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 * Allows us to specify a class that will perform the translation from source
22 * to destination.
23 * For special needs, we can implement a class that takes the source field from
24 * the CSV and translates it into a form of our choice.
25 *
26 * @author Andrew Rucker Jones
27 * @since 3.8
28 */
29 @Documented
30 @Retention(RetentionPolicy.RUNTIME)
31 @Target(ElementType.FIELD)
32 @Repeatable(CsvCustomBindByPositions.class)
33 public @interface CsvCustomBindByPosition {
34
35 /**
36 * The class that takes care of the conversion.
37 * Every custom converter must be descended from
38 * {@link com.opencsv.bean.AbstractBeanField} and override the method
39 * {@link com.opencsv.bean.AbstractBeanField#convert(java.lang.String)}.
40 *
41 * @return The implementation that can convert to the type of this field.
42 */
43 Class<? extends AbstractBeanField> converter();
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 * Whether or not the annotated field is required to be present in every
56 * data set of the input.
57 * This means that the input cannot be empty. The output after conversion is
58 * not guaranteed to be non-empty. "Input" means the string from the field
59 * in the CSV file on reading and the bean member variable on writing.
60 *
61 * @return If the field is required to contain information.
62 * @since 3.10
63 */
64 boolean required() default false;
65
66 /**
67 * A profile can be used to annotate the same field differently for
68 * different inputs or outputs.
69 * <p>Perhaps you have multiple input sources, and they all use different
70 * header names or positions for the same data. With profiles, you don't
71 * have to create different beans with the same fields and different
72 * annotations for each input. Simply annotate the same field multiple
73 * times and specify the profile when you parse the input.</p>
74 * <p>The same applies to output: if you want to be able to represent the
75 * same data in multiple CSV formats (that is, with different headers or
76 * orders), annotate the bean fields multiple times with different profiles
77 * and specify which profile you want to use on writing.</p>
78 * <p>Results are undefined if profile names are not unique.</p>
79 * <p>If the same configuration applies to multiple profiles, simply list
80 * all applicable profile names here. This parameter is an array of
81 * strings.</p>
82 * <p>The empty string, which is the default value, specifies the default
83 * profile and will be used if no annotation for the specific profile
84 * being used can be found, or if no profile is specified.</p>
85 *
86 * @return The names of the profiles this configuration is for
87 * @since 5.4
88 */
89 String[] profiles() default "";
90 }