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 java.lang.Long},
030 * Joda-Time value types; and as of Spring 4 and JDK 8, to JSR-310 <code>java.time</code> types too.
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 org.joda.time.format.DateTimeFormat
052 */
053@Documented
054@Retention(RetentionPolicy.RUNTIME)
055@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
056public @interface DateTimeFormat {
057
058        /**
059         * The style pattern to use to format the field.
060         * <p>Defaults to 'SS' for short date time. Set this attribute when you wish to format
061         * your field in accordance with a common style other than the default style.
062         */
063        String style() default "SS";
064
065        /**
066         * The ISO pattern to use to format the field.
067         * <p>The possible ISO patterns are defined in the {@link ISO} enum.
068         * <p>Defaults to {@link ISO#NONE}, indicating this attribute should be ignored.
069         * Set this attribute when you wish to format your field in accordance with an ISO format.
070         */
071        ISO iso() default ISO.NONE;
072
073        /**
074         * The custom pattern to use to format the field.
075         * <p>Defaults to empty String, indicating no custom pattern String has been specified.
076         * Set this attribute when you wish to format your field in accordance with a custom
077         * date time pattern not represented by a style or ISO format.
078         * <p>Note: This pattern follows the original {@link java.text.SimpleDateFormat} style,
079         * as also supported by Joda-Time, with strict parsing semantics towards overflows
080         * (e.g. rejecting a Feb 29 value for a non-leap-year). As a consequence, 'yy'
081         * characters indicate a year in the traditional style, not a "year-of-era" as in the
082         * {@link java.time.format.DateTimeFormatter} specification (i.e. 'yy' turns into 'uu'
083         * when going through that {@code DateTimeFormatter} with strict resolution mode).
084         */
085        String pattern() default "";
086
087
088        /**
089         * Common ISO date time format patterns.
090         */
091        enum ISO {
092
093                /**
094                 * The most common ISO Date Format {@code yyyy-MM-dd},
095                 * e.g. "2000-10-31".
096                 */
097                DATE,
098
099                /**
100                 * The most common ISO Time Format {@code HH:mm:ss.SSSZ},
101                 * e.g. "01:30:00.000-05:00".
102                 */
103                TIME,
104
105                /**
106                 * The most common ISO DateTime Format {@code yyyy-MM-dd'T'HH:mm:ss.SSSZ},
107                 * e.g. "2000-10-31T01:30:00.000-05:00".
108                 */
109                DATE_TIME,
110
111                /**
112                 * Indicates that no ISO-based format pattern should be applied.
113                 */
114                NONE
115        }
116
117}