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