001/*
002 * Copyright 2002-2020 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.format.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023import java.lang.annotation.Target;
024
025/**
026 * Declares that a field or method parameter should be formatted as a date or time.
027 *
028 * <p>Supports formatting by style pattern, ISO date time pattern, or custom format pattern string.
029 * Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code Long} (for
030 * millisecond timestamps) as well as JSR-310 <code>java.time</code> and Joda-Time value types.
031 *
032 * <p>For style-based formatting, set the {@link #style} attribute to be the style pattern code.
033 * The first character of the code is the date style, and the second character is the time style.
034 * Specify a character of 'S' for short style, 'M' for medium, 'L' for long, and 'F' for full.
035 * A date or time may be omitted by specifying the style character '-'.
036 *
037 * <p>For ISO-based formatting, set the {@link #iso} attribute to be the desired {@link ISO} format,
038 * such as {@link ISO#DATE}. For custom formatting, set the {@link #pattern} attribute to be the
039 * DateTime pattern, such as {@code yyyy/MM/dd hh:mm:ss a}.
040 *
041 * <p>Each attribute is mutually exclusive, so only set one attribute per annotation instance
042 * (the one most convenient one for your formatting needs).
043 * When the pattern attribute is specified, it takes precedence over both the style and ISO attribute.
044 * When the {@link #iso} attribute is specified, it takes precedence over the style attribute.
045 * When no annotation attributes are specified, the default format applied is style-based
046 * with a style code of 'SS' (short date, short time).
047 *
048 * @author Keith Donald
049 * @author Juergen Hoeller
050 * @since 3.0
051 * @see java.time.format.DateTimeFormatter
052 * @see org.joda.time.format.DateTimeFormat
053 */
054@Documented
055@Retention(RetentionPolicy.RUNTIME)
056@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
057public @interface DateTimeFormat {
058
059        /**
060         * The style pattern to use to format the field.
061         * <p>Defaults to 'SS' for short date time. Set this attribute when you wish to format
062         * your field in accordance with a common style other than the default style.
063         */
064        String style() default "SS";
065
066        /**
067         * The ISO pattern to use to format the field.
068         * <p>The possible ISO patterns are defined in the {@link ISO} enum.
069         * <p>Defaults to {@link ISO#NONE}, indicating this attribute should be ignored.
070         * Set this attribute when you wish to format your field in accordance with an ISO format.
071         */
072        ISO iso() default ISO.NONE;
073
074        /**
075         * The custom pattern to use to format the field.
076         * <p>Defaults to empty String, indicating no custom pattern String has been specified.
077         * Set this attribute when you wish to format your field in accordance with a custom
078         * date time pattern not represented by a style or ISO format.
079         * <p>Note: This pattern follows the original {@link java.text.SimpleDateFormat} style,
080         * as also supported by Joda-Time, with strict parsing semantics towards overflows
081         * (e.g. rejecting a Feb 29 value for a non-leap-year). As a consequence, 'yy'
082         * characters indicate a year in the traditional style, not a "year-of-era" as in the
083         * {@link java.time.format.DateTimeFormatter} specification (i.e. 'yy' turns into 'uu'
084         * when going through that {@code DateTimeFormatter} with strict resolution mode).
085         */
086        String pattern() default "";
087
088
089        /**
090         * Common ISO date time format patterns.
091         */
092        enum ISO {
093
094                /**
095                 * The most common ISO Date Format {@code yyyy-MM-dd},
096                 * e.g. "2000-10-31".
097                 */
098                DATE,
099
100                /**
101                 * The most common ISO Time Format {@code HH:mm:ss.SSSXXX},
102                 * e.g. "01:30:00.000-05:00".
103                 */
104                TIME,
105
106                /**
107                 * The most common ISO DateTime Format {@code yyyy-MM-dd'T'HH:mm:ss.SSSXXX},
108                 * e.g. "2000-10-31T01:30:00.000-05:00".
109                 */
110                DATE_TIME,
111
112                /**
113                 * Indicates that no ISO-based format pattern should be applied.
114                 */
115                NONE
116        }
117
118}