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}