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

[sbrannen]

Overview

JDK 20 adopted Unicode CLDR-14032 (Common Locale Data Repository) which changed the space character that precedes the period (AM or PM) in formatted date/time text from a standard space (" ") to a narrow non-breaking space (NNBSP: "\u202F"). Consequently, applications that rely on date/time parsing and formatting may encounter incompatible changes in behavior when using Spring on Java 20 or higher -- for example, web applications that make use of @DateTimeFormat.

On JDK 20, 21, and 22, applications can use the -Djava.locale.providers=COMPAT command-line argument for java in order to force the use of legacy locale data which uses a standard space for the space character that precedes the period in formatted date/time text.

Support for the aforementioned COMPAT mode has been removed in JDK 23; however, the Java team has introduced support for lenient parsing of space characters in JDK 23. This applies to SimpleDateFormat as well as DateTimeFormatter.

SimpleDateFormat and DateTimeFormatter Configuration

SimpleDateFormat is lenient by default; however, DateTimeFormatter instances are not lenient by default, and factory methods like DateTimeFormatter.ofLocalizedTime(...) do not create lenient formatters.

To create a lenient DateTimeFormatter, one must forgo the use of the static factory methods in DateTimeFormatter and instead make use of the DateTimeFormatterBuilder. The following example shows how to create a static factory method for a lenient DateTimeFormatter that is comparable to what DateTimeFormatter.ofLocalizedDateTime(FormatStyle, FormatStyle) produces.

pubic static DateTimeFormatter createLenientDateTimeFormatter(
         FormatStyle dateStyle, FormatStyle timeStyle) {

   return new DateTimeFormatterBuilder()
         .parseLenient()
         .appendLocalized(dateStyle, timeStyle)
         .toFormatter()
         .withChronology(IsoChronology.INSTANCE);
}

Proposal

In Spring Framework, we do not plan to introduce additional support for lenient parsing of dates using AM/PM in conjunction with @DateTimeFormat. We also do not plan to introduce additional support to control the format used when rendering/printing String representations of dates or times.

Rather, we will document the options that Spring provides to assist developers who encounter date/time parsing and formatting issues, and we will refer developers to the updated documentation in JEP 252 provided by the JDK team.

For example, @DateTimeFormat already provides support for fallback patterns that allow for lenient parsing of date/time inputs.

Related Resources

• https://openjdk.org/jeps/252
• https://jdk.java.net/20/release-notes#JDK-8284840
• https://unicode-org.atlassian.net/browse/CLDR-14032
• https://bugs.openjdk.org/browse/JDK-8223587
• https://bugs.openjdk.org/browse/JDK-8284840
• https://bugs.openjdk.org/browse/JDK-8297316
• https://bugs.openjdk.org/browse/JDK-8304925
• https://bugs.openjdk.org/browse/JDK-8324665

Related Issues

• Ensure compatibility with JDK 20 #30185
• Adapt Date/Time formatting tests to accommodate narrow non-breaking spaces #33144
• Support lenient parsing for dates using AM/PM in conjunction with @DateTimeFormat #30649
• Different behavior of the @DateTimeFormat when running on Local env and on Cloud env (Heroku) spring-boot#42430

[sbrannen]

Rather, we will document the options that Spring provides to assist developers who encounter date/time parsing and formatting issues, and we will refer developers to the updated documentation in JEP 252 provided by the JDK team.

Javadoc and the reference guide have been updated in bfde33a, and a new Date and Time Formatting with JDK 20 and higher wiki page has been introduced as well.