Interface MappingStrategy<T>
-
- Type Parameters:
T
- Type of object you are converting the data to.
- All Known Implementing Classes:
AbstractMappingStrategy
,ColumnPositionMappingStrategy
,FuzzyMappingStrategy
,HeaderColumnNameMappingStrategy
,HeaderColumnNameTranslateMappingStrategy
,HeaderNameBaseMappingStrategy
public interface MappingStrategy<T>
The interface for the classes that handle translating between the columns in the CSV file to an actual object.Any implementing class must be thread-safe. Specifically, the following methods must be thread-safe:
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description void
captureHeader(CSVReader reader)
Implementation of this method can grab the header line before parsing begins to use to map columns to bean properties.java.lang.String[]
generateHeader(T bean)
Implementations of this method must return an array of column headers based on the contents of the mapping strategy.default void
ignoreFields(org.apache.commons.collections4.MultiValuedMap<java.lang.Class<?>,java.lang.reflect.Field> fields)
When processing a bean for reading or writing, ignore the given fields from the given classes completely, including all annotations and requirements.default boolean
isAnnotationDriven()
Deprecated.This is simply no longer necessary.T
populateNewBean(java.lang.String[] line)
Takes a line of input from a CSV file and creates a bean out of it.default void
setErrorLocale(java.util.Locale errorLocale)
Sets the locale for all error messages.void
setType(java.lang.Class<? extends T> type)
Sets the class type that is being mapped.java.lang.String[]
transmuteBean(T bean)
Transmutes a bean instance into an array ofString
s to be written to a CSV file.
-
-
-
Method Detail
-
captureHeader
void captureHeader(CSVReader reader) throws java.io.IOException, CsvRequiredFieldEmptyException
Implementation of this method can grab the header line before parsing begins to use to map columns to bean properties.- Parameters:
reader
- The CSVReader to use for header parsing- Throws:
java.io.IOException
- If parsing failsCsvRequiredFieldEmptyException
- If a field is required, but the header or column position for the field is not present in the input
-
generateHeader
java.lang.String[] generateHeader(T bean) throws CsvRequiredFieldEmptyException
Implementations of this method must return an array of column headers based on the contents of the mapping strategy. If no header can or should be generated, an array of zero length must be returned, and notnull
.- Parameters:
bean
- One fully populated bean from which the header can be derived. This is important in the face of joining and splitting. If we have a MultiValuedMap as a field that is the target for a join on reading, that same field must be split into multiple columns on writing. Since the joining is done via regular expressions, it is impossible for opencsv to know what the column names are supposed to be on writing unless this bean includes a fully populated map.- Returns:
- An array of column names for a header. This may be an empty array
if no header should be written, but it must not be
null
. - Throws:
CsvRequiredFieldEmptyException
- If a required header is missing while attempting to write. Since every other header is hard-wired through the bean fields and their associated annotations, this can only happen with multi-valued fields.- Since:
- 3.9
-
isAnnotationDriven
@Deprecated default boolean isAnnotationDriven()
Deprecated.This is simply no longer necessary.Determines whether the mapping strategy is driven by annotations.- Returns:
- Whether the mapping strategy is driven by annotations
-
populateNewBean
T populateNewBean(java.lang.String[] line) throws CsvBeanIntrospectionException, CsvRequiredFieldEmptyException, CsvDataTypeMismatchException, CsvConstraintViolationException, CsvValidationException
Takes a line of input from a CSV file and creates a bean out of it.- Parameters:
line
- A line of input returned fromCSVReader
- Returns:
- A bean containing the converted information from the input
- Throws:
CsvBeanIntrospectionException
- Generally, if some part of the bean cannot be accessed and used as neededCsvRequiredFieldEmptyException
- If the input for a field defined as required is emptyCsvDataTypeMismatchException
- If conversion of the input to a field type failsCsvConstraintViolationException
- If the value provided for a field would in some way compromise the logical integrity of the data as a wholeCsvValidationException
- If a user-supplied validator determines that the input is invalid- Since:
- 4.2
-
setErrorLocale
default void setErrorLocale(java.util.Locale errorLocale)
Sets the locale for all error messages. The default implementation does nothing, as it is expected that most implementations of this interface will not support multiple languages.- Parameters:
errorLocale
- Locale for error messages. If null, the default locale is used.- Since:
- 4.0
-
setType
void setType(java.lang.Class<? extends T> type) throws CsvBadConverterException
Sets the class type that is being mapped. May perform additional initialization tasks.- Parameters:
type
- Class type.- Throws:
CsvBadConverterException
- If a field in the bean is annotated with a custom converter that cannot be initialized. If you are not using custom converters that you have written yourself, it should be safe to catch this exception and ignore it.
-
ignoreFields
default void ignoreFields(org.apache.commons.collections4.MultiValuedMap<java.lang.Class<?>,java.lang.reflect.Field> fields) throws java.lang.IllegalArgumentException
When processing a bean for reading or writing, ignore the given fields from the given classes completely, including all annotations and requirements.This method has two compelling applications:
- If you are not able to modify the source code of the beans you use, or
- If you use a mapping strategy without annotations and want to exclude a small number of fields from a bean with a large number of fields.
Calling this method overwrites the fields passed in from any previous calls. It is legal to call this method before calling
setType(Class)
, and it may be more efficient to do so.Caution must be exercised with this method when letting opencsv automatically determine the mapping strategy. When a field is ignored, opencsv pretends it does not exist at all. If, for instance, all fields annotated with opencsv binding annotations are ignored, opencsv will automatically switch to
HeaderColumnNameMappingStrategy
and assume header names exactly match field names.An implementation of this interface is not required to implement this method. The default implementation throws
UnsupportedOperationException
.- Parameters:
fields
- All fields to be ignored, mapped from the classes of which they are members. These are the classes as opencsv encounters them, not necessarily the declaring classes if any fields are inherited. May benull
.- Throws:
java.lang.IllegalArgumentException
- If any entry in the map has anull
key, anull
value, or if the value is not a field in the class represented by the key- Since:
- 5.0
- See Also:
CsvIgnore
-
transmuteBean
java.lang.String[] transmuteBean(T bean) throws CsvDataTypeMismatchException, CsvRequiredFieldEmptyException
Transmutes a bean instance into an array ofString
s to be written to a CSV file.- Parameters:
bean
- The bean to be transmuted- Returns:
- The converted values of the bean fields in the correct order,
ready to be passed to a
CSVWriter
- Throws:
CsvDataTypeMismatchException
- If expected to convert an unsupported data typeCsvRequiredFieldEmptyException
- If the field is marked as required, but is currently empty
-
-