Support multiple parsing patterns in @DateTimeFormat

Prior to this commit, @DateTimeFormat only supported a single format
for parsing date time values via the style, iso, and pattern attributes.

This commit introduces a new fallbackPatterns attribute that can be
used to configure multiple fallback patterns for parsing date time
values. This allows applications to accept multiple input formats for
date time values.

For example, if you wish to use the ISO date format for parsing and
printing but allow for lenient parsing of user input for various
additional date formats, you could annotate a field or method parameter
with configuration similar to the following.

    @DateTimeFormat(
        iso = ISO.DATE,
        fallbackPatterns = { "M/d/yy", "dd.MM.yyyy" }
    )

Closes gh-20292

Author: sbrannen

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

@@ -26,17 +26,20 @@
  * Declares that a field or method parameter should be formatted as a date or time.
  *
  * <p>Supports formatting by style pattern, ISO date time pattern, or custom format pattern string.
- * Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code Long} (for
- * millisecond timestamps) as well as JSR-310 <code>java.time</code> and Joda-Time value types.
+ * 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} and Joda-Time value types.
  *
- * <p>For style-based formatting, set the {@link #style} attribute to be the style pattern code.
+ * <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.
- * A date or time may be omitted by specifying the style character '-'.
+ * The date or time may be omitted by specifying the style character '-' &mdash; for example,
+ * 'M-' specifies a medium format for the date with no time.
  *
- * <p>For ISO-based formatting, set the {@link #iso} attribute to be the desired {@link ISO} format,
- * such as {@link ISO#DATE}. For custom formatting, set the {@link #pattern} attribute to be the
- * DateTime pattern, such as {@code "yyyy/MM/dd hh:mm:ss a"}.
+ * <p>For ISO-based formatting, set the {@link #iso} attribute to the desired {@link ISO} format,
+ * such as {@link ISO#DATE}.
+ *
+ * <p>For custom formatting, set the {@link #pattern} attribute to a date time pattern, such as
+ * {@code "yyyy/MM/dd hh:mm:ss a"}.
  *
  * <p>Each attribute is mutually exclusive, so only set one attribute per annotation instance
  * (the one most convenient for your formatting needs).
@@ -48,8 +51,19 @@
  * with a style code of 'SS' (short date, short time).</li>
  * </ul>
  *
+ * <h3>Time Zones</h3>
+ * <p>Whenever the {@link #style} or {@link #pattern} attribute is used, the
+ * {@linkplain java.util.TimeZone#getDefault() default time zone} of the JVM will
+ * be used when formatting {@link java.util.Date} values. Whenever the {@link #iso}
+ * attribute is used when formatting {@link java.util.Date} values, {@code UTC}
+ * will be used as the time zone. The same time zone will be applied to any
+ * {@linkplain #fallbackPatterns fallback patterns} as well. In order to enforce
+ * consistent use of {@code UTC} as the time zone, you can bootstrap the JVM with
+ * {@code -Duser.timezone=UTC}.
+ *
  * @author Keith Donald
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.0
  * @see java.time.format.DateTimeFormatter
  * @see org.joda.time.format.DateTimeFormat
@@ -60,55 +74,80 @@
 public @interface DateTimeFormat {
 
 	/**
-	 * The style pattern to use to format the field.
-	 * <p>Defaults to 'SS' for short date time. Set this attribute when you wish to format
-	 * your field in accordance with a common style other than the default style.
+	 * The style pattern to use to format the field or method parameter.
+	 * <p>Defaults to 'SS' for short date, short time. Set this attribute when you
+	 * wish to format your field or method parameter in accordance with a common
+	 * style other than the default style.
+	 * @see #fallbackPatterns
 	 */
 	String style() default "SS";
 
 	/**
-	 * The ISO pattern to use to format the field.
-	 * <p>The possible ISO patterns are defined in the {@link ISO} enum.
+	 * The ISO pattern to use to format the field or method parameter.
+	 * <p>Supported ISO patterns are defined in the {@link ISO} enum.
 	 * <p>Defaults to {@link ISO#NONE}, indicating this attribute should be ignored.
-	 * Set this attribute when you wish to format your field in accordance with an ISO format.
+	 * Set this attribute when you wish to format your field or method parameter
+	 * in accordance with an ISO format.
+	 * @see #fallbackPatterns
 	 */
 	ISO iso() default ISO.NONE;
 
 	/**
-	 * The custom pattern to use to format the field.
-	 * <p>Defaults to empty String, indicating no custom pattern String has been specified.
-	 * Set this attribute when you wish to format your field in accordance with a custom
-	 * date time pattern not represented by a style or ISO format.
+	 * The custom pattern to use to format the field or method parameter.
+	 * <p>Defaults to empty String, indicating no custom pattern String has been
+	 * specified. Set this attribute when you wish to format your field or method
+	 * parameter in accordance with a custom date time pattern not represented by
+	 * a style or ISO format.
 	 * <p>Note: This pattern follows the original {@link java.text.SimpleDateFormat} style,
 	 * as also supported by Joda-Time, with strict parsing semantics towards overflows
 	 * (e.g. rejecting a Feb 29 value for a non-leap-year). As a consequence, 'yy'
 	 * characters indicate a year in the traditional style, not a "year-of-era" as in the
 	 * {@link java.time.format.DateTimeFormatter} specification (i.e. 'yy' turns into 'uu'
-	 * when going through that {@code DateTimeFormatter} with strict resolution mode).
+	 * when going through a {@code DateTimeFormatter} with strict resolution mode).
+	 * @see #fallbackPatterns
 	 */
 	String pattern() default "";
 
+	/**
+	 * The set of custom patterns to use as a fallback in case parsing fails for
+	 * the primary {@link #pattern}, {@link #iso}, or {@link #style} attribute.
+	 * <p>For example, if you wish to use the ISO date format for parsing and
+	 * printing but allow for lenient parsing of user input for various date
+	 * formats, you could configure something similar to the following.
+	 * <pre style="code">
+	 * {@literal @}DateTimeFormat(iso = ISO.DATE, fallbackPatterns = { "M/d/yy", "dd.MM.yyyy" })
+	 * </pre>
+	 * <p>Fallback patterns are only used for parsing. They are not used for
+	 * printing the value as a String. The primary {@link #pattern}, {@link #iso},
+	 * or {@link #style} attribute is always used for printing. For details on
+	 * which time zone is used for fallback patterns, see the
+	 * {@linkplain DateTimeFormat class-level documentation}.
+	 * <p>Fallback patterns are not supported for Joda-Time value types.
+	 * @since 5.3.5
+	 */
+	String[] fallbackPatterns() default {};
+
 
 	/**
 	 * Common ISO date time format patterns.
 	 */
 	enum ISO {
 
 		/**
-		 * The most common ISO Date Format {@code yyyy-MM-dd},
-		 * e.g. "2000-10-31".
+		 * The most common ISO Date Format {@code yyyy-MM-dd} &mdash; for example,
+		 * "2000-10-31".
 		 */
 		DATE,
 
 		/**
-		 * The most common ISO Time Format {@code HH:mm:ss.SSSXXX},
-		 * e.g. "01:30:00.000-05:00".
+		 * The most common ISO Time Format {@code HH:mm:ss.SSSXXX} &mdash; for example,
+		 * "01:30:00.000-05:00".
 		 */
 		TIME,
 
 		/**
-		 * The most common ISO DateTime Format {@code yyyy-MM-dd'T'HH:mm:ss.SSSXXX},
-		 * e.g. "2000-10-31T01:30:00.000-05:00".
+		 * The most common ISO Date Time Format {@code yyyy-MM-dd'T'HH:mm:ss.SSSXXX}
+		 * &mdash; for example, "2000-10-31T01:30:00.000-05:00".
 		 */
 		DATE_TIME,
 

spring-context/src/main/java/org/springframework/format/datetime/DateFormatter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,17 +27,21 @@
 import java.util.TimeZone;
 
 import org.springframework.format.Formatter;
+import org.springframework.format.annotation.DateTimeFormat;
 import org.springframework.format.annotation.DateTimeFormat.ISO;
 import org.springframework.lang.Nullable;
+import org.springframework.util.ObjectUtils;
 import org.springframework.util.StringUtils;
 
 /**
  * A formatter for {@link java.util.Date} types.
- * Allows the configuration of an explicit date pattern and locale.
+ * <p>Supports the configuration of an explicit date time pattern, timezone,
+ * locale, and fallback date time patterns for lenient parsing.
  *
  * @author Keith Donald
  * @author Juergen Hoeller
  * @author Phillip Webb
+ * @author Sam Brannen
  * @since 3.0
  * @see SimpleDateFormat
  */
@@ -56,9 +60,15 @@ public class DateFormatter implements Formatter<Date> {
 	}
 
 
+	@Nullable
+	private Object source;
+
 	@Nullable
 	private String pattern;
 
+	@Nullable
+	private String[] fallbackPatterns;
+
 	private int style = DateFormat.DEFAULT;
 
 	@Nullable
@@ -74,19 +84,33 @@ public class DateFormatter implements Formatter<Date> {
 
 
 	/**
-	 * Create a new default DateFormatter.
+	 * Create a new default {@code DateFormatter}.
 	 */
 	public DateFormatter() {
 	}
 
 	/**
-	 * Create a new DateFormatter for the given date pattern.
+	 * Create a new {@code DateFormatter} for the given date time pattern.
 	 */
 	public DateFormatter(String pattern) {
 		this.pattern = pattern;
 	}
 
 
+	/**
+	 * Set the source of the configuration for this {@code DateFormatter} &mdash;
+	 * for example, an instance of the {@link DateTimeFormat @DateTimeFormat}
+	 * annotation if such an annotation was used to configure this {@code DateFormatter}.
+	 * <p>The supplied source object will only be used for descriptive purposes
+	 * by invoking its {@code toString()} method &mdash; for example, when
+	 * generating an exception message to provide further context.
+	 * @param source the source of the configuration
+	 * @since 5.3.5
+	 */
+	public void setSource(Object source) {
+		this.source = source;
+	}
+
 	/**
 	 * Set the pattern to use to format date values.
 	 * <p>If not specified, DateFormat's default style will be used.
@@ -96,7 +120,19 @@ public void setPattern(String pattern) {
 	}
 
 	/**
-	 * Set the ISO format used for this date.
+	 * Set additional patterns to use as a fallback in case parsing fails for the
+	 * configured {@linkplain #setPattern pattern}, {@linkplain #setIso ISO format},
+	 * {@linkplain #setStyle style}, or {@linkplain #setStylePattern style pattern}.
+	 * @param fallbackPatterns the fallback parsing patterns
+	 * @since 5.3.5
+	 * @see DateTimeFormat#fallbackPatterns()
+	 */
+	public void setFallbackPatterns(String... fallbackPatterns) {
+		this.fallbackPatterns = fallbackPatterns;
+	}
+
+	/**
+	 * Set the ISO format to use to format date values.
 	 * @param iso the {@link ISO} format
 	 * @since 3.2
 	 */
@@ -105,7 +141,7 @@ public void setIso(ISO iso) {
 	}
 
 	/**
-	 * Set the style to use to format date values.
+	 * Set the {@link DateFormat} style to use to format date values.
 	 * <p>If not specified, DateFormat's default style will be used.
 	 * @see DateFormat#DEFAULT
 	 * @see DateFormat#SHORT
@@ -118,8 +154,10 @@ public void setStyle(int style) {
 	}
 
 	/**
-	 * Set the two character to use to format date values. The first character used for
-	 * the date style, the second is for the time style. Supported characters are
+	 * Set the two characters to use to format date values.
+	 * <p>The first character is used for the date style; the second is used for
+	 * the time style.
+	 * <p>Supported characters:
 	 * <ul>
 	 * <li>'S' = Small</li>
 	 * <li>'M' = Medium</li>
@@ -136,7 +174,7 @@ public void setStylePattern(String stylePattern) {
 	}
 
 	/**
-	 * Set the TimeZone to normalize the date values into, if any.
+	 * Set the {@link TimeZone} to normalize the date values into, if any.
 	 */
 	public void setTimeZone(TimeZone timeZone) {
 		this.timeZone = timeZone;
@@ -159,12 +197,43 @@ public String print(Date date, Locale locale) {
 
 	@Override
 	public Date parse(String text, Locale locale) throws ParseException {
-		return getDateFormat(locale).parse(text);
+		try {
+			return getDateFormat(locale).parse(text);
+		}
+		catch (ParseException ex) {
+			if (!ObjectUtils.isEmpty(this.fallbackPatterns)) {
+				for (String pattern : this.fallbackPatterns) {
+					try {
+						DateFormat dateFormat = configureDateFormat(new SimpleDateFormat(pattern, locale));
+						// Align timezone for parsing format with printing format if ISO is set.
+						if (this.iso != null && this.iso != ISO.NONE) {
+							dateFormat.setTimeZone(UTC);
+						}
+						return dateFormat.parse(text);
+					}
+					catch (ParseException ignoredException) {
+						// Ignore fallback parsing exceptions since the exception thrown below
+						// will include information from the "source" if available -- for example,
+						// the toString() of a @DateTimeFormat annotation.
+					}
+				}
+			}
+			if (this.source != null) {
+				throw new ParseException(
+					String.format("Unable to parse date time value \"%s\" using configuration from %s", text, this.source),
+					ex.getErrorOffset());
+			}
+			// else rethrow original exception
+			throw ex;
+		}
 	}
 
 
 	protected DateFormat getDateFormat(Locale locale) {
-		DateFormat dateFormat = createDateFormat(locale);
+		return configureDateFormat(createDateFormat(locale));
+	}
+
+	private DateFormat configureDateFormat(DateFormat dateFormat) {
 		if (this.timeZone != null) {
 			dateFormat.setTimeZone(this.timeZone);
 		}

spring-context/src/main/java/org/springframework/format/datetime/DateTimeFormatAnnotationFormatterFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,10 +16,12 @@
 
 package org.springframework.format.datetime;
 
+import java.util.ArrayList;
 import java.util.Calendar;
 import java.util.Collections;
 import java.util.Date;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 
 import org.springframework.context.support.EmbeddedValueResolutionSupport;
@@ -34,6 +36,7 @@
  * Formats fields annotated with the {@link DateTimeFormat} annotation using a {@link DateFormatter}.
  *
  * @author Phillip Webb
+ * @author Sam Brannen
  * @since 3.2
  * @see org.springframework.format.datetime.joda.JodaDateTimeFormatAnnotationFormatterFactory
  */
@@ -68,15 +71,30 @@ public Parser<?> getParser(DateTimeFormat annotation, Class<?> fieldType) {
 
 	protected Formatter<Date> getFormatter(DateTimeFormat annotation, Class<?> fieldType) {
 		DateFormatter formatter = new DateFormatter();
+		formatter.setSource(annotation);
+		formatter.setIso(annotation.iso());
+
 		String style = resolveEmbeddedValue(annotation.style());
 		if (StringUtils.hasLength(style)) {
 			formatter.setStylePattern(style);
 		}
-		formatter.setIso(annotation.iso());
+
 		String pattern = resolveEmbeddedValue(annotation.pattern());
 		if (StringUtils.hasLength(pattern)) {
 			formatter.setPattern(pattern);
 		}
+
+		List<String> resolvedFallbackPatterns = new ArrayList<>();
+		for (String fallbackPattern : annotation.fallbackPatterns()) {
+			String resolvedFallbackPattern = resolveEmbeddedValue(fallbackPattern);
+			if (StringUtils.hasLength(resolvedFallbackPattern)) {
+				resolvedFallbackPatterns.add(resolvedFallbackPattern);
+			}
+		}
+		if (!resolvedFallbackPatterns.isEmpty()) {
+			formatter.setFallbackPatterns(resolvedFallbackPatterns.toArray(new String[0]));
+		}
+
 		return formatter;
 	}