Improve docs on date and time formatting

Closes gh-24370

src/docs/asciidoc/core/core-validation.adoc

@@ -1693,18 +1693,18 @@ See <<web.adoc#mvc-config-conversion, Conversion and Formatting>> in the Spring
 [[format-configuring-formatting-globaldatetimeformat]]
 == Configuring a Global Date and Time Format
 
-By default, date and time fields that are not annotated with `@DateTimeFormat` are
+By default, date and time fields not annotated with `@DateTimeFormat` are converted from
-converted from strings by using the `DateFormat.SHORT` style. If you prefer, you can
+strings by using the `DateFormat.SHORT` style. If you prefer, you can change this by
-change this by defining your own global format.
+defining your own global format.
 
-To do so, you need to ensure that Spring does not register default formatters. Instead,
+To do that, ensure that Spring does not register default formatters. Instead, register
-you should register all formatters manually. Use the
+formatters manually with the help of:
-`org.springframework.format.datetime.joda.JodaTimeFormatterRegistrar` or
-`org.springframework.format.datetime.DateFormatterRegistrar` class, depending on whether
-you use the Joda-Time library.
 
-For example, the following Java configuration registers a global `yyyyMMdd`
+* `org.springframework.format.datetime.standard.DateTimeFormatterRegistrar`
-format (this example does not depend on the Joda-Time library):
+* `org.springframework.format.datetime.DateFormatterRegistrar`, or
+`org.springframework.format.datetime.joda.JodaTimeFormatterRegistrar` for Joda-Time.
+
+For example, the following Java configuration registers a global `yyyyMMdd` format:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -1721,6 +1721,11 @@ format (this example does not depend on the Joda-Time library):
 			// Ensure @NumberFormat is still supported
 			conversionService.addFormatterForFieldAnnotation(new NumberFormatAnnotationFormatterFactory());
 
+			// Register JSR-310 date conversion with a specific global format
+			DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
+			registrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyyMMdd"));
+			registrar.registerFormatters(conversionService);
+
 			// Register date conversion with a specific global format
 			DateFormatterRegistrar registrar = new DateFormatterRegistrar();
 			registrar.setFormatter(new DateFormatter("yyyyMMdd"));
@@ -1740,8 +1745,15 @@ format (this example does not depend on the Joda-Time library):
 		fun conversionService(): FormattingConversionService {
 			// Use the DefaultFormattingConversionService but do not register defaults
 			return DefaultFormattingConversionService(false).apply {
+
 				// Ensure @NumberFormat is still supported
 				addFormatterForFieldAnnotation(NumberFormatAnnotationFormatterFactory())
+
+				// Register JSR-310 date conversion with a specific global format
+				val registrar = DateTimeFormatterRegistrar()
+				registrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyyMMdd"))
+				registrar.registerFormatters(this)
+
 				// Register date conversion with a specific global format
 				val registrar = DateFormatterRegistrar()
 				registrar.setFormatter(DateFormatter("yyyyMMdd"))
@@ -1786,18 +1798,10 @@ Time):
 	</beans>
 ----
 
-NOTE: Joda-Time provides separate distinct types to represent `date`, `time`, and `date-time`
+Note there are extra considerations when configuring date and time formats in web
-values. The `dateFormatter`, `timeFormatter`, and `dateTimeFormatter` properties of the
+applications. Please see
-`JodaTimeFormatterRegistrar` should be used to configure the different formats for each
+<<web.adoc#mvc-config-conversion, WebMVC Conversion and Formatting>> or
-type. The `DateTimeFormatterFactoryBean` provides a convenient way to create formatters.
+<<web-reactive.adoc#webflux-config-conversion, WebFlux Conversion and Formatting>>.
-
-NOTE: If you use Spring MVC, remember to explicitly configure the conversion service that
-is used. For Java-based `@Configuration`, this means extending the
-`WebMvcConfigurationSupport` class and overriding the `mvcConversionService()` method.
-For XML, you should use the `conversion-service` attribute of the
-`mvc:annotation-driven` element.
-See <<web.adoc#mvc-config-conversion, Conversion and Formatting>> for details.
-
 
 
 

src/docs/asciidoc/web/webflux.adoc

@@ -3691,11 +3691,10 @@ class WebConfig : WebFluxConfigurer {
 === Conversion, formatting
 [.small]#<<web.adoc#mvc-config-conversion, Web MVC>>#
 
-By default, formatters for `Number` and `Date` types are installed, including support for
+By default, formatters for various number and date types are installed, along with support
-the `@NumberFormat` and `@DateTimeFormat` annotations. Full support for the Joda-Time
+for customization via `@NumberFormat` and `@DateTimeFormat` on fields.
-formatting library is also installed if Joda-Time is present on the classpath.
 
-The following example shows how to register custom formatters and converters:
+To register custom formatters and converters in Java config, use the following:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -3724,6 +3723,41 @@ The following example shows how to register custom formatters and converters:
 	}
 ----
 
+By default Spring WebFlux considers the request Locale when parsing and formatting date
+values. This works for forms where dates are represented as Strings with "input" form
+fields. For "date" and "time" form fields, however, browsers use a fixed format defined
+in the HTML spec. For such cases date and time formatting can be customized as follows:
+
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+.Java
+----
+	@Configuration
+	@EnableWebFlux
+	public class WebConfig implements WebFluxConfigurer {
+
+		@Override
+		public void addFormatters(FormatterRegistry registry) {
+			DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
+			registrar.setUseIsoFormat(true);
+			registrar.registerFormatters(registry);
+      	}
+	}
+----
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
+.Kotlin
+----
+	@Configuration
+	@EnableWebFlux
+	class WebConfig : WebFluxConfigurer {
+
+		override fun addFormatters(registry: FormatterRegistry) {
+			val registrar = DateTimeFormatterRegistrar()
+			registrar.setUseIsoFormat(true)
+			registrar.registerFormatters(registry)
+		}
+	}
+----
+
 NOTE: See <<core.adoc#format-FormatterRegistrar-SPI, `FormatterRegistrar` SPI>>
 and the `FormattingConversionServiceFactoryBean` for more information on when to
 use `FormatterRegistrar` implementations.

src/docs/asciidoc/web/webmvc.adoc

@@ -4977,12 +4977,10 @@ sub-elements are available.
 === Type Conversion
 [.small]#<<web-reactive.adoc#webflux-config-conversion, WebFlux>>#
 
-By default formatters, for `Number` and `Date` types are installed, including support for
+By default, formatters for various number and date types are installed, along with support
-the `@NumberFormat` and `@DateTimeFormat` annotations. Full support for the Joda-Time
+for customization via `@NumberFormat` and `@DateTimeFormat` on fields.
-formatting library is also installed if Joda-Time is present on the classpath.
 
-In Java configuration, you can register custom formatters and converters, as the
+To register custom formatters and converters in Java config, use the following:
-following example shows:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -5010,7 +5008,7 @@ following example shows:
 	}
 ----
 
-The following example shows how to achieve the same configuration in XML:
+To do the same in XML config, use the following:
 
 [source,xml,indent=0,subs="verbatim,quotes"]
 ----
@@ -5049,6 +5047,41 @@ The following example shows how to achieve the same configuration in XML:
 	</beans>
 ----
 
+By default Spring MVC considers the request Locale when parsing and formatting date
+values. This works for forms where dates are represented as Strings with "input" form
+fields. For "date" and "time" form fields, however, browsers use a fixed format defined
+in the HTML spec. For such cases date and time formatting can be customized as follows:
+
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+.Java
+----
+	@Configuration
+	@EnableWebMvc
+	public class WebConfig implements WebMvcConfigurer {
+
+		@Override
+		public void addFormatters(FormatterRegistry registry) {
+			DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
+			registrar.setUseIsoFormat(true);
+			registrar.registerFormatters(registry);
+      	}
+	}
+----
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
+.Kotlin
+----
+	@Configuration
+	@EnableWebMvc
+	class WebConfig : WebMvcConfigurer {
+
+		override fun addFormatters(registry: FormatterRegistry) {
+			val registrar = DateTimeFormatterRegistrar()
+			registrar.setUseIsoFormat(true)
+			registrar.registerFormatters(registry)
+		}
+	}
+----
+
 NOTE: See <<core.adoc#format-FormatterRegistrar-SPI, the `FormatterRegistrar` SPI>>
 and the `FormattingConversionServiceFactoryBean` for more information on when to use
 FormatterRegistrar implementations.