com.opencsv.bean

Class AbstractBeanField<T,I>

java.lang.Object

com.opencsv.bean.AbstractBeanField<T,I>

Type Parameters:

T - Type of the bean being populated

I - Type of the index into a multivalued field

All Implemented Interfaces:

BeanField<T,I>

Direct Known Subclasses:

BeanFieldSingleValue, BeanFieldSplit, ConverterLanguageToBoolean

public abstract class AbstractBeanField<T,I>
extends Object
implements BeanField<T,I>

This base bean takes over the responsibility of converting the supplied string to the proper type for the destination field and setting the destination field.

All custom converters must be descended from this class.

Internally, opencsv uses another set of classes for the actual conversion, leaving this class mostly to deal with assigment to bean fields.

Since:

3.8

Author:

Andrew Rucker Jones

Field Summary

Fields

Modifier and Type	Field and Description
protected CsvConverter	converter A class that converts from a string to the destination type on reading and vice versa on writing.
protected Locale	errorLocale Locale for error messages.
protected Field	field The field this class represents.
protected FieldAccess<Object>	fieldAccess An encapsulated way of accessing the member variable associated with this field.
protected boolean	required Whether or not this field is required.
protected Class<?>	type The type the field is located in.

Constructor Summary

Constructors

Constructor and Description
AbstractBeanField() Default nullary constructor, so derived classes aren't forced to create a constructor identical to this one.
AbstractBeanField(Class<?> type, Field field, boolean required, Locale errorLocale, CsvConverter converter)

Method Summary

Modifier and Type	Method and Description
protected void	assignValueToField(Object bean, Object obj, String header) Assigns the given object to this field of the destination bean.
protected abstract Object	convert(String value) Method for converting from a string to the proper datatype of the destination field.
protected String	convertToWrite(Object value) This is the method that actually performs the conversion from field to string for write(java.lang.Object, java.lang.Object) and should be overridden in derived classes.
Locale	getErrorLocale() Returns the error locale for the beans.
Field	getField() Gets the field to be processed.
Object	getFieldValue(Object bean) Gets the contents of the selected field of the given bean.
Class<?>	getType() Gets the type of the bean this field is attached to.
Object[]	indexAndSplitMultivaluedField(Object value, I index) Given the value of a bean field and an index into that value, determine what values need to be written.
protected boolean	isFieldEmptyForWrite(Object value) Whether or not this implementation of BeanField considers the value passed in as empty for the purposes of determining whether or not a required field is empty.
boolean	isRequired() Answers the query, whether this field is required or not.
void	setErrorLocale(Locale errorLocale) Sets the locale for all error messages.
void	setField(Field field) Sets the field to be processed.
void	setFieldValue(Object bean, String value, String header) Populates the selected field of the bean.
void	setRequired(boolean required) Determines whether or not a field is required.
void	setType(Class<?> type) Sets the type of the bean this field is attached to.
String[]	write(Object bean, I index) This method takes the current value of the field in question in the bean passed in and converts it to a string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

type

protected Class<?> type

The type the field is located in. This is not necessarily the declaring class in the case of inheritance, but rather the type that opencsv expects to instantiate.

field

protected Field field

The field this class represents.

required

protected boolean required

Whether or not this field is required.

errorLocale

protected Locale errorLocale

Locale for error messages.

converter

protected CsvConverter converter

A class that converts from a string to the destination type on reading and vice versa on writing. This is only used for opencsv-internal conversions, not by custom converters.

fieldAccess

protected FieldAccess<Object> fieldAccess

An encapsulated way of accessing the member variable associated with this field.

Constructor Detail

AbstractBeanField

public AbstractBeanField()

Default nullary constructor, so derived classes aren't forced to create a constructor identical to this one.

AbstractBeanField

public AbstractBeanField(Class<?> type,
                         Field field,
                         boolean required,
                         Locale errorLocale,
                         CsvConverter converter)

Parameters:

type - The type of the class in which this field is found. This is the type as instantiated by opencsv, and not necessarily the type in which the field is declared in the case of inheritance.

field - A Field object.

required - Whether or not this field is required in input

errorLocale - The errorLocale to use for error messages.

converter - The converter to be used to perform the actual data conversion

Since:

4.2

Method Detail

getType

public Class<?> getType()

Description copied from interface: BeanField

Gets the type of the bean this field is attached to. This is necessary because the declaring class as given by the field itself may be a superclass of the class that is instantiated during bean population.

Specified by:

getType in interface BeanField<T,I>

Returns:

The type of the bean this field is attached to

setType

public void setType(Class<?> type)

Description copied from interface: BeanField

Sets the type of the bean this field is attached to.

Specified by:

setType in interface BeanField<T,I>

Parameters:

type - The type that is instantiated when this field is used

setField

public void setField(Field field)

Description copied from interface: BeanField

Sets the field to be processed.

Specified by:

setField in interface BeanField<T,I>

Parameters:

field - Which field is being populated

getField

public Field getField()

Description copied from interface: BeanField

Gets the field to be processed.

Specified by:

getField in interface BeanField<T,I>

Returns:

A field object

See Also:

Field

isRequired

public boolean isRequired()

Description copied from interface: BeanField

Answers the query, whether this field is required or not.

Specified by:

isRequired in interface BeanField<T,I>

Returns:

True if the field is required to be set (cannot be null or an empty string), false otherwise

setRequired

public void setRequired(boolean required)

Description copied from interface: BeanField

Determines whether or not a field is required. Implementation note: This method is necessary for custom converters. If we did not have it, every custom converter would be required to implement a constructor with this one boolean parameter, and the instantiation code for the custom converter would look much uglier.

Specified by:

setRequired in interface BeanField<T,I>

Parameters:

required - Whether or not the field is required

setErrorLocale

public void setErrorLocale(Locale errorLocale)

Description copied from interface: BeanField

Sets the locale for all error messages.

Specified by:

setErrorLocale in interface BeanField<T,I>

Parameters:

errorLocale - Locale for error messages. If null, the default locale is used.

getErrorLocale

public Locale getErrorLocale()

Description copied from interface: BeanField

Returns the error locale for the beans. Used by the opencsv provided validators to populate the error messages they generate.

Specified by:

getErrorLocale in interface BeanField<T,I>

Returns:

Locale for error messages.

setFieldValue

public final void setFieldValue(Object bean,
                                String value,
                                String header)
                         throws CsvDataTypeMismatchException,
                                CsvRequiredFieldEmptyException,
                                CsvConstraintViolationException,
                                CsvValidationException

Description copied from interface: BeanField

Populates the selected field of the bean. This method performs conversion on the input string and assigns the result to the proper field in the provided bean.

Specified by:

setFieldValue in interface BeanField<T,I>

Parameters:

bean - Object containing the field to be set.

value - String containing the value to set the field to.

header - The header from the CSV file under which this value was found.

Throws:

CsvDataTypeMismatchException - When the result of data conversion returns an object that cannot be assigned to the selected field

CsvRequiredFieldEmptyException - When a field is mandatory, but there is no input datum in the CSV file

CsvConstraintViolationException - When the internal structure of data would be violated by the data in the CSV file

CsvValidationException - If a user-supplied validator determines that the input is invalid

getFieldValue

public Object getFieldValue(Object bean)

Description copied from interface: BeanField

Gets the contents of the selected field of the given bean. This method performs no conversions of any kind, but simply gets the value of the desired field using an accessor method if one is available and reflection if one is not.

Specified by:

getFieldValue in interface BeanField<T,I>

Parameters:

bean - Object containing the field to be read

Returns:

The value of the field in the given bean

indexAndSplitMultivaluedField

public Object[] indexAndSplitMultivaluedField(Object value,
                                              I index)
                                       throws CsvDataTypeMismatchException

Description copied from interface: BeanField

Given the value of a bean field and an index into that value, determine what values need to be written. When writing a bean to a CSV file, some single fields from the bean could have values that need to be split into multiple fields when writing them to the CSV file. Given the value of the bean field and an index into the data, this method returns the objects to be converted and written.

Specified by:

indexAndSplitMultivaluedField in interface BeanField<T,I>

Parameters:

value - The value of the bean field that should be written

index - An index into value that determines which of the many possible values are currently being written. For header-based mapping strategies, this will be the header name, and for column position mapping strategies, it will be the zero-based column position.

Returns:

value wrapped in an array, since we assume most values will not be multi-valued

Throws:

CsvDataTypeMismatchException - If value is not of the type expected by the implementing class

Since:

4.2

isFieldEmptyForWrite

protected boolean isFieldEmptyForWrite(Object value)

Whether or not this implementation of BeanField considers the value passed in as empty for the purposes of determining whether or not a required field is empty.

This allows any overriding class to define "empty" while writing values to a CSV file in a way that is meaningful for its own data. A simple example is a Collection that is not null, but empty.

The default implementation simply checks for null.

Parameters:

value - The value of a field out of a bean that is being written to a CSV file. Can be null.

Returns:

Whether or not this implementation considers value to be empty for the purposes of its conversion

Since:

4.2

assignValueToField

protected void assignValueToField(Object bean,
                                  Object obj,
                                  String header)
                           throws CsvDataTypeMismatchException

Assigns the given object to this field of the destination bean.

Uses the setter method if available.

Derived classes can override this method if they have special needs for setting the value of a field, such as adding to an existing collection.

Parameters:

bean - The bean in which the field is located

obj - The data to be assigned to this field of the destination bean

header - The header from the CSV file under which this value was found.

Throws:

CsvDataTypeMismatchException - If the data to be assigned cannot be converted to the type of the destination field

convert

protected abstract Object convert(String value)
                           throws CsvDataTypeMismatchException,
                                  CsvConstraintViolationException

Method for converting from a string to the proper datatype of the destination field. This method must be specified in all non-abstract derived classes.

Parameters:

value - The string from the selected field of the CSV file. If the field is marked as required in the annotation, this value is guaranteed not to be null, empty or blank according to StringUtils.isBlank(java.lang.CharSequence)

Returns:

An Object representing the input data converted into the proper type

Throws:

CsvDataTypeMismatchException - If the input string cannot be converted into the proper type

CsvConstraintViolationException - When the internal structure of data would be violated by the data in the CSV file

write

public final String[] write(Object bean,
                            I index)
                     throws CsvDataTypeMismatchException,
                            CsvRequiredFieldEmptyException

This method takes the current value of the field in question in the bean passed in and converts it to a string. It is actually a stub that calls convertToWrite(java.lang.Object) for the actual conversion, and itself performs validation and handles exceptions thrown by convertToWrite(java.lang.Object). The validation consists of verifying that both bean and field are not null before calling convertToWrite(java.lang.Object).

Specified by:

write in interface BeanField<T,I>

Parameters:

bean - The bean holding the field to be written

index - The header name or column number of the field currently being processed. This can be used to find a certain position in a multivalued field when not all of the values should be written.

Returns:

An array of string representations for the values of this field out of the bean passed in. Typically, there will be only one value, but BeanFieldJoin may return multiple values. If either the bean or the field are null, this method returns an empty array to allow the writer to treat null specially. It is also possible that individual values in the array are null. The writer may wish to write "(null)" or "\0" or "NULL" or some other key instead of a blank string.

Throws:

CsvDataTypeMismatchException - If expected to convert an unsupported data type

CsvRequiredFieldEmptyException - If the field is marked as required, but is currently empty

convertToWrite

protected String convertToWrite(Object value)
                         throws CsvDataTypeMismatchException,
                                CsvRequiredFieldEmptyException

This is the method that actually performs the conversion from field to string for write(java.lang.Object, java.lang.Object) and should be overridden in derived classes.

The default implementation simply calls toString() on the object in question. Derived classes will, in most cases, want to override this method. Alternatively, for complex types, overriding the toString() method in the type of the field in question would also work fine.

Parameters:

value - The contents of the field currently being processed from the bean to be written. Can be null if the field is not marked as required.

Returns:

A string representation of the value of the field in question in the bean passed in, or an empty string if value is null

Throws:

CsvDataTypeMismatchException - This implementation does not throw this exception

CsvRequiredFieldEmptyException - If the input is empty but the field is required. The case of the field being null is checked before this method is called, but other implementations may have other cases that are semantically equivalent to being empty, such as an empty collection. The preferred way to perform this check is in isFieldEmptyForWrite(java.lang.Object). This exception may be removed from this method signature sometime in the future.

Since:

3.9

See Also:

write(java.lang.Object, java.lang.Object)