root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Document options for Date/Time parsing & formatting issues with JDK 20+ 

This commit updates Javadoc and the reference guide to document options
for handling date/time parsing and formatting issues on JDK 20 and higher.

A new "Date and Time Formatting with JDK 20 and higher" page has also been
introduced in the wiki.

https://github.com/spring-projects/spring-framework/wiki/Date-and-Time-Formatting-with-JDK-20-and-higher

Closes gh-33151
This commit is contained in:
Sam Brannen 2024-11-13 16:39:40 +01:00
parent 14b9865de7
commit bfde33a514
4 changed files with 40 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
framework-docs/modules/ROOT/pages/core/validation/format.adoc
View File

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

2
framework-docs/modules/ROOT/pages/web/webflux/config.adoc
View File

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

2
framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc
View File

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

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

@ -28,17 +28,27 @@ import java.lang.annotation.Target;
* <p>Formatting applies to parsing a date/time object from a string as well as printing a
* date/time object to a string.
*
* <p>Supports formatting by style pattern, ISO date time pattern, or custom format pattern string.
* <p>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.
*
* <p>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 '-' &mdash; 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}.
*
* <p><strong>WARNING</strong>: 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
* <a href="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</a> page in the Spring Framework wiki.
*
* <p>For ISO-based formatting, set the {@link #iso} attribute to the desired {@link ISO} format,
* such as {@link ISO#DATE}.
*