Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revised format annotation docs

Browse Source 
(cherry picked from commit aab421167b)
This commit is contained in:
Juergen Hoeller
2018-12-13 17:19:50 +01:00
parent 1b26f2fb31
commit 62885a1922
3 changed files with 53 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
spring-context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java
View File

@@ -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.
*
* <p>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 <code>java.time</code> types too.
* Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code Long} (for
* millisecond timestamps) as well as JSR-310 <code>java.time</code> and Joda-Time value types.
*
* <p>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

6
spring-context/src/main/java/org/springframework/format/annotation/NumberFormat.java
View File

@@ -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.
*
* <p>Supports formatting by style or custom pattern string.
* Can be applied to any JDK {@code java.lang.Number} type.
* <p>Supports formatting by style or custom pattern string. Can be applied
* to any JDK {@code Number} type such as {@code Double} and {@code Long}.
*
* <p>For style-based formatting, set the {@link #style} attribute to be the
* desired {@link Style}. For custom formatting, set the {@link #pattern}

91
src/docs/asciidoc/core/core-validation.adoc
View File

@@ -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<T>),
the __range__ of classes you can convert to. Then implement `getConverter(Class<T>)`,
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]