1 /*
2 * Copyright 2016 Andrew Rucker Jones.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.opencsv.bean;
17
18 import java.lang.annotation.*;
19
20 /**
21 * This annotation indicates that the destination field is an expression of time.
22 * <p>Conversion to the following old-style types is supported:
23 * <ul><li>{@link java.util.Date}</li>
24 * <li>{@link java.util.Calendar} (a {@link java.util.GregorianCalendar} is returned)</li>
25 * <li>{@link java.util.GregorianCalendar}</li>
26 * <li>{@link javax.xml.datatype.XMLGregorianCalendar}</li>
27 * <li>{@link java.sql.Date}</li>
28 * <li>{@link java.sql.Time}</li>
29 * <li>{@link java.sql.Timestamp}</li>
30 * </ul></p>
31 * <p>Conversion to the following {@link java.time.temporal.TemporalAccessor}-style
32 * types is supported:
33 * <ul><li>{@link java.time.temporal.TemporalAccessor}. If this interface is
34 * used, the actual type returned is not defined.</li>
35 * <li>{@link java.time.chrono.ChronoLocalDate}. If this interface is used, the
36 * actual type returned is {@link java.time.LocalDate}.</li>
37 * <li>{@link java.time.LocalDate}</li>
38 * <li>{@link java.time.chrono.ChronoLocalDateTime}. If this interface is used,
39 * the actual type returned is {@link java.time.LocalDateTime}.</li>
40 * <li>{@link java.time.LocalDateTime}</li>
41 * <li>{@link java.time.chrono.ChronoZonedDateTime}. If this interface is used,
42 * the actual type returned is {@link java.time.ZonedDateTime}.</li>
43 * <li>{@link java.time.ZonedDateTime}</li>
44 * <li>{@link java.time.temporal.Temporal}. If this interface is used, the
45 * actual type returned is not defined.</li>
46 * <li>{@link java.time.chrono.Era}. If this interface is used, the actual type
47 * returned is {@link java.time.chrono.IsoEra}.</li>
48 * <li>{@link java.time.chrono.IsoEra}</li>
49 * <li>{@link java.time.DayOfWeek}</li>
50 * <li>{@link java.time.chrono.HijrahDate}</li>
51 * <li>{@link java.time.chrono.HijrahEra}</li>
52 * <li>{@link java.time.Instant}</li>
53 * <li>{@link java.time.chrono.JapaneseDate}</li>
54 * <li>{@link java.time.chrono.JapaneseEra}</li>
55 * <li>{@link java.time.LocalTime}</li>
56 * <li>{@link java.time.chrono.MinguoDate}</li>
57 * <li>{@link java.time.chrono.MinguoEra}</li>
58 * <li>{@link java.time.Month}</li>
59 * <li>{@link java.time.MonthDay}</li>
60 * <li>{@link java.time.OffsetDateTime}</li>
61 * <li>{@link java.time.OffsetTime}</li>
62 * <li>{@link java.time.chrono.ThaiBuddhistDate}</li>
63 * <li>{@link java.time.chrono.ThaiBuddhistEra}</li>
64 * <li>{@link java.time.Year}</li>
65 * <li>{@link java.time.YearMonth}</li>
66 * <li>{@link java.time.ZoneOffset}</li></ul></p>
67 * <p>This annotation must be used with either {@link com.opencsv.bean.CsvBindByName}
68 * or {@link com.opencsv.bean.CsvBindByPosition}, otherwise it is ignored.</p>
69 *
70 * @author Andrew Rucker Jones
71 * @since 3.8
72 */
73 @Documented
74 @Retention(RetentionPolicy.RUNTIME)
75 @Target(ElementType.FIELD)
76 @Repeatable(CsvDates.class)
77 public @interface CsvDate {
78
79 /**
80 * A date/time format string.
81 * If this annotation is applied to old-style dates and times, then this
82 * must be a string understood by
83 * {@link java.text.SimpleDateFormat#SimpleDateFormat(java.lang.String)}.
84 * If it is applied to {@link java.time.temporal.TemporalAccessor}-based
85 * dates and times, then this must be a string understood by
86 * {@link java.time.format.DateTimeFormatter}.
87 * The default value works for both styles and conforms with
88 * <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>. Locale
89 * information, if specified, is gleaned from one of the other CSV-related
90 * annotations and is used for conversion.
91 *
92 * @return The format string for parsing input
93 */
94 String value() default "yyyyMMdd'T'HHmmss";
95
96 /**
97 * Whether or not the same format string is used for writing as for reading.
98 * If this is true, {@link #value()} is used for both reading and writing
99 * and {@link #writeFormat()} is ignored.
100 *
101 * @return Whether the read format is used for writing as well
102 * @since 5.0
103 */
104 boolean writeFormatEqualsReadFormat() default true;
105
106 /**
107 * A date/time format string.
108 *
109 * @return The format string for formatting output
110 * @see #value()
111 * @see #writeFormatEqualsReadFormat()
112 * @since 5.0
113 */
114 String writeFormat() default "yyyyMMdd'T'HHmmss";
115
116 /**
117 * The {@link java.time.chrono.Chronology} that should be used for parsing.
118 * <p>The value must be understood by
119 * {@link java.time.chrono.Chronology#of(String)}. The requisite ID for the
120 * desired Chronology can usually be found in the Javadoc for the
121 * {@code getId()} method of the specific implementation.</p>
122 * <p>This value is only used for
123 * {@link java.time.temporal.TemporalAccessor}-based fields. It is ignored
124 * for old-style dates and times.</p>
125 * <p>The default value specifies the ISO-8601 chronology. If a blank
126 * string or empty string is specified, the chronology is
127 * {@link java.time.chrono.Chronology#ofLocale(Locale) taken from the locale}.</p>
128 *
129 * @return The {@link java.time.chrono.Chronology} in use
130 * @since 5.0
131 */
132 String chronology() default "ISO";
133
134 /**
135 * Whether or not the same chronology string is used for writing as for
136 * reading.
137 * If this is true, {@link #chronology()} is used for both reading and
138 * writing and {@link #writeChronology()} is ignored.
139 *
140 * @return Whether the read chronology is used for writing as well
141 * @since 5.0
142 */
143 boolean writeChronologyEqualsReadChronology() default true;
144
145 /**
146 * The {@link java.time.chrono.Chronology} that should be used for
147 * formatting.
148 *
149 * @return The {@link java.time.chrono.Chronology} in use
150 * @see #chronology()
151 * @see #writeChronologyEqualsReadChronology()
152 * @since 5.0
153 */
154 String writeChronology() default "ISO";
155
156 /**
157 * A profile can be used to annotate the same field differently for
158 * different inputs or outputs.
159 * <p>Perhaps you have multiple input sources, and they all use different
160 * header names or positions for the same data. With profiles, you don't
161 * have to create different beans with the same fields and different
162 * annotations for each input. Simply annotate the same field multiple
163 * times and specify the profile when you parse the input.</p>
164 * <p>The same applies to output: if you want to be able to represent the
165 * same data in multiple CSV formats (that is, with different headers or
166 * orders), annotate the bean fields multiple times with different profiles
167 * and specify which profile you want to use on writing.</p>
168 * <p>Results are undefined if profile names are not unique.</p>
169 * <p>If the same configuration applies to multiple profiles, simply list
170 * all applicable profile names here. This parameter is an array of
171 * strings.</p>
172 * <p>The empty string, which is the default value, specifies the default
173 * profile and will be used if no annotation for the specific profile
174 * being used can be found, or if no profile is specified.</p>
175 *
176 * @return The names of the profiles this configuration is for
177 * @since 5.4
178 */
179 String[] profiles() default "";
180 }