Class CsvReader.CsvReaderBuilder

java.lang.Object

de.siegmar.fastcsv.reader.CsvReader.CsvReaderBuilder

Enclosing class:

CsvReader<T>

public static final class CsvReader.CsvReaderBuilder
extends Object

This builder is used to create configured instances of CsvReader. The default configuration of this class adheres with RFC 4180:

• Field separator: , (comma)
• Quote character: " (double quotes)
• Comment strategy: CommentStrategy.NONE (as RFC doesn't handle comments)
• Comment character: # (hash) (in case comment strategy is enabled)
• Skip empty lines: true
• Ignore different field count: true
• Accept characters after quotes: true
• Detect BOM header: false
• Max buffer size: 16,777,216 characters

The line delimiter (line-feed, carriage-return or the combination of both) is detected automatically and thus not configurable.

Method Summary

Modifier and Type	Method	Description
CsvReader.CsvReaderBuilder	acceptCharsAfterQuotes(boolean acceptCharsAfterQuotes)	Specifies whether the presence of characters between a closing quote and a field separator or the end of a line should be treated as an error or not.
<T> CsvReader<T>	build(CsvCallbackHandler<T> callbackHandler, InputStream inputStream)	Constructs a new callback-based CsvReader for the specified input stream.
<T> CsvReader<T>	build(CsvCallbackHandler<T> callbackHandler, InputStream inputStream, Charset charset)	Constructs a new callback-based CsvReader for the specified input stream and character set.
<T> CsvReader<T>	build(CsvCallbackHandler<T> callbackHandler, Reader reader)	Constructs a new callback-based CsvReader for the specified reader.
<T> CsvReader<T>	build(CsvCallbackHandler<T> callbackHandler, String data)	Constructs a new callback-based CsvReader for the specified String.
<T> CsvReader<T>	build(CsvCallbackHandler<T> callbackHandler, Path file)	Constructs a new callback-based CsvReader for the specified file.
<T> CsvReader<T>	build(CsvCallbackHandler<T> callbackHandler, Path file, Charset charset)	Constructs a new callback-based CsvReader for the specified file and character set.
CsvReader.CsvReaderBuilder	commentCharacter(char commentCharacter)	Sets the commentCharacter used to comment lines.
CsvReader.CsvReaderBuilder	commentStrategy(CommentStrategy commentStrategy)	Sets the strategy that defines how (and if) commented lines should be handled (default: CommentStrategy.NONE as comments are not defined in RFC 4180).
CsvReader.CsvReaderBuilder	detectBomHeader(boolean detectBomHeader)	Defines if an optional BOM (Byte order mark) header should be detected.
CsvReader.CsvReaderBuilder	fieldSeparator(char fieldSeparator)	Sets the fieldSeparator used when reading CSV data.
CsvReader.CsvReaderBuilder	ignoreDifferentFieldCount(boolean ignoreDifferentFieldCount)	Defines if an CsvParseException should be thrown if records do contain a different number of fields.
CsvReader.CsvReaderBuilder	maxBufferSize(int maxBufferSize)	Defines the maximum buffer size used when parsing data.
CsvReader<CsvRecord>	ofCsvRecord(InputStream inputStream)	Constructs a new index-based CsvReader for the specified input stream.
CsvReader<CsvRecord>	ofCsvRecord(InputStream inputStream, Charset charset)	Constructs a new index-based CsvReader for the specified input stream and character set.
CsvReader<CsvRecord>	ofCsvRecord(Reader reader)	Constructs a new index-based CsvReader for the specified reader.
CsvReader<CsvRecord>	ofCsvRecord(String data)	Constructs a new index-based CsvReader for the specified String.
CsvReader<CsvRecord>	ofCsvRecord(Path file)	Constructs a new index-based CsvReader for the specified file.
CsvReader<CsvRecord>	ofCsvRecord(Path file, Charset charset)	Constructs a new index-based CsvReader for the specified file and character set.
CsvReader<NamedCsvRecord>	ofNamedCsvRecord(InputStream inputStream)	Constructs a new name-based CsvReader for the specified input stream.
CsvReader<NamedCsvRecord>	ofNamedCsvRecord(InputStream inputStream, Charset charset)	Constructs a new name-based CsvReader for the specified input stream and character set.
CsvReader<NamedCsvRecord>	ofNamedCsvRecord(Reader reader)	Constructs a new name-based CsvReader for the specified reader.
CsvReader<NamedCsvRecord>	ofNamedCsvRecord(String data)	Constructs a new name-based CsvReader for the specified String.
CsvReader<NamedCsvRecord>	ofNamedCsvRecord(Path file)	Constructs a new name-based CsvReader for the specified file.
CsvReader<NamedCsvRecord>	ofNamedCsvRecord(Path file, Charset charset)	Constructs a new name-based CsvReader for the specified file and character set.
CsvReader.CsvReaderBuilder	quoteCharacter(char quoteCharacter)	Sets the quoteCharacter used when reading CSV data.
CsvReader.CsvReaderBuilder	skipEmptyLines(boolean skipEmptyLines)	Defines whether empty lines should be skipped when reading data.
String	toString()

Methods inherited from class java.lang.Object

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

Method Details

fieldSeparator

public CsvReader.CsvReaderBuilder fieldSeparator(char fieldSeparator)

Sets the fieldSeparator used when reading CSV data.

Parameters:

fieldSeparator - the field separator character (default: , - comma).

Returns:

This updated object, allowing additional method calls to be chained together.

quoteCharacter

public CsvReader.CsvReaderBuilder quoteCharacter(char quoteCharacter)

Sets the quoteCharacter used when reading CSV data.

Parameters:

quoteCharacter - the character used to enclose fields (default: " - double quotes).

Returns:

This updated object, allowing additional method calls to be chained together.

commentStrategy

public CsvReader.CsvReaderBuilder commentStrategy(CommentStrategy commentStrategy)

Sets the strategy that defines how (and if) commented lines should be handled (default: CommentStrategy.NONE as comments are not defined in RFC 4180).

If a comment strategy other than CommentStrategy.NONE is used, special parsing rules are applied for commented lines. FastCSV defines a comment as a line that starts with a comment character. No (whitespace) character is allowed before the comment character. Everything after the comment character until the end of the line is considered the comment value.

Parameters:

commentStrategy - the strategy for handling comments.

Returns:

This updated object, allowing additional method calls to be chained together.

See Also:

• commentCharacter(char)

commentCharacter

public CsvReader.CsvReaderBuilder commentCharacter(char commentCharacter)

Sets the commentCharacter used to comment lines.

Parameters:

commentCharacter - the character used to comment lines (default: # - hash)

Returns:

This updated object, allowing additional method calls to be chained together.

See Also:

• commentStrategy(CommentStrategy)

skipEmptyLines

public CsvReader.CsvReaderBuilder skipEmptyLines(boolean skipEmptyLines)

Defines whether empty lines should be skipped when reading data.

The default implementation interprets empty lines as lines that do not contain any data (no whitespace, no quotes, nothing).

Commented lines are not considered empty lines. Use commentStrategy(CommentStrategy) for handling commented lines.

Parameters:

skipEmptyLines - Whether empty lines should be skipped (default: true).

Returns:

This updated object, allowing additional method calls to be chained together.

ignoreDifferentFieldCount

public CsvReader.CsvReaderBuilder ignoreDifferentFieldCount(boolean ignoreDifferentFieldCount)

Defines if an CsvParseException should be thrown if records do contain a different number of fields.

Parameters:

ignoreDifferentFieldCount - if exception should be suppressed, when CSV data contains different field count (default: true).

Returns:

This updated object, allowing additional method calls to be chained together.

acceptCharsAfterQuotes

public CsvReader.CsvReaderBuilder acceptCharsAfterQuotes(boolean acceptCharsAfterQuotes)

Specifies whether the presence of characters between a closing quote and a field separator or the end of a line should be treated as an error or not.

Example: "a"b,"c"

If this is set to true, the value ab will be returned for the first field.

If this is set to false, a CsvParseException will be thrown.

Parameters:

acceptCharsAfterQuotes - allow characters after quotes (default: true).

Returns:

This updated object, allowing additional method calls to be chained together.

detectBomHeader

public CsvReader.CsvReaderBuilder detectBomHeader(boolean detectBomHeader)

Defines if an optional BOM (Byte order mark) header should be detected.

BOM detection only applies for InputStream and Path based data sources. It does not apply for Reader or String based data sources as they are already decoded.

Supported BOMs are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.

Parameters:

detectBomHeader - if detection should be enabled (default: false)

Returns:

This updated object, allowing additional method calls to be chained together.

maxBufferSize

public CsvReader.CsvReaderBuilder maxBufferSize(int maxBufferSize)

Defines the maximum buffer size used when parsing data.

The size of the internal buffer is automatically adjusted to the needs of the parser. To protect against out-of-memory errors, its maximum size is limited.

The buffer is used for two purposes:

• Reading data from the underlying stream of data in chunks
• Storing the data of a single field before it is passed to the callback handler

Set a larger value only if you expect to read fields larger than the default limit. In that case you probably also need to adjust the maximum field size of the callback handler.

Set a smaller value if your runtime environment has not enough memory available for the default value. Setting values smaller than 16,384 characters will most likely lead to performance degradation.

Parameters:

maxBufferSize - the maximum buffer size in characters (default: 16,777,216)

Returns:

This updated object, allowing additional method calls to be chained together.

Throws:

IllegalArgumentException - if maxBufferSize is not positive

ofCsvRecord

public CsvReader<CsvRecord> ofCsvRecord(InputStream inputStream)

Constructs a new index-based CsvReader for the specified input stream.

This is a convenience method for calling build(CsvCallbackHandler,InputStream) with CsvRecordHandler as callback handler.

If detectBomHeader(boolean) is enabled, the character set is determined by the BOM header. Per default the character set is StandardCharsets.UTF_8.

Parameters:

inputStream - the input stream to read data from.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if inputStream is null

See Also:

• ofCsvRecord(InputStream, Charset)

ofCsvRecord

public CsvReader<CsvRecord> ofCsvRecord(InputStream inputStream,
 Charset charset)

Constructs a new index-based CsvReader for the specified input stream and character set.

This is a convenience method for calling build(CsvCallbackHandler,InputStream,Charset) with CsvRecordHandler as callback handler.

Parameters:

inputStream - the input stream to read data from.

charset - the character set to use. If BOM header detection is enabled (via detectBomHeader(boolean)), this acts as a default when no BOM header was found.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if inputStream or charset is null

See Also:

• ofCsvRecord(InputStream)

ofCsvRecord

public CsvReader<CsvRecord> ofCsvRecord(Reader reader)

Constructs a new index-based CsvReader for the specified reader.

This is a convenience method for calling build(CsvCallbackHandler,Reader) with CsvRecordHandler as callback handler.

detectBomHeader(boolean) has no effect on this method.

Parameters:

reader - the data source to read from.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if reader is null

ofCsvRecord

public CsvReader<CsvRecord> ofCsvRecord(String data)

Constructs a new index-based CsvReader for the specified String.

This is a convenience method for calling build(CsvCallbackHandler,String) with CsvRecordHandler as callback handler.

detectBomHeader(boolean) has no effect on this method.

Parameters:

data - the data to read.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if data is null

ofCsvRecord

public CsvReader<CsvRecord> ofCsvRecord(Path file)
                                 throws IOException

Constructs a new index-based CsvReader for the specified file.

This is a convenience method for calling build(CsvCallbackHandler,Path) with CsvRecordHandler as callback handler.

If detectBomHeader(boolean) is enabled, the character set is determined by the BOM header. Per default the character set is StandardCharsets.UTF_8.

Parameters:

file - the file to read data from.

Returns:

a new CsvReader - never null. Don't forget to close it!

Throws:

IOException - if an I/O error occurs.

NullPointerException - if file is null

See Also:

• ofCsvRecord(Path, Charset)

ofCsvRecord

public CsvReader<CsvRecord> ofCsvRecord(Path file,
 Charset charset)
                                 throws IOException

Constructs a new index-based CsvReader for the specified file and character set.

This is a convenience method for calling build(CsvCallbackHandler,Path,Charset) with CsvRecordHandler as callback handler.

Parameters:

file - the file to read data from.

charset - the character set to use. If BOM header detection is enabled (via detectBomHeader(boolean)), this acts as a default when no BOM header was found.

Returns:

a new CsvReader - never null. Don't forget to close it!

Throws:

IOException - if an I/O error occurs.

NullPointerException - if file or charset is null

See Also:

• ofCsvRecord(Path)

ofNamedCsvRecord

public CsvReader<NamedCsvRecord> ofNamedCsvRecord(InputStream inputStream)

Constructs a new name-based CsvReader for the specified input stream.

This is a convenience method for calling build(CsvCallbackHandler,InputStream) with NamedCsvRecordHandler as callback handler.

If detectBomHeader(boolean) is enabled, the character set is determined by the BOM header. Per default the character set is StandardCharsets.UTF_8.

Parameters:

inputStream - the input stream to read data from.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if reader is null

See Also:

• ofNamedCsvRecord(InputStream, Charset)

ofNamedCsvRecord

public CsvReader<NamedCsvRecord> ofNamedCsvRecord(InputStream inputStream,
 Charset charset)

Constructs a new name-based CsvReader for the specified input stream and character set.

This is a convenience method for calling build(CsvCallbackHandler,InputStream,Charset) with NamedCsvRecordHandler as callback handler.

Parameters:

inputStream - the input stream to read data from.

charset - the character set to use. If BOM header detection is enabled (via detectBomHeader(boolean)), this acts as a default when no BOM header was found.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if file or charset is null

See Also:

• ofNamedCsvRecord(InputStream)

ofNamedCsvRecord

public CsvReader<NamedCsvRecord> ofNamedCsvRecord(Reader reader)

Constructs a new name-based CsvReader for the specified reader.

This is a convenience method for calling build(CsvCallbackHandler,Reader) with NamedCsvRecordHandler as callback handler.

detectBomHeader(boolean) has no effect on this method.

Parameters:

reader - the data source to read from.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if reader is null

ofNamedCsvRecord

public CsvReader<NamedCsvRecord> ofNamedCsvRecord(String data)

Constructs a new name-based CsvReader for the specified String.

This is a convenience method for calling build(CsvCallbackHandler,String) with NamedCsvRecordHandler as callback handler.

detectBomHeader(boolean) has no effect on this method.

Parameters:

data - the data to read.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if data is null

ofNamedCsvRecord

public CsvReader<NamedCsvRecord> ofNamedCsvRecord(Path file)
                                           throws IOException

Constructs a new name-based CsvReader for the specified file.

This is a convenience method for calling build(CsvCallbackHandler,Path) with NamedCsvRecordHandler as callback handler.

If detectBomHeader(boolean) is enabled, the character set is determined by the BOM header. Per default the character set is StandardCharsets.UTF_8.

Parameters:

file - the file to read data from.

Returns:

a new CsvReader - never null. Don't forget to close it!

Throws:

IOException - if an I/O error occurs.

NullPointerException - if file is null

See Also:

• ofNamedCsvRecord(Path, Charset)

ofNamedCsvRecord

public CsvReader<NamedCsvRecord> ofNamedCsvRecord(Path file,
 Charset charset)
                                           throws IOException

Constructs a new name-based CsvReader for the specified file and character set.

This is a convenience method for calling build(CsvCallbackHandler,Path,Charset) with NamedCsvRecordHandler as callback handler.

Parameters:

file - the file to read data from.

charset - the character set to use. If BOM header detection is enabled (via detectBomHeader(boolean)), this acts as a default when no BOM header was found.

Returns:

a new CsvReader - never null. Don't forget to close it!

Throws:

IOException - if an I/O error occurs.

NullPointerException - if file or charset is null

See Also:

• ofNamedCsvRecord(Path)

build

public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler,
 InputStream inputStream)

Constructs a new callback-based CsvReader for the specified input stream.

This is a convenience method for calling build(CsvCallbackHandler,InputStream,Charset).

This library uses built-in buffering, so you do not need to pass in a buffered InputStream implementation such as BufferedInputStream. Performance may be even likely better if you do not.

If detectBomHeader(boolean) is enabled, the character set is determined by the BOM header. Per default the character set is StandardCharsets.UTF_8.

Use build(CsvCallbackHandler,Path) for optimal performance when reading files.

Type Parameters:

T - the type of the CSV record.

Parameters:

callbackHandler - the record handler to use. Do not reuse a handler after it has been used!

inputStream - the input stream to read data from.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if callbackHandler or inputStream is null

See Also:

• build(CsvCallbackHandler, InputStream, Charset)

build

public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler,
 InputStream inputStream,
 Charset charset)

Constructs a new callback-based CsvReader for the specified input stream and character set.

This library uses built-in buffering, so you do not need to pass in a buffered InputStream implementation such as BufferedInputStream. Performance may be even likely better if you do not.

If detectBomHeader(boolean) is enabled, this method will immediately cause consumption of the input stream to read the BOM header and determine the character set.

Use build(CsvCallbackHandler,Path,Charset) for optimal performance when reading files.

Type Parameters:

T - the type of the CSV record.

Parameters:

callbackHandler - the record handler to use. Do not reuse a handler after it has been used!

inputStream - the input stream to read data from.

charset - the character set to use. If BOM header detection is enabled (via detectBomHeader(boolean)), this acts as a default when no BOM header was found.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if callbackHandler, inputStream or charset is null

See Also:

• build(CsvCallbackHandler, InputStream)

build

public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler,
 Reader reader)

Constructs a new callback-based CsvReader for the specified reader.

This library uses built-in buffering, so you do not need to pass in a buffered Reader implementation such as BufferedReader. Performance may be even likely better if you do not.

Use build(CsvCallbackHandler,Path) for optimal performance when reading files and build(CsvCallbackHandler,String) when reading Strings.

detectBomHeader(boolean) has no effect on this method.

Type Parameters:

T - the type of the CSV record.

Parameters:

callbackHandler - the record handler to use. Do not reuse a handler after it has been used!

reader - the data source to read from.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if callbackHandler or reader is null

IllegalArgumentException - if argument validation fails.

build

public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler,
 String data)

Constructs a new callback-based CsvReader for the specified String.

detectBomHeader(boolean) has no effect on this method.

Type Parameters:

T - the type of the CSV record.

Parameters:

callbackHandler - the record handler to use. Do not reuse a handler after it has been used!

data - the data to read.

Returns:

a new CsvReader - never null.

Throws:

NullPointerException - if callbackHandler or data is null

IllegalArgumentException - if argument validation fails.

build

public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler,
 Path file)
                       throws IOException

Constructs a new callback-based CsvReader for the specified file.

If detectBomHeader(boolean) is enabled, the character set is determined by the BOM header. Per default the character set is StandardCharsets.UTF_8.

Type Parameters:

T - the type of the CSV record.

Parameters:

callbackHandler - the record handler to use. Do not reuse a handler after it has been used!

file - the file to read data from.

Returns:

a new CsvReader - never null. Remember to close it!

Throws:

IOException - if an I/O error occurs.

NullPointerException - if callbackHandler or file is null

See Also:

• build(CsvCallbackHandler, Path, Charset)

build

public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler,
 Path file,
 Charset charset)
                       throws IOException

Constructs a new callback-based CsvReader for the specified file and character set.

Type Parameters:

T - the type of the CSV record.

Parameters:

callbackHandler - the record handler to use. Do not reuse a handler after it has been used!

file - the file to read data from.

charset - the character set to use. If BOM header detection is enabled (via detectBomHeader(boolean)), this acts as a default when no BOM header was found.

Returns:

a new CsvReader - never null. Remember to close it!

Throws:

IOException - if an I/O error occurs.

NullPointerException - if callbackHandler, file or charset is null

See Also:

• build(CsvCallbackHandler, Path)

toString

public String toString()

Overrides:

toString in class Object