Class CsvReader.CsvReaderBuilder

  • Enclosing class:
    CsvReader<T>

    public static final class CsvReader.CsvReaderBuilder
    extends java.lang.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 Detail

      • fieldSeparator

        private char fieldSeparator
      • quoteCharacter

        private char quoteCharacter
      • commentCharacter

        private char commentCharacter
      • skipEmptyLines

        private boolean skipEmptyLines
      • ignoreDifferentFieldCount

        private boolean ignoreDifferentFieldCount
      • acceptCharsAfterQuotes

        private boolean acceptCharsAfterQuotes
      • detectBomHeader

        private boolean detectBomHeader
    • Constructor Detail

      • CsvReaderBuilder

        private CsvReaderBuilder()
    • Method Detail

      • 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 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​(java.io.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:
        java.lang.NullPointerException - if reader is null
      • ofCsvRecord

        public CsvReader<CsvRecord> ofCsvRecord​(java.lang.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:
        java.lang.NullPointerException - if data is null
      • ofCsvRecord

        public CsvReader<CsvRecord> ofCsvRecord​(java.nio.file.Path file)
                                         throws java.io.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:
        java.io.IOException - if an I/O error occurs.
        java.lang.NullPointerException - if file is null
      • ofCsvRecord

        public CsvReader<CsvRecord> ofCsvRecord​(java.nio.file.Path file,
                                                java.nio.charset.Charset charset)
                                         throws java.io.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:
        java.io.IOException - if an I/O error occurs.
        java.lang.NullPointerException - if file or charset is null
      • ofNamedCsvRecord

        public CsvReader<NamedCsvRecord> ofNamedCsvRecord​(java.nio.file.Path file)
                                                   throws java.io.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:
        java.io.IOException - if an I/O error occurs.
        java.lang.NullPointerException - if file is null
      • ofNamedCsvRecord

        public CsvReader<NamedCsvRecord> ofNamedCsvRecord​(java.nio.file.Path file,
                                                          java.nio.charset.Charset charset)
                                                   throws java.io.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:
        java.io.IOException - if an I/O error occurs.
        java.lang.NullPointerException - if file or charset is null
      • build

        public <T> CsvReader<T> build​(CsvCallbackHandler<T> callbackHandler,
                                      java.io.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:
        java.lang.NullPointerException - if callbackHandler or reader is null
      • build

        public <T> CsvReader<T> build​(CsvCallbackHandler<T> callbackHandler,
                                      java.lang.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:
        java.lang.NullPointerException - if callbackHandler or data is null
      • build

        public <T> CsvReader<T> build​(CsvCallbackHandler<T> callbackHandler,
                                      java.nio.file.Path file)
                               throws java.io.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:
        java.io.IOException - if an I/O error occurs.
        java.lang.NullPointerException - if callbackHandler or file is null
      • build

        public <T> CsvReader<T> build​(CsvCallbackHandler<T> callbackHandler,
                                      java.nio.file.Path file,
                                      java.nio.charset.Charset charset)
                               throws java.io.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:
        java.io.IOException - if an I/O error occurs.
        java.lang.NullPointerException - if callbackHandler, file or charset is null
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object