Class IndexedCsvReader.IndexedCsvReaderBuilder

java.lang.Object
de.siegmar.fastcsv.reader.IndexedCsvReader.IndexedCsvReaderBuilder
Enclosing class:
IndexedCsvReader<T>
public static final class IndexedCsvReader.IndexedCsvReaderBuilder extends Object

This builder is used to create configured instances of IndexedCsvReader. 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)
  • Allow extra characters after closing quotes: 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 Details

    • fieldSeparator

      public IndexedCsvReader.IndexedCsvReaderBuilder 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 IndexedCsvReader.IndexedCsvReaderBuilder 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 IndexedCsvReader.IndexedCsvReaderBuilder 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).
      Parameters:
      commentStrategy - the strategy for handling comments.
      Returns:
      This updated object, allowing additional method calls to be chained together.
      Throws:
      IllegalArgumentException - if CommentStrategy.SKIP is passed, as this is not supported
      See Also:

    • commentCharacter

      public IndexedCsvReader.IndexedCsvReaderBuilder 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:

    • allowExtraCharsAfterClosingQuote

      @Deprecated(forRemoval=true) public IndexedCsvReader.IndexedCsvReaderBuilder allowExtraCharsAfterClosingQuote(boolean allowExtraCharsAfterClosingQuote)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This option permits non-conforming input (RFC 4180 does not allow any character between a closing quote and the field separator or end of line) and yields unspecified results if the extra characters contain quote characters. For sequential reading, CsvReader.CsvReaderBuilder.trimWhitespacesAroundQuotes(boolean) provides a saner alternative.

      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:
      allowExtraCharsAfterClosingQuote - allow extra characters after closing quotes (default: false).
      Returns:
      This updated object, allowing additional method calls to be chained together.
      See Also:

    • allowUnclosedQuote

      public IndexedCsvReader.IndexedCsvReaderBuilder allowUnclosedQuote(boolean allowUnclosedQuote)

      Defines whether input that ends inside a quoted field (EOF before a closing quote) is tolerated.

      Example: "foo,bar

      If this is set to true, the value foo,bar will be returned as a single field; otherwise, a CsvParseException will be thrown.

      Independent of this flag, a CsvParseException is thrown if the unclosed region exceeds maxBufferSize(int).

      The default will change to false in version 5.0.

      Parameters:
      allowUnclosedQuote - allow input ending inside a quoted field (default: true).
      Returns:
      This updated object, allowing additional method calls to be chained together.

    • statusListener

      public IndexedCsvReader.IndexedCsvReaderBuilder statusListener(StatusListener statusListener)
      Sets the statusListener to listen for indexer status updates.
      Parameters:
      statusListener - the status listener.
      Returns:
      This updated object, allowing additional method calls to be chained together.

    • index

      public IndexedCsvReader.IndexedCsvReaderBuilder index(CsvIndex csvIndex)

      Sets a prebuilt index that should be used for accessing the file.

      The file and all settings – including pageSize(int) – have to be the ones the index was built with; otherwise an IllegalArgumentException is thrown.

      Parameters:
      csvIndex - a prebuilt index
      Returns:
      This updated object, allowing additional method calls to be chained together.

    • pageSize

      public IndexedCsvReader.IndexedCsvReaderBuilder pageSize(int pageSize)

      Sets the pageSize for pages returned by IndexedCsvReader.readPage(int) (default: DEFAULT_PAGE_SIZE).

      One index entry (roughly 40 bytes of heap) is kept per pageSize records – a smaller page size grants finer-grained random access at the cost of memory.

      Parameters:
      pageSize - the maximum size of pages.
      Returns:
      This updated object, allowing additional method calls to be chained together.

    • maxBufferSize

      public IndexedCsvReader.IndexedCsvReaderBuilder 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 IndexedCsvReader<CsvRecord> ofCsvRecord(Path file) throws IOException

      Constructs a new IndexedCsvReader of CsvRecord for the specified path using UTF-8 as the character set.

      Convenience method for build(CsvCallbackHandler,Path,Charset) with CsvRecordHandler as the callback handler and StandardCharsets.UTF_8 as the charset.

      Parameters:
      file - the file to read data from.
      Returns:
      a new IndexedCsvReader - never null. Remember to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if file or charset is null

    • ofCsvRecord

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

      Constructs a new IndexedCsvReader of CsvRecord for the specified arguments.

      Convenience method for build(CsvCallbackHandler,Path,Charset) with CsvRecordHandler as the callback handler.

      Parameters:
      file - the file to read data from.
      charset - the character set to use.
      Returns:
      a new IndexedCsvReader - never null. Remember to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if file or charset is null

    • build

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

      Constructs a new IndexedCsvReader for the specified callback handler and path using UTF-8 as the character set.

      Convenience method for build(CsvCallbackHandler,Path,Charset) with StandardCharsets.UTF_8 as charset.

      Type Parameters:
      T - the type of the CSV record.
      Parameters:
      callbackHandler - the callback handler to use.
      file - the file to read data from.
      Returns:
      a new IndexedCsvReader - never null. Remember to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if callbackHandler, file or charset is null

    • build

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

      Constructs a new IndexedCsvReader for the specified arguments.

      Only UTF-8 and single-byte charsets are supported – whether passed explicitly or detected via a BOM header. Every configured control character must additionally map to its own single byte in both directions under that charset.

      Type Parameters:
      T - the type of the CSV record.
      Parameters:
      callbackHandler - the callback handler to use.
      file - the file to read data from.
      charset - the character set to use (UTF-8 or a single-byte charset).
      Returns:
      a new IndexedCsvReader - never null. Remember to close it!
      Throws:
      IOException - if an I/O error occurs.
      NullPointerException - if callbackHandler, file or charset is null
      IllegalArgumentException - if argument validation fails, the (supplied or BOM-detected) charset is neither UTF-8 nor single-byte, or a configured control character does not map to its own byte in it.