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 956099d012..efe7cf0b55 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 3424143ec5..d8cf43904a 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 46a14c40e0..826dfaa932 100644 --- a/src/docs/asciidoc/core/core-validation.adoc +++ b/src/docs/asciidoc/core/core-validation.adoc @@ -362,10 +362,9 @@ the knowledge of how to convert properties to the desired type. Read more about A couple of examples where property editing is used in Spring: * __setting properties on beans__ is done using `PropertyEditors`. When mentioning - `java.lang.String` as the value of a property of some bean you're declaring in XML - file, Spring will (if the setter of the corresponding property has a - `Class`-parameter) use the `ClassEditor` to try to resolve the parameter to a `Class` - object. + `String` as the value of a property of some bean you're declaring in XML file, + Spring will (if the setter of the corresponding property has `Class` parameter) + use the `ClassEditor` to try to resolve the parameter to a `Class` object. * __parsing HTTP request parameters__ in Spring's MVC framework is done using all kinds of `PropertyEditors` that you can manually bind in all subclasses of the `CommandController`. @@ -761,9 +760,9 @@ Consider `StringToInteger` as an example for a typical `Converter` implementatio [[core-convert-ConverterFactory-SPI]] === 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, implement -`ConverterFactory`: +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: [source,java,indent=0] [subs="verbatim,quotes"] @@ -777,10 +776,10 @@ example, when converting from String to java.lang.Enum objects, implement ---- 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] [subs="verbatim,quotes"] @@ -813,12 +812,13 @@ Consider the `StringToEnum` ConverterFactory as an example: [[core-convert-GenericConverter-SPI]] === GenericConverter -When you require a sophisticated Converter implementation, consider the GenericConverter -interface. With a more flexible but less strongly typed signature, a GenericConverter -supports converting between multiple source and target types. In addition, a -GenericConverter makes available source and target field context you can use when -implementing your conversion logic. Such context allows a type conversion to be driven -by a field annotation, or generic information declared on a field signature. +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] [subs="verbatim,quotes"] @@ -833,22 +833,22 @@ by a field annotation, or generic information declared on a field signature. } ---- -To implement a GenericConverter, have getConvertibleTypes() return the supported -source->target type pairs. Then implement convert(Object, TypeDescriptor, -TypeDescriptor) to implement your conversion logic. The source TypeDescriptor provides -access to the source field holding the value being converted. The target TypeDescriptor -provides access to the target field where the converted value will be set. +To implement a `GenericConverter`, have `getConvertibleTypes()` return the supported +source->target type pairs. Then implement `convert(Object, TypeDescriptor, +TypeDescriptor)` to contain your conversion logic. The source `TypeDescriptor` provides +access to the source field that holds the value being converted. The target `TypeDescriptor` +provides access to the target field where the converted value is to be set. -A good example of a GenericConverter is a converter that converts between a Java Array -and a Collection. Such an ArrayToCollectionConverter introspects the field that declares -the target Collection type to resolve the Collection's element type. This allows each -element in the source array to be converted to the Collection element type before the -Collection is set on the target field. +A good example of a `GenericConverter` is a converter that converts between a Java array +and a collection. Such an `ArrayToCollectionConverter` introspects the field that declares +the target collection type to resolve the collection's element type. This lets each +element in the source array be converted to the collection element type before the +collection is set on the target field. [NOTE] ==== -Because GenericConverter is a more complex SPI interface, only use it when you need it. -Favor Converter or ConverterFactory for basic type conversion needs. +Because `GenericConverter` is a more complex SPI interface, only use it when you need it. +Favor `Converter` or `ConverterFactory` for basic type conversion needs. ==== @@ -1044,11 +1044,11 @@ general __core.convert__ Converter SPI does not address such __formatting__ requ directly. To directly address them, Spring 3 introduces a convenient Formatter SPI that provides a simple and robust alternative to PropertyEditors for client environments. -In general, use the Converter SPI when you need to implement general-purpose type -conversion logic; for example, for converting between a java.util.Date and and -java.lang.Long. Use the Formatter SPI when you're working 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. +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 `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. @@ -1088,22 +1088,22 @@ Where Formatter extends from the Printer and Parser building-block interfaces: } ---- -To create your own Formatter, simply implement the Formatter interface above. -Parameterize T to be the type of object you wish to format, for example, -`java.util.Date`. Implement the `print()` operation to print an instance of T for +To create your own `Formatter`, implement the `Formatter` interface shown earlier. +Parameterize `T` to be the type of object you wish to format -- for example, +`java.util.Date`. Implement the `print()` operation to print an instance of `T` for display in the client locale. Implement the `parse()` operation to parse an instance of -T from the formatted representation returned from the client locale. Your Formatter -should throw a ParseException or IllegalArgumentException if a parse attempt fails. Take -care to ensure your Formatter implementation is thread-safe. +`T` from the formatted representation returned from the client locale. Your `Formatter` +should throw a `ParseException` or an `IllegalArgumentException` if a parse attempt fails. Take +care to ensure that your `Formatter` implementation is thread-safe. -Several Formatter implementations are provided in `format` subpackages as a convenience. -The `number` package provides a `NumberStyleFormatter`, `CurrencyStyleFormatter`, and -`PercentStyleFormatter` to format `java.lang.Number` objects using a `java.text.NumberFormat`. +The `format` subpackages provide several `Formatter` implementations as a convenience. +The `number` package provides `NumberStyleFormatter`, `CurrencyStyleFormatter`, and +`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]. -Consider `DateFormatter` as an example `Formatter` implementation: +The following `DateFormatter` is an example `Formatter` implementation: [source,java,indent=0] [subs="verbatim,quotes"] @@ -1230,10 +1230,11 @@ To trigger formatting, simply annotate fields with @NumberFormat: ==== Format Annotation API A portable format annotation API exists in the `org.springframework.format.annotation` -package. Use @NumberFormat to format java.lang.Number fields. Use @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 example below uses @DateTimeFormat to format a java.util.Date as a ISO Date +The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date (yyyy-MM-dd): [source,java,indent=0]