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

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

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}.
*