Package org.springframework.format.annotation

# Annotation Interface DateTimeFormat

@Documented @Retention(RUNTIME) @Target({METHOD,FIELD,PARAMETER,ANNOTATION_TYPE}) public @interface DateTimeFormat
Declares that a field or method parameter should be formatted as a date or time.

Formatting applies to parsing a date/time object from a string as well as printing a date/time object to a string.

Supports formatting by style pattern, ISO date/time pattern, or custom format pattern string. Can be applied to `Date`, `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. The supported style pattern codes correlate to the enum constants defined in `FormatStyle`.

WARNING: Style-based formatting and parsing rely on locale-sensitive patterns which may change depending on the Java runtime. Specifically, applications that rely on date/time parsing and formatting may encounter incompatible changes in behavior when running on JDK 20 or higher. Using an ISO standardized format or a concrete pattern that you control allows for reliable system-independent and locale-independent parsing and formatting of date/time values. The use of fallback patterns can also help to address compatibility issues. For further details, see the Date and Time Formatting with JDK 20 and higher page in the Spring Framework wiki.

For ISO-based formatting, set the `iso()` attribute to the desired `DateTimeFormat.ISO` format, such as `DateTimeFormat.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 `Date` values. Whenever the `iso()` attribute is used when formatting `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`.

Since:
  3.0
Author:
  Keith Donald, Juergen Hoeller, Sam Brannen
See Also:
  - `DateFormat`
  - `SimpleDateFormat`
  - `DateTimeFormatter`

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`DateTimeFormat.ISO`
Common ISO date time format patterns.

## Optional Element Summary

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

## Element Details

### style

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 the class-level documentation for further details.

See Also:
  - `fallbackPatterns()`

Default:
  "SS"

### iso

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

Supported ISO patterns are defined in the `DateTimeFormat.ISO` enum.

Defaults to `DateTimeFormat.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()`

Default:
  NONE

### pattern

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

Defaults to an 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 `SimpleDateFormat` style, with strict parsing semantics towards overflows (for example, 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 `DateTimeFormatter` specification (i.e. 'yy' turns into 'uu' when going through a `DateTimeFormatter` with strict resolution mode).

See Also:
  - `fallbackPatterns()`

Default:
  ""

### fallbackPatterns

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.

Since:
  5.3.5

Default:
  {}