com.opencsv.bean

Class CsvToBeanBuilder<T>

java.lang.Object

com.opencsv.bean.CsvToBeanBuilder<T>

Type Parameters:

T - Type of the bean to be populated

public class CsvToBeanBuilder<T>
extends Object

This class makes it possible to bypass all the intermediate steps and classes in setting up to read from a CSV source to a list of beans.

This is the place to start if you're reading a CSV source into beans, especially if you're binding the input's columns to the bean's variables using the annotations CsvBindByName, CsvCustomBindByName, CsvBindByPosition, or CsvCustomBindByPosition.

If you want nothing but defaults for the entire import, your code can look as simple as this, where myreader is any valid Reader:
List<MyBean> result = new CsvToBeanBuilder(myreader).withType(MyBean.class).build().parse();

This builder is intelligent enough to guess the mapping strategy according to the following strategy:

1. If a mapping strategy is explicitly set, it is always used.
2. If CsvBindByPosition or CsvCustomBindByPosition is present, ColumnPositionMappingStrategy is used.
3. Otherwise, HeaderColumnNameMappingStrategy is used. This includes the case when CsvBindByName or CsvCustomBindByName are being used. The annotations will automatically be recognized.

Since:

3.9

Author:

Andrew Rucker Jones

Constructor Summary

Constructors

Constructor and Description
CsvToBeanBuilder(CSVReader csvReader) Constructor with the one parameter that is most definitely mandatory, and always will be.
CsvToBeanBuilder(Reader reader) Constructor with the one parameter that is most definitely mandatory, and always will be.

Method Summary

Modifier and Type	Method and Description
CsvToBean<T>	build() Builds the CsvToBean out of the provided information.
CsvToBeanBuilder<T>	withErrorLocale(Locale errorLocale) Sets the locale for all error messages.
CsvToBeanBuilder<T>	withEscapeChar(char escapeChar)
CsvToBeanBuilder<T>	withExceptionHandler(CsvExceptionHandler exceptionHandler) Sets the handler for recoverable exceptions raised during processing of records.
CsvToBeanBuilder<T>	withFieldAsNull(CSVReaderNullFieldIndicator indicator)
CsvToBeanBuilder<T>	withFilter(CsvToBeanFilter filter)
CsvToBeanBuilder<T>	withIgnoreEmptyLine(boolean ignore)
CsvToBeanBuilder<T>	withIgnoreField(Class<?> type, Field field) Adds a Field to the list of fields opencsv should ignore completely.
CsvToBeanBuilder<T>	withIgnoreLeadingWhiteSpace(boolean ignoreLeadingWhiteSpace)
CsvToBeanBuilder<T>	withIgnoreQuotations(boolean ignoreQuotations)
CsvToBeanBuilder<T>	withKeepCarriageReturn(boolean keepCR)
CsvToBeanBuilder<T>	withMappingStrategy(MappingStrategy<? extends T> mappingStrategy)
CsvToBeanBuilder<T>	withMultilineLimit(int multilineLimit) Sets the maximum number of lines allowed in a multiline record.
CsvToBeanBuilder<T>	withOrderedResults(boolean orderedResults) Sets whether the resulting beans must be ordered as in the input.
CsvToBeanBuilder<T>	withProfile(String profile) Selects a profile for deciding which configurations to use for the bean fields.
CsvToBeanBuilder<T>	withQuoteChar(char quoteChar)
CsvToBeanBuilder<T>	withSeparator(char separator)
CsvToBeanBuilder<T>	withSkipLines(int skipLines)
CsvToBeanBuilder<T>	withStrictQuotes(boolean strictQuotes)
CsvToBeanBuilder<T>	withThrowExceptions(boolean throwExceptions) Sets how the CsvToBean will act when an exception occurs.
CsvToBeanBuilder<T>	withType(Class<? extends T> type) Sets the type of the bean to be populated.
CsvToBeanBuilder<T>	withVerifier(BeanVerifier<T> verifier) Adds a BeanVerifier to the list of verifiers to run on all beans created.
CsvToBeanBuilder<T>	withVerifyReader(boolean verifyReader)

Methods inherited from class java.lang.Object

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

Constructor Detail

CsvToBeanBuilder

public CsvToBeanBuilder(Reader reader)

Constructor with the one parameter that is most definitely mandatory, and always will be.

Parameters:

reader - The reader that is the source of data for the CSV import

CsvToBeanBuilder

public CsvToBeanBuilder(CSVReader csvReader)

Constructor with the one parameter that is most definitely mandatory, and always will be.

Parameters:

csvReader - The CSVReader that is the source of data for the CSV import

Method Detail

build

public CsvToBean<T> build()
                   throws IllegalStateException

Builds the CsvToBean out of the provided information.

Returns:

A valid CsvToBean

Throws:

IllegalStateException - If a necessary parameter was not specified. Currently this means that both the mapping strategy and the bean type are not set, so it is impossible to determine a mapping strategy.

withMappingStrategy

public CsvToBeanBuilder<T> withMappingStrategy(MappingStrategy<? extends T> mappingStrategy)

Parameters:

mappingStrategy - Please see the "See Also" section

Returns:

this

See Also:

CsvToBean.setMappingStrategy(com.opencsv.bean.MappingStrategy)

withFilter

public CsvToBeanBuilder<T> withFilter(CsvToBeanFilter filter)

Parameters:

filter - Please see the "See Also" section

Returns:

this

See Also:

CsvToBean.setFilter(com.opencsv.bean.CsvToBeanFilter)

withThrowExceptions

public CsvToBeanBuilder<T> withThrowExceptions(boolean throwExceptions)

Sets how the CsvToBean will act when an exception occurs. If both withThrowsExcpetion and withExceptionHandler(CsvExceptionHandler) are used then the withExceptionHandler takes precedence and is used.

Parameters:

throwExceptions - Please see the "See Also" section

Returns:

this

See Also:

CsvToBean.setThrowExceptions(boolean), withExceptionHandler(CsvExceptionHandler)

withExceptionHandler

public CsvToBeanBuilder<T> withExceptionHandler(CsvExceptionHandler exceptionHandler)

Sets the handler for recoverable exceptions raised during processing of records. If both withThrowExceptions(boolean) and withExceptionHandler are used then the withExceptionHandler takes precedence and is used.

If neither this method nor withThrowExceptions(boolean) is called, the default exception handler is ExceptionHandlerThrow.

Please note that if both this method and withThrowExceptions(boolean) are called, the last call wins.

Parameters:

exceptionHandler - The exception handler to be used. If null, this method does nothing.

Returns:

this

Since:

5.2

withFieldAsNull

public CsvToBeanBuilder<T> withFieldAsNull(CSVReaderNullFieldIndicator indicator)

Parameters:

indicator - Which field content will be returned as null: EMPTY_SEPARATORS, EMPTY_QUOTES, BOTH, NEITHER (default)

Returns:

this

withKeepCarriageReturn

public CsvToBeanBuilder<T> withKeepCarriageReturn(boolean keepCR)

Parameters:

keepCR - True to keep carriage returns in data read, false otherwise

Returns:

this

withVerifyReader

public CsvToBeanBuilder<T> withVerifyReader(boolean verifyReader)

Parameters:

verifyReader - Please see the "See Also" section

Returns:

this

See Also:

CSVReaderBuilder.withVerifyReader(boolean)

withSkipLines

public CsvToBeanBuilder<T> withSkipLines(int skipLines)

Parameters:

skipLines - Please see the "See Also" section

Returns:

this

See Also:

CSVReaderBuilder.withSkipLines(int)

withSeparator

public CsvToBeanBuilder<T> withSeparator(char separator)

Parameters:

separator - Please see the "See Also" section

Returns:

this

See Also:

CSVParser(char, char, char, boolean, boolean, boolean, CSVReaderNullFieldIndicator, Locale)

withQuoteChar

public CsvToBeanBuilder<T> withQuoteChar(char quoteChar)

Parameters:

quoteChar - Please see the "See Also" section

Returns:

this

See Also:

CSVParser(char, char, char, boolean, boolean, boolean, CSVReaderNullFieldIndicator, Locale)

withEscapeChar

public CsvToBeanBuilder<T> withEscapeChar(char escapeChar)

Parameters:

escapeChar - Please see the "See Also" section

Returns:

this

See Also:

CSVParser(char, char, char, boolean, boolean, boolean, CSVReaderNullFieldIndicator, Locale)

withStrictQuotes

public CsvToBeanBuilder<T> withStrictQuotes(boolean strictQuotes)

Parameters:

strictQuotes - Please see the "See Also" section

Returns:

this

See Also:

CSVParser(char, char, char, boolean, boolean, boolean, CSVReaderNullFieldIndicator, Locale)

withIgnoreLeadingWhiteSpace

public CsvToBeanBuilder<T> withIgnoreLeadingWhiteSpace(boolean ignoreLeadingWhiteSpace)

Parameters:

ignoreLeadingWhiteSpace - Please see the "See Also" section

Returns:

this

See Also:

CSVParser(char, char, char, boolean, boolean, boolean, CSVReaderNullFieldIndicator, Locale)

withIgnoreQuotations

public CsvToBeanBuilder<T> withIgnoreQuotations(boolean ignoreQuotations)

Parameters:

ignoreQuotations - Please see the "See Also" section

Returns:

this

See Also:

CSVParser(char, char, char, boolean, boolean, boolean, CSVReaderNullFieldIndicator, Locale)

withType

public CsvToBeanBuilder<T> withType(Class<? extends T> type)

Sets the type of the bean to be populated. Ignored if withMappingStrategy(com.opencsv.bean.MappingStrategy) is called.

Parameters:

type - Class of the destination bean

Returns:

this

See Also:

AbstractMappingStrategy.setType(java.lang.Class), AbstractMappingStrategy.setType(java.lang.Class)

withMultilineLimit

public CsvToBeanBuilder<T> withMultilineLimit(int multilineLimit)

Sets the maximum number of lines allowed in a multiline record. More than this number in one record results in an IOException.

Parameters:

multilineLimit - No more than this number of lines is allowed in a single input record. The default is CSVReader.DEFAULT_MULTILINE_LIMIT.

Returns:

this

withOrderedResults

public CsvToBeanBuilder<T> withOrderedResults(boolean orderedResults)

Sets whether the resulting beans must be ordered as in the input.

Parameters:

orderedResults - Whether to order the results or not

Returns:

this

Since:

4.0

See Also:

CsvToBean.setOrderedResults(boolean)

withErrorLocale

public CsvToBeanBuilder<T> withErrorLocale(Locale errorLocale)

Sets the locale for all error messages.

Parameters:

errorLocale - Locale for error messages

Returns:

this

Since:

4.0

See Also:

CsvToBean.setErrorLocale(java.util.Locale)

withVerifier

public CsvToBeanBuilder<T> withVerifier(BeanVerifier<T> verifier)

Adds a BeanVerifier to the list of verifiers to run on all beans created. This method may be called as many times as desired. All added verifiers will be run on every bean. No guarantee is made as to the order in which the verifiers are run.

Parameters:

verifier - A new verifier that is to process all beans after creation. null is permissible but has no effect.

Returns:

this

Since:

4.4

withIgnoreField

public CsvToBeanBuilder<T> withIgnoreField(Class<?> type,
                                           Field field)
                                    throws IllegalArgumentException

Adds a Field to the list of fields opencsv should ignore completely.

May be called as many times as necessary.

Parameters:

type - The class opencsv will encounter the field in during processing. In the case of inheritance, this may not be the declaring class.

field - The field opencsv is to ignore

Returns:

this

Throws:

IllegalArgumentException - If one of the parameters is null or field cannot be found in type.

Since:

5.0

See Also:

MappingStrategy.ignoreFields(MultiValuedMap)

withIgnoreEmptyLine

public CsvToBeanBuilder<T> withIgnoreEmptyLine(boolean ignore)

Parameters:

ignore - Please see the "See Also" section

Returns:

this

See Also:

CsvToBean.ignoreEmptyLines

withProfile

public CsvToBeanBuilder<T> withProfile(String profile)

Selects a profile for deciding which configurations to use for the bean fields.

Parameters:

profile - The name of the profile to be used

Returns:

this

Since:

5.4