1 package com.opencsv.bean;
2
3 import com.opencsv.exceptions.CsvConstraintViolationException;
4 import com.opencsv.exceptions.CsvDataTypeMismatchException;
5 import com.opencsv.exceptions.CsvRequiredFieldEmptyException;
6 import com.opencsv.exceptions.CsvValidationException;
7
8 import java.lang.reflect.Field;
9 import java.util.Locale;
10
11 /**
12 * Used to extend the {@link java.lang.reflect.Field} class to include
13 * functionality that opencsv requires.
14 * <p>This includes a required flag and a
15 * {@link #write(java.lang.Object, java.lang.Object) } method for writing beans
16 * back out to a CSV file. The required flag determines if the field has to be
17 * non-empty.</p>
18 * <p><b><i>Synchronization:</i></b> All implementations of this interface must
19 * be thread-safe.</p>
20 *
21 * @param <T> Type of the bean being populated
22 * @param <I> Type of the index into a multivalued field
23 */
24 public interface BeanField<T, I> {
25
26 /**
27 * Gets the type of the bean this field is attached to.
28 * This is necessary because the declaring class as given by the field
29 * itself may be a superclass of the class that is instantiated during bean
30 * population.
31 *
32 * @return The type of the bean this field is attached to
33 * @since 5.0
34 */
35 Class<?> getType();
36
37 /**
38 * Sets the type of the bean this field is attached to.
39 *
40 * @param type The type that is instantiated when this field is used
41 * @since 5.0
42 */
43 void setType(Class<?> type);
44
45 /**
46 * Sets the field to be processed.
47 *
48 * @param field Which field is being populated
49 */
50 void setField(Field field);
51
52 /**
53 * Gets the field to be processed.
54 *
55 * @return A field object
56 * @see java.lang.reflect.Field
57 */
58 Field getField();
59
60 /**
61 * Answers the query, whether this field is required or not.
62 *
63 * @return True if the field is required to be set (cannot be null or an
64 * empty string), false otherwise
65 * @since 3.10
66 */
67 boolean isRequired();
68
69 /**
70 * Determines whether or not a field is required.
71 * Implementation note: This method is necessary for custom converters. If
72 * we did not have it, every custom converter would be required to implement
73 * a constructor with this one boolean parameter, and the instantiation code
74 * for the custom converter would look much uglier.
75 *
76 * @param required Whether or not the field is required
77 * @since 3.10
78 */
79 void setRequired(boolean required);
80
81 /**
82 * Populates the selected field of the bean.
83 * This method performs conversion on the input string and assigns the
84 * result to the proper field in the provided bean.
85 *
86 * @param bean Object containing the field to be set.
87 * @param value String containing the value to set the field to.
88 * @param header The header from the CSV file under which this value was found.
89 * @throws CsvDataTypeMismatchException When the result of data conversion returns
90 * an object that cannot be assigned to the selected field
91 * @throws CsvRequiredFieldEmptyException When a field is mandatory, but there is no
92 * input datum in the CSV file
93 * @throws CsvConstraintViolationException When the internal structure of
94 * data would be violated by the data in the CSV file
95 * @throws CsvValidationException If a user-supplied validator determines
96 * that the input is invalid
97 */
98 void setFieldValue(Object bean, String value, String header)
99 throws CsvDataTypeMismatchException, CsvRequiredFieldEmptyException,
100 CsvConstraintViolationException, CsvValidationException;
101
102 /**
103 * Gets the contents of the selected field of the given bean.
104 * This method performs no conversions of any kind, but simply gets the
105 * value of the desired field using an accessor method if one is
106 * available and reflection if one is not.
107 *
108 * @param bean Object containing the field to be read
109 * @return The value of the field in the given bean
110 * @since 4.2
111 */
112 Object getFieldValue(Object bean);
113
114 /**
115 * Given the value of a bean field and an index into that value, determine
116 * what values need to be written.
117 * When writing a bean to a CSV file, some single fields from the bean could
118 * have values that need to be split into multiple fields when writing them
119 * to the CSV file. Given the value of the bean field and an index into the
120 * data, this method returns the objects to be converted and written.
121 *
122 * @param value The value of the bean field that should be written
123 * @param index An index into {@code value} that determines which of the
124 * many possible values are currently being written. For header-based
125 * mapping strategies, this will be the header name, and for column
126 * position mapping strategies, it will be the zero-based column position.
127 * @return An array of {@link Object}s that should be converted for the
128 * output and written
129 * @throws CsvDataTypeMismatchException If {@code value} is not of the type
130 * expected by the implementing class
131 * @since 4.2
132 */
133 Object[] indexAndSplitMultivaluedField(Object value, I index)
134 throws CsvDataTypeMismatchException;
135
136 /**
137 * This method takes the current value of the field in question in the bean
138 * passed in and converts it to one or more strings.
139 * This method is used to write beans back out to a CSV file, and should
140 * ideally provide an accurate representation of the field such that it is
141 * round trip equivalent. That is to say, this method should write data out
142 * just as it would expect to read the data in.
143 *
144 * @param bean The bean holding the field to be written
145 * @param index The header name or column number of the field currently
146 * being processed. This can be used to find a certain position in a
147 * multivalued field when not all of the values should be written.
148 * @return An array of string representations for the values of this field
149 * out of the bean passed in. Typically, there will be only one value, but
150 * {@link com.opencsv.bean.BeanFieldJoin} may return multiple values.
151 * If either the bean or the field are {@code null}, this method returns
152 * an empty array to allow the writer to treat {@code null} specially. It
153 * is also possible that individual values in the array are {@code null}.
154 * The writer may wish to write "(null)" or "\0" or "NULL" or some other
155 * key instead of a blank string.
156 *
157 * @throws CsvDataTypeMismatchException If expected to convert an
158 * unsupported data type
159 * @throws CsvRequiredFieldEmptyException If the field is marked as required,
160 * but is currently empty
161 * @since 3.9
162 */
163 String[] write(Object bean, I index) throws CsvDataTypeMismatchException,
164 CsvRequiredFieldEmptyException;
165
166 /**
167 * Sets the locale for all error messages.
168 * @param errorLocale Locale for error messages. If null, the default locale
169 * is used.
170 * @since 4.0
171 */
172 void setErrorLocale(Locale errorLocale);
173
174 /**
175 * Returns the error locale for the beans. Used by the opencsv provided validators
176 * to populate the error messages they generate.
177 *
178 * @return Locale for error messages.
179 * @since 5.0
180 */
181 Locale getErrorLocale();
182 }