diff --git a/spring-context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java b/spring-context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java index 956099d012a..efe7cf0b550 100644 --- a/spring-context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java +++ b/spring-context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 the original author or authors. + * Copyright 2002-2018 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -26,8 +26,8 @@ import java.lang.annotation.Target; * Declares that a field or method parameter should be formatted as a date or time. * *

Supports formatting by style pattern, ISO date time pattern, or custom format pattern string. - * Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code java.lang.Long}, - * Joda-Time value types; and as of Spring 4 and JDK 8, to JSR-310 java.time types too. + * Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code Long} (for + * millisecond timestamps) as well as JSR-310 java.time and Joda-Time value types. * *

For style-based formatting, set the {@link #style} attribute to be the style pattern code. * The first character of the code is the date style, and the second character is the time style. @@ -48,6 +48,7 @@ import java.lang.annotation.Target; * @author Keith Donald * @author Juergen Hoeller * @since 3.0 + * @see java.time.format.DateTimeFormatter * @see org.joda.time.format.DateTimeFormat */ @Documented diff --git a/spring-context/src/main/java/org/springframework/format/annotation/NumberFormat.java b/spring-context/src/main/java/org/springframework/format/annotation/NumberFormat.java index 3424143ec59..d8cf43904a8 100644 --- a/spring-context/src/main/java/org/springframework/format/annotation/NumberFormat.java +++ b/spring-context/src/main/java/org/springframework/format/annotation/NumberFormat.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 the original author or authors. + * Copyright 2002-2018 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -25,8 +25,8 @@ import java.lang.annotation.Target; /** * Declares that a field or method parameter should be formatted as a number. * - *

Supports formatting by style or custom pattern string. - * Can be applied to any JDK {@code java.lang.Number} type. + *

Supports formatting by style or custom pattern string. Can be applied + * to any JDK {@code Number} type such as {@code Double} and {@code Long}. * *

For style-based formatting, set the {@link #style} attribute to be the * desired {@link Style}. For custom formatting, set the {@link #pattern} diff --git a/src/docs/asciidoc/core/core-validation.adoc b/src/docs/asciidoc/core/core-validation.adoc index 107f8ed253c..b83ce0acc20 100644 --- a/src/docs/asciidoc/core/core-validation.adoc +++ b/src/docs/asciidoc/core/core-validation.adoc @@ -363,11 +363,10 @@ the knowledge of how to convert properties to the desired type. For more about A couple of examples where property editing is used in Spring: -* Setting properties on beans is done by using `PropertyEditor` implementations. When you use - `java.lang.String` as the value of a property of some bean that you declare in an XML - file, Spring (if the setter of the corresponding property has a - `Class` parameter) uses `ClassEditor` to try to resolve the parameter to a `Class` - object. +* Setting properties on beans is done by using `PropertyEditor` implementations. + When you use `String` as the value of a property of some bean that you declare + in an XML file, Spring (if the setter of the corresponding property has a `Class` + parameter) uses `ClassEditor` to try to resolve the parameter to a `Class` object. * Parsing HTTP request parameters in Spring's MVC framework is done by using all kinds of `PropertyEditor` implementations that you can manually bind in all subclasses of the `CommandController`. @@ -789,8 +788,8 @@ The following listing shows the `StringToInteger` class, which is a typical `Con [[core-convert-ConverterFactory-SPI]] === Using `ConverterFactory` -When you need to centralize the conversion logic for an entire class hierarchy (for -example, when converting from String to java.lang.Enum objects), you can implement +When you need to centralize the conversion logic for an entire class hierarchy +(for example, when converting from `String` to `Enum` objects), you can implement `ConverterFactory`, as the following example shows: ==== @@ -807,10 +806,10 @@ example, when converting from String to java.lang.Enum objects), you can impleme ==== Parameterize S to be the type you are converting from and R to be the base type defining -the __range__ of classes you can convert to. Then implement getConverter(Class), +the __range__ of classes you can convert to. Then implement `getConverter(Class)`, where T is a subclass of R. -Consider the `StringToEnum` `ConverterFactory` as an example: +Consider the `StringToEnumConverterFactory` as an example: ==== [source,java,indent=0] @@ -845,13 +844,13 @@ Consider the `StringToEnum` `ConverterFactory` as an example: [[core-convert-GenericConverter-SPI]] === Using `GenericConverter` -When you require a sophisticated `Converter` implementation, consider using the `GenericConverter` -interface. With a more flexible but less strongly typed signature than `Converter`, a `GenericConverter` -supports converting between multiple source and target types. In addition, a -`GenericConverter` makes available source and target field context that you can use when -you implement your conversion logic. Such context lets a type conversion be driven -by a field annotation or by generic information declared on a field signature. The -following listing shows the interface definition of `GenericConverter`: +When you require a sophisticated `Converter` implementation, consider using the +`GenericConverter` interface. With a more flexible but less strongly typed signature +than `Converter`, a `GenericConverter` supports converting between multiple source and +target types. In addition, a `GenericConverter` makes available source and target field +context that you can use when you implement your conversion logic. Such context lets a +type conversion be driven by a field annotation or by generic information declared on a +field signature. The following listing shows the interface definition of `GenericConverter`: ==== [source,java,indent=0] @@ -1088,10 +1087,10 @@ directly. To directly address them, Spring 3 introduced a convenient `Formatter` provides a simple and robust alternative to `PropertyEditor` implementations for client environments. In general, you can use the `Converter` SPI when you need to implement general-purpose type -conversion logic -- for example, for converting between a `java.util.Date` and a -`java.lang.Long`. You can use the `Formatter` SPI when you work in a client environment (such -as a web application) and need to parse and print localized field values. The -`ConversionService` provides a unified type conversion API for both SPIs. +conversion logic -- for example, for converting between a `java.util.Date` and a `Long`. +You can use the `Formatter` SPI when you work in a client environment (such as a web +application) and need to parse and print localized field values. The `ConversionService` +provides a unified type conversion API for both SPIs. @@ -1147,7 +1146,7 @@ care to ensure that your `Formatter` implementation is thread-safe. The `format` subpackages provide several `Formatter` implementations as a convenience. The `number` package provides `NumberStyleFormatter`, `CurrencyStyleFormatter`, and -`PercentStyleFormatter` to format `java.lang.Number` objects that use a `java.text.NumberFormat`. +`PercentStyleFormatter` to format `Number` objects that use a `java.text.NumberFormat`. The `datetime` package provides a `DateFormatter` to format `java.util.Date` objects with a `java.text.DateFormat`. The `datetime.joda` package provides comprehensive datetime formatting support based on the http://joda-time.sourceforge.net[Joda-Time library]. @@ -1291,8 +1290,9 @@ example shows: ==== Format Annotation API A portable format annotation API exists in the `org.springframework.format.annotation` -package. You can use `@NumberFormat` to format java.lang.Number fields and `@DateTimeFormat` to -format `java.util.Date`, `java.util.Calendar`, `java.util.Long`, or Joda-Time fields. +package. You can use `@NumberFormat` to format `Number` fields such as `Double` and +`Long`, and `@DateTimeFormat` to format `java.util.Date`, `java.util.Calendar`, `Long` +(for millisecond timestamps) as well as JSR-310 `java.time` and Joda-Time value types. The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date (yyyy-MM-dd): @@ -1316,9 +1316,9 @@ The following example uses `@DateTimeFormat` to format a `java.util.Date` as an The `FormatterRegistry` is an SPI for registering formatters and converters. `FormattingConversionService` is an implementation of `FormatterRegistry` suitable for -most environments. You can programmatically or declaratively configure this implementation -as a Spring bean by using `FormattingConversionServiceFactoryBean`. Because -this implementation also implements `ConversionService`, you can directly configure it +most environments. You can programmatically or declaratively configure this variant +as a Spring bean, e.g. by using `FormattingConversionServiceFactoryBean`. Because this +implementation also implements `ConversionService`, you can directly configure it for use with Spring's `DataBinder` and the Spring Expression Language (SpEL). The following listing shows the `FormatterRegistry` SPI: