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 import java.util.regex.Matcher;
20
21 /**
22 * Specifies a binding between a column number of the CSV input and a field in
23 * a bean.
24 *
25 * @author Andrew Rucker Jones
26 * @since 3.8
27 */
28 @Documented
29 @Retention(RetentionPolicy.RUNTIME)
30 @Target(ElementType.FIELD)
31 @Repeatable(CsvBindByPositions.class)
32 public @interface CsvBindByPosition {
33
34 /**
35 * Whether or not the annotated field is required to be present in every
36 * data set of the input.
37 * This means that the input cannot be empty. The output after conversion is
38 * not guaranteed to be non-empty. "Input" means the string from the field
39 * in the CSV file on reading and the bean member variable on writing.
40 *
41 * @return If the field is required to contain information.
42 */
43 boolean required() default false;
44
45 /**
46 * The column position in the input that is used to fill the annotated
47 * field.
48 *
49 * @return The position of the column in the CSV file from which this field
50 * should be taken. This column number is zero-based.
51 */
52 int position();
53
54 /**
55 * Defines the locale to be used for decoding the argument.
56 * <p>If not specified, the current default locale is used. The locale must be
57 * one recognized by {@link java.util.Locale}. Locale conversion is supported
58 * for the following data types:<ul>
59 * <li>byte and {@link java.lang.Byte}</li>
60 * <li>float and {@link java.lang.Float}</li>
61 * <li>double and {@link java.lang.Double}</li>
62 * <li>int and {@link java.lang.Integer}</li>
63 * <li>long and {@link java.lang.Long}</li>
64 * <li>short and {@link java.lang.Short}</li>
65 * <li>{@link java.math.BigDecimal}</li>
66 * <li>{@link java.math.BigInteger}</li>
67 * <li>All time data types supported by {@link com.opencsv.bean.CsvDate}</li></ul>
68 * <p>The locale must be in a format accepted by
69 * {@link java.util.Locale#forLanguageTag(java.lang.String)}</p>
70 * <p>Caution must be exercised with the default locale, for the default
71 * locale for numerical types does not mean the locale of the running
72 * program, such as en-US or de-DE, but rather <em>no</em> locale. Numbers
73 * will be parsed more or less the way the Java compiler would parse them.
74 * That means, for instance, that thousands separators in long numbers are
75 * not permitted, even if the locale of the running program would accept
76 * them. When dealing with locale-sensitive data, it is always best to
77 * specify the locale explicitly.</p>
78 *
79 * @return The locale selected. The default is indicated by an empty string.
80 */
81 String locale() default "";
82
83 /**
84 * Whether or not the same locale is used for writing as for reading.
85 * If this is true, {@link #locale()} is used for both reading and writing
86 * and {@link #writeLocale()} is ignored.
87 *
88 * @return Whether the read locale is used for writing as well
89 * @since 5.0
90 */
91 boolean writeLocaleEqualsReadLocale() default true;
92
93 /**
94 * The locale for writing.
95 * This field is ignored unless {@link #writeLocaleEqualsReadLocale()} is
96 * {@code false}. The format is identical to {@link #locale()}.
97 *
98 * @return The locale for writing, if one is in use
99 * @see #locale()
100 * @see #writeLocaleEqualsReadLocale()
101 * @since 5.0
102 */
103 String writeLocale() default "";
104
105 /**
106 * If this is anything but an empty string, it will be used as a regular
107 * expression to extract part of the input before conversion to the bean
108 * field.
109 * <p>An empty string behaves as if the regular expression {@code ^(.*)$}
110 * had been specified.</p>
111 * <p>The regular expression will be compiled and every field of input will
112 * be passed through it, naturally after the input has been normalized
113 * (quotations and escape characters removed). The first capture group will
114 * be extracted, and that string will be passed on to the appropriate
115 * conversion routine for the bean field in question.</p>
116 * <p>This makes it possible to easily convert input fields with forms like
117 * {@code Grade: 94.2} into {@code 94.2}, which can then be converted to a
118 * floating point bean field, all without writing a custom converter.</p>
119 * <p>The regular expression is applied to the entire string in question
120 * (i.e. with {@link Matcher#matches()}), instead of just the beginning of
121 * the string ({@link Matcher#lookingAt()}) or anywhere in the string
122 * ({@link Matcher#find()}). If it fails to match, the input string is
123 * passed unchanged to the appropriate conversion routine for the bean
124 * field. The reason for this is two-fold:</p>
125 * <ol><li>The matching may occur against an empty string. If the field is
126 * not required, this is legitimate, but it's likely the regular expression
127 * is not written to accommodate this possibility, and it may indeed not be
128 * at all desirable to.</li>
129 * <li>If there is an error in either the regular expression or the input
130 * that causes the match to fail, there is a good likelihood that the
131 * subsequent conversion will fail with a
132 * {@link com.opencsv.exceptions.CsvDataTypeMismatchException} if the
133 * input is not being converted into a simple string.</li></ol>
134 * <p>This is the inverse operation of {@link #format()}.</p>
135 *
136 * @return A regular expression, the first capture group of which will be
137 * used for conversion to the bean field
138 * @since 4.3
139 */
140 String capture() default "";
141
142 /**
143 * If this is anything but an empty string, it will be used as a format
144 * string for {@link java.lang.String#format(String, Object...)} on
145 * writing.
146 * <p>An empty string behaves as if the format string {@code "%s"} had been
147 * specified.</p>
148 * <p>The format string, if it is not empty, should contain one and only
149 * one {@code %s}, which will be replaced by the string value of the bean
150 * field after conversion. If, however, the bean field is empty, then the
151 * output will be empty as well, as opposed to passing an empty string to
152 * this format string and using that as the output.</p>
153 * <p>This is the inverse operation of {@link #capture()}.</p>
154 *
155 * @return A format string for writing fields
156 * @since 4.3
157 */
158 String format() default "";
159
160 /**
161 * A profile can be used to annotate the same field differently for
162 * different inputs or outputs.
163 * <p>Perhaps you have multiple input sources, and they all use different
164 * header names or positions for the same data. With profiles, you don't
165 * have to create different beans with the same fields and different
166 * annotations for each input. Simply annotate the same field multiple
167 * times and specify the profile when you parse the input.</p>
168 * <p>The same applies to output: if you want to be able to represent the
169 * same data in multiple CSV formats (that is, with different headers or
170 * orders), annotate the bean fields multiple times with different profiles
171 * and specify which profile you want to use on writing.</p>
172 * <p>Results are undefined if profile names are not unique.</p>
173 * <p>If the same configuration applies to multiple profiles, simply list
174 * all applicable profile names here. This parameter is an array of
175 * strings.</p>
176 * <p>The empty string, which is the default value, specifies the default
177 * profile and will be used if no annotation for the specific profile
178 * being used can be found, or if no profile is specified.</p>
179 *
180 * @return The names of the profiles this configuration is for
181 * @since 5.4
182 */
183 String[] profiles() default "";
184 }