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

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

  • Field Details

    • fieldSeparator

      private char fieldSeparator
    • quoteCharacter

      private char quoteCharacter
    • commentStrategy

      private CommentStrategy commentStrategy
    • commentCharacter

      private char commentCharacter
    • skipEmptyLines

      private boolean skipEmptyLines
    • ignoreDifferentFieldCount

      private boolean ignoreDifferentFieldCount
    • acceptCharsAfterQuotes

      private boolean acceptCharsAfterQuotes
    • detectBomHeader

      private boolean detectBomHeader
  • Constructor Details

    • CsvReaderBuilder

      private CsvReaderBuilder()
  • 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

      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:
    • 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 direct file access.

      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.
    • ofCsvRecord

      public CsvReader<CsvRecord> ofCsvRecord(Reader reader)
      Constructs a new CsvReader that uses CsvRecord as record type.

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

      Parameters:
      reader - the data source to read from.
      Returns:
      a new CsvReader of CsvRecord - never null.
      Throws:
      NullPointerException - if reader is null
    • ofCsvRecord

      public CsvReader<CsvRecord> ofCsvRecord(String data)
      Constructs a new CsvReader for the specified arguments.

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

      Parameters:
      data - the data to read.
      Returns:
      a new CsvReader of CsvRecord - never null.
      Throws:
      NullPointerException - if data is null
    • ofCsvRecord

      public CsvReader<CsvRecord> ofCsvRecord(Path file) throws IOException
      Constructs a new CsvReader for the specified file.

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

      Parameters:
      file - the file to read data from.
      Returns:
      a new CsvReader of CsvRecord - never null. Don't forget to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if file is null
    • ofCsvRecord

      public CsvReader<CsvRecord> ofCsvRecord(Path file, Charset charset) throws IOException
      Constructs a new CsvReader for the specified file.

      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 of CsvRecord - never null. Don't forget to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if file or charset is null
    • ofNamedCsvRecord

      public CsvReader<NamedCsvRecord> ofNamedCsvRecord(Reader reader)
      Constructs a new CsvReader that uses CsvRecord as record type.

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

      Parameters:
      reader - the data source to read from.
      Returns:
      a new CsvReader of CsvRecord - never null.
      Throws:
      NullPointerException - if reader is null
    • ofNamedCsvRecord

      public CsvReader<NamedCsvRecord> ofNamedCsvRecord(String data)
      Constructs a new CsvReader for the specified arguments.

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

      Parameters:
      data - the data to read.
      Returns:
      a new CsvReader of CsvRecord - never null.
      Throws:
      NullPointerException - if data is null
    • ofNamedCsvRecord

      public CsvReader<NamedCsvRecord> ofNamedCsvRecord(Path file) throws IOException
      Constructs a new CsvReader for the specified file.

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

      Parameters:
      file - the file to read data from.
      Returns:
      a new CsvReader of CsvRecord - never null. Don't forget to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if file is null
    • ofNamedCsvRecord

      public CsvReader<NamedCsvRecord> ofNamedCsvRecord(Path file, Charset charset) throws IOException
      Constructs a new CsvReader for the specified file.

      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 of CsvRecord - never null. Don't forget to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if file or charset is null
    • build

      public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler, Reader reader)
      Constructs a new CsvReader for the specified arguments.

      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.

      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
    • build

      public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler, String data)
      Constructs a new CsvReader for the specified arguments.
      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
    • build

      public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler, Path file) throws IOException
      Constructs a new CsvReader for the specified file.

      This is a convenience method for calling build(file, StandardCharsets.UTF_8, callbackHandler).

      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
    • build

      public <T> CsvReader<T> build(CsvCallbackHandler<T> callbackHandler, Path file, Charset charset) throws IOException
      Constructs a new CsvReader for the specified arguments.
      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
    • newReader

      private <T> CsvReader<T> newReader(CsvCallbackHandler<T> callbackHandler, CsvParser csvParser)
    • toString

      public String toString()
      Overrides:
      toString in class Object