Declares that a field or method parameter should be formatted as a date or time.

Supports formatting by style pattern, ISO date time pattern, or custom format pattern string. Can be applied to java.util.Date, java.util.Calendar, Long (for millisecond timestamps) as well as JSR-310 java.time value types.

For style-based formatting, set the 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 '-' — for example, 'M-' specifies a medium format for the date with no time.

For ISO-based formatting, set the iso attribute to the desired ISO format, such as ISO#DATE.

For custom formatting, set the pattern attribute to a date time pattern, such as "yyyy/MM/dd hh:mm:ss a".

Each attribute is mutually exclusive, so only set one attribute per annotation instance (the one most convenient for your formatting needs).

When the pattern attribute is specified, it takes precedence over both the style and ISO attribute.
When the iso attribute is specified, it takes precedence over the style attribute.
When no annotation attributes are specified, the default format applied is style-based with a style code of 'SS' (short date, short time).

Time Zones

Whenever the style or pattern attribute is used, the default time zone of the JVM will be used when formatting java.util.Date values. Whenever the iso attribute is used when formatting java.util.Date values, UTC will be used as the time zone. The same time zone will be applied to any fallback patterns as well. In order to enforce consistent use of UTC as the time zone, you can bootstrap the JVM with -Duser.timezone=UTC.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	DateTimeFormat.ISO Common ISO date time format patterns.

Method Summary

Modifier and Type	Method and Description
public String[]	fallbackPatterns() The set of custom patterns to use as a fallback in case parsing fails for the primary `pattern`, `iso`, or `style` attribute.
public DateTimeFormat.ISO	iso() The ISO pattern to use to format the field or method parameter.
public String	pattern() The custom pattern to use to format the field or method parameter.
public String	style() The style pattern to use to format the field or method parameter.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

fallbackPatterns back to summary

fallbackPatterns	back to summary
public String[] fallbackPatterns() The set of custom patterns to use as a fallback in case parsing fails for the primary `pattern`, `iso`, or `style` attribute. 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. @DateTimeFormat(iso = ISO.DATE, fallbackPatterns = { "M/d/yy", "dd.MM.yyyy" }) Fallback patterns are only used for parsing. They are not used for printing the value as a String. The primary `pattern`, `iso`, or `style` attribute is always used for printing. For details on which time zone is used for fallback patterns, see the class-level documentation. Fallback patterns are not supported for Joda-Time value types. Since 5.3.5

public String[] fallbackPatterns()

The set of custom patterns to use as a fallback in case parsing fails for the primary pattern, iso, or style attribute.

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.

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

Fallback patterns are only used for parsing. They are not used for printing the value as a String. The primary pattern, iso, or style attribute is always used for printing. For details on which time zone is used for fallback patterns, see the class-level documentation.

Fallback patterns are not supported for Joda-Time value types.

Since: 5.3.5

iso back to summary

iso	back to summary
public DateTimeFormat.ISO iso() The ISO pattern to use to format the field or method parameter. Supported ISO patterns are defined in the `ISO` enum. Defaults to `ISO#NONE`, indicating this attribute should be ignored. Set this attribute when you wish to format your field or method parameter in accordance with an ISO format. See Also `fallbackPatterns`

public DateTimeFormat.ISO iso()

The ISO pattern to use to format the field or method parameter.

Supported ISO patterns are defined in the ISO enum.

Defaults to ISO#NONE, indicating this attribute should be ignored. Set this attribute when you wish to format your field or method parameter in accordance with an ISO format.

See Also: fallbackPatterns

pattern back to summary

pattern	back to summary
public String pattern() The custom pattern to use to format the field or method parameter. 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. Note This pattern follows the original `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 `java.time.format.DateTimeFormatter` specification (i.e. 'yy' turns into 'uu' when going through a `DateTimeFormatter` with strict resolution mode). See Also `fallbackPatterns`

public String pattern()

The custom pattern to use to format the field or method parameter.

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.

Note

This pattern follows the original 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 java.time.format.DateTimeFormatter specification (i.e. 'yy' turns into 'uu' when going through a DateTimeFormatter with strict resolution mode).

See Also: fallbackPatterns

style back to summary

style	back to summary
public String style() The style pattern to use to format the field or method parameter. 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 Also `fallbackPatterns`

public String style()

The style pattern to use to format the field or method parameter.

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 Also: fallbackPatterns

org.springframework.format.annotation back to summary

public final Enum DateTimeFormat.ISO

Class Inheritance

extends Enum<DateTimeFormat.ISO>

java.lang.Object
java.lang.Enum
org.springframework.format.annotation.DateTimeFormat.ISO

Common ISO date time format patterns.

Field Summary

Modifier and Type	Field and Description
public static final DateTimeFormat.ISO	DATE The most common ISO Date Format `yyyy-MM-dd` — for example, "2000-10-31".
public static final DateTimeFormat.ISO	DATE_TIME The most common ISO Date Time Format `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` — for example, "2000-10-31T01:30:00.000-05:00".
public static final DateTimeFormat.ISO	NONE Indicates that no ISO-based format pattern should be applied.
public static final DateTimeFormat.ISO	TIME The most common ISO Time Format `HH:mm:ss.SSSXXX` — for example, "01:30:00.000-05:00".

Constructor Summary

Access	Constructor and Description
private	ISO()

Method Summary

Modifier and Type	Method and Description
public static DateTimeFormat.ISO	valueOf(String name)
public static DateTimeFormat.ISO[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

DATE	back to summary
public static final DateTimeFormat.ISO DATE The most common ISO Date Format `yyyy-MM-dd` — for example, "2000-10-31".

DATE_TIME	back to summary
public static final DateTimeFormat.ISO DATE_TIME The most common ISO Date Time Format `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` — for example, "2000-10-31T01:30:00.000-05:00".

NONE	back to summary
public static final DateTimeFormat.ISO NONE Indicates that no ISO-based format pattern should be applied.

TIME	back to summary
public static final DateTimeFormat.ISO TIME The most common ISO Time Format `HH:mm:ss.SSSXXX` — for example, "01:30:00.000-05:00".

Constructor Detail

ISO	back to summary
private ISO()

Method Detail

valueOf	back to summary
public static DateTimeFormat.ISO valueOf(String name)

values	back to summary
public static DateTimeFormat.ISO[] values()

public @Interface DateTimeFormat

Time Zones

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum DateTimeFormat.ISO

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail