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

Revised format annotation docs

Browse Source
This commit is contained in:
Juergen Hoeller
2018-12-13 17:19:50 +01:00
parent 112cc70231
commit aab421167b
3 changed files with 33 additions and 32 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}

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

@@ -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<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]
@@ -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: