diff --git a/framework-docs/modules/ROOT/pages/core/validation/format.adoc b/framework-docs/modules/ROOT/pages/core/validation/format.adoc index 4ac313d3f298..1300bf3a5821 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format.adoc @@ -280,10 +280,11 @@ Kotlin:: A portable format annotation API exists in the `org.springframework.format.annotation` 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`. +`Long`, and `@DateTimeFormat` to format fields such as `java.util.Date`, +`java.util.Calendar`, and `Long` (for millisecond timestamps) as well as JSR-310 +`java.time` types. -The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date +The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO date (yyyy-MM-dd): [tabs] @@ -309,6 +310,28 @@ Kotlin:: ---- ====== +For further details, see the javadoc for +{spring-framework-api}/format/annotation/DateTimeFormat.html[`@DateTimeFormat`] and +{spring-framework-api}/format/annotation/NumberFormat.html[`@NumberFormat`]. + +[WARNING] +==== +Style-based formatting and parsing rely on locale-sensitive patterns which may change +depending on the Java runtime. Specifically, applications that rely on date, time, or +number parsing and formatting may encounter incompatible changes in behavior when running +on JDK 20 or higher. + +Using an ISO standardized format or a concrete pattern that you control allows for +reliable system-independent and locale-independent parsing and formatting of date, time, +and number values. + +For `@DateTimeFormat`, the use of fallback patterns can also help to address +compatibility issues. + +For further details, see the +https://github.com/spring-projects/spring-framework/wiki/Date-and-Time-Formatting-with-JDK-20-and-higher[Date and Time Formatting with JDK 20 and higher] +page in the Spring Framework wiki. +==== [[format-FormatterRegistry-SPI]] == The `FormatterRegistry` SPI diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc index bef72ec172b2..2e7438b2d8d3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc @@ -91,7 +91,7 @@ class WebConfig : WebFluxConfigurer { [.small]#xref:web/webmvc/mvc-config/conversion.adoc[See equivalent in the Servlet stack]# By default, formatters for various number and date types are installed, along with support -for customization via `@NumberFormat` and `@DateTimeFormat` on fields. +for customization via `@NumberFormat` and `@DateTimeFormat` on fields and parameters. To register custom formatters and converters in Java config, use the following: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc index 35d0998934de..bce9b2e137ce 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc @@ -4,7 +4,7 @@ [.small]#xref:web/webflux/config.adoc#webflux-config-conversion[See equivalent in the Reactive stack]# By default, formatters for various number and date types are installed, along with support -for customization via `@NumberFormat` and `@DateTimeFormat` on fields. +for customization via `@NumberFormat` and `@DateTimeFormat` on fields and parameters. To register custom formatters and converters in Java config, use the following: 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 39fc7ba929f1..bb542896c2ee 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 @@ -28,17 +28,27 @@ *

Formatting applies to parsing a date/time object from a string as well as printing a * date/time object to a string. * - *

Supports formatting by style pattern, ISO date time pattern, or custom format pattern string. + *

Supports formatting by style pattern, ISO date/time pattern, or custom format pattern string. * Can be applied to {@link java.util.Date}, {@link java.util.Calendar}, {@link Long} (for * millisecond timestamps) as well as JSR-310 {@code java.time} value types. * *

For style-based formatting, set the {@link #style} attribute to the desired style pattern code. * The first character of the code is the date style, and the second character is the time style. * Specify a character of 'S' for short style, 'M' for medium, 'L' for long, and 'F' for full. - * The date or time may be omitted by specifying the style character '-' — for example, + * The date or time may be omitted by specifying the style character '-'. For example, * 'M-' specifies a medium format for the date with no time. The supported style pattern codes * correlate to the enum constants defined in {@link java.time.format.FormatStyle}. * + *

WARNING: Style-based formatting and parsing rely on locale-sensitive + * patterns which may change depending on the Java runtime. Specifically, applications that + * rely on date/time parsing and formatting may encounter incompatible changes in behavior + * when running on JDK 20 or higher. Using an ISO standardized format or a concrete pattern + * that you control allows for reliable system-independent and locale-independent parsing and + * formatting of date/time values. The use of {@linkplain #fallbackPatterns() fallback patterns} + * can also help to address compatibility issues. For further details, see the + * + * Date and Time Formatting with JDK 20 and higher page in the Spring Framework wiki. + * *

For ISO-based formatting, set the {@link #iso} attribute to the desired {@link ISO} format, * such as {@link ISO#DATE}. *