Document options for handling Date/Time parsing 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 lenient support for parsing dates using AM/PM in conjunction with @DateTimeFormat. 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.

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

• #30185
• #33144
• #30649
• https://github.com/spring-projects/spring-boot/issues/42430