Package org.apache.commons.csv

Class CSVFormat.Builder

  • All Implemented Interfaces:
    java.util.function.Supplier<CSVFormat>
    Enclosing class:
    CSVFormat
    public static class CSVFormat.Builder
extends java.lang.Object
implements java.util.function.Supplier<CSVFormat>
    Builds CSVFormat instances.
    Since:
    1.9.0

    • Field Detail

      • allowMissingColumnNames

        private boolean allowMissingColumnNames

      • autoFlush

        private boolean autoFlush

      • commentMarker

        private java.lang.Character commentMarker

      • delimiter

        private java.lang.String delimiter

      • escapeCharacter

        private java.lang.Character escapeCharacter

      • headerComments

        private java.lang.String[] headerComments

      • headers

        private java.lang.String[] headers

      • ignoreEmptyLines

        private boolean ignoreEmptyLines

      • ignoreHeaderCase

        private boolean ignoreHeaderCase

      • ignoreSurroundingSpaces

        private boolean ignoreSurroundingSpaces

      • nullString

        private java.lang.String nullString

      • quoteCharacter

        private java.lang.Character quoteCharacter

      • quotedNullString

        private java.lang.String quotedNullString

      • recordSeparator

        private java.lang.String recordSeparator

      • skipHeaderRecord

        private boolean skipHeaderRecord

      • lenientEof

        private boolean lenientEof

      • trailingData

        private boolean trailingData

      • trailingDelimiter

        private boolean trailingDelimiter

      • trim

        private boolean trim

      • maxRows

        private long maxRows
        The maximum number of rows to process, excluding the header row.

    • Constructor Detail

      • Builder

        private Builder()

      • Builder

        private Builder​(CSVFormat csvFormat)

    • Method Detail

      • create

        public static CSVFormat.Builder create​(CSVFormat csvFormat)
        Creates a new builder from the given format.
        Parameters:
        csvFormat - the source format.
        Returns:
        a new builder.

      • build

        @Deprecated
public CSVFormat build()
        Deprecated.
        Use get().
        Builds a new CSVFormat instance.
        Returns:
        a new CSVFormat instance.

      • get

        public CSVFormat get()
        Builds a new CSVFormat instance.
        Specified by:
        get in interface java.util.function.Supplier<CSVFormat>
        Returns:
        a new CSVFormat instance.
        Since:
        1.13.0

      • setAllowDuplicateHeaderNames

        @Deprecated
public CSVFormat.Builder setAllowDuplicateHeaderNames​(boolean allowDuplicateHeaderNames)
        Deprecated.
        Use setDuplicateHeaderMode(DuplicateHeaderMode).
        Sets the duplicate header names behavior, true to allow, false to disallow.
        Parameters:
        allowDuplicateHeaderNames - the duplicate header names behavior, true to allow, false to disallow.
        Returns:
        This instance.

      • setAllowMissingColumnNames

        public CSVFormat.Builder setAllowMissingColumnNames​(boolean allowMissingColumnNames)
        Sets the parser missing column names behavior, true to allow missing column names in the header line, false to cause an IllegalArgumentException to be thrown.
        Parameters:
        allowMissingColumnNames - the missing column names behavior, true to allow missing column names in the header line, false to cause an IllegalArgumentException to be thrown.
        Returns:
        This instance.

      • setAutoFlush

        public CSVFormat.Builder setAutoFlush​(boolean autoFlush)
        Sets whether to flush on close.
        Parameters:
        autoFlush - whether to flush on close.
        Returns:
        This instance.

      • setCommentMarker

        public CSVFormat.Builder setCommentMarker​(char commentMarker)
        Sets the comment marker character, use null to disable comments.

        The comment start character is only recognized at the start of a line.

        Comments are printed first, before headers.

        Use setCommentMarker(char) or setCommentMarker(Character) to set the comment marker written at the start of each comment line.

        If the comment marker is not set, then the header comments are ignored.

        For example: 

         builder.setCommentMarker('#').setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));

        writes: 

         # Generated by Apache Commons CSV.
 # 1970-01-01T00:00:00Z
        Parameters:
        commentMarker - the comment start marker, use null to disable.
        Returns:
        This instance.
        Throws:
        java.lang.IllegalArgumentException - thrown if the specified character is a line break

      • setCommentMarker

        public CSVFormat.Builder setCommentMarker​(java.lang.Character commentMarker)
        Sets the comment marker character, use null to disable comments.

        The comment start character is only recognized at the start of a line.

        Comments are printed first, before headers.

        Use setCommentMarker(char) or setCommentMarker(Character) to set the comment marker written at the start of each comment line.

        If the comment marker is not set, then the header comments are ignored.

        For example: 

         builder.setCommentMarker('#').setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));

        writes: 

         # Generated by Apache Commons CSV.
 # 1970-01-01T00:00:00Z
        Parameters:
        commentMarker - the comment start marker, use null to disable.
        Returns:
        This instance.
        Throws:
        java.lang.IllegalArgumentException - thrown if the specified character is a line break

      • setDelimiter

        public CSVFormat.Builder setDelimiter​(char delimiter)
        Sets the delimiter character.
        Parameters:
        delimiter - the delimiter character.
        Returns:
        This instance.

      • setDelimiter

        public CSVFormat.Builder setDelimiter​(java.lang.String delimiter)
        Sets the delimiter character.
        Parameters:
        delimiter - the delimiter character.
        Returns:
        This instance.

      • setDuplicateHeaderMode

        public CSVFormat.Builder setDuplicateHeaderMode​(DuplicateHeaderMode duplicateHeaderMode)
        Sets the duplicate header names behavior.
        Parameters:
        duplicateHeaderMode - the duplicate header names behavior
        Returns:
        This instance.
        Since:
        1.10.0

      • setEscape

        public CSVFormat.Builder setEscape​(char escapeCharacter)
        Sets the escape character.
        Parameters:
        escapeCharacter - the escape character.
        Returns:
        This instance.
        Throws:
        java.lang.IllegalArgumentException - thrown if the specified character is a line break

      • setEscape

        public CSVFormat.Builder setEscape​(java.lang.Character escapeCharacter)
        Sets the escape character.
        Parameters:
        escapeCharacter - the escape character.
        Returns:
        This instance.
        Throws:
        java.lang.IllegalArgumentException - thrown if the specified character is a line break

      • setHeader

        public CSVFormat.Builder setHeader​(java.lang.Class<? extends java.lang.Enum<?>> headerEnum)
        Sets the header defined by the given Enum class.

        Example: 

         public enum HeaderEnum {
     Name, Email, Phone
 }

 Builder builder = builder.setHeader(HeaderEnum.class);

        The header is also used by the CSVPrinter.

        Parameters:
        headerEnum - the enum defining the header, null if disabled, empty if parsed automatically, user-specified otherwise.
        Returns:
        This instance.

      • setHeader

        public CSVFormat.Builder setHeader​(java.sql.ResultSet resultSet)
                            throws java.sql.SQLException
        Sets the header from the result set metadata. The header can be parsed automatically from the input file with: 
         builder.setHeader();
        or specified manually with: 
         builder.setHeader(resultSet);

        The header is also used by the CSVPrinter.

        Parameters:
        resultSet - the resultSet for the header, null if disabled, empty if parsed automatically, user-specified otherwise.
        Returns:
        This instance.
        Throws:
        java.sql.SQLException - SQLException if a database access error occurs or this method is called on a closed result set.

      • setHeader

        public CSVFormat.Builder setHeader​(java.sql.ResultSetMetaData resultSetMetaData)
                            throws java.sql.SQLException
        Sets the header from the result set metadata. The header can be parsed automatically from the input file with: 
         builder.setHeader();
        or specified manually with: 
         builder.setHeader(resultSetMetaData);

        The header is also used by the CSVPrinter.

        Parameters:
        resultSetMetaData - the metaData for the header, null if disabled, empty if parsed automatically, user-specified otherwise.
        Returns:
        This instance.
        Throws:
        java.sql.SQLException - SQLException if a database access error occurs or this method is called on a closed result set.

      • setHeader

        public CSVFormat.Builder setHeader​(java.lang.String... header)
        Sets the header to the given values. The header can be parsed automatically from the input file with: 
         builder.setHeader();
        or specified manually with: 
        
 builder.setHeader("name", "email", "phone");

        The header is also used by the CSVPrinter.

        This method keeps a copy of the input array.

        Parameters:
        header - the header, null if disabled, empty if parsed automatically, user-specified otherwise.
        Returns:
        This instance.

      • setHeaderComments

        public CSVFormat.Builder setHeaderComments​(java.lang.Object... headerComments)
        Sets the header comments to write before the CSV data.

        This setting is ignored by the parser.

        Comments are printed first, before headers.

        Use setCommentMarker(char) or setCommentMarker(Character) to set the comment marker written at the start of each comment line.

        If the comment marker is not set, then the header comments are ignored.

        For example: 

         builder.setCommentMarker('#').setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));

        writes: 

         # Generated by Apache Commons CSV.
 # 1970-01-01T00:00:00Z

        This method keeps a copy of the input array.

        Parameters:
        headerComments - the headerComments which will be printed by the Printer before the CSV data.
        Returns:
        This instance.

      • setHeaderComments

        public CSVFormat.Builder setHeaderComments​(java.lang.String... headerComments)
        Sets the header comments to write before the CSV data.

        This setting is ignored by the parser.

        Comments are printed first, before headers.

        Use setCommentMarker(char) or setCommentMarker(Character) to set the comment marker written at the start of each comment line.

        If the comment marker is not set, then the header comments are ignored.

        For example: 

         builder.setCommentMarker('#').setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0).toString());

        writes: 

         # Generated by Apache Commons CSV.
 # 1970-01-01T00:00:00Z

        This method keeps a copy of the input array.

        Parameters:
        headerComments - the headerComments which will be printed by the Printer before the CSV data.
        Returns:
        This instance.

      • setIgnoreEmptyLines

        public CSVFormat.Builder setIgnoreEmptyLines​(boolean ignoreEmptyLines)
        Sets the empty line skipping behavior, true to ignore the empty lines between the records, false to translate empty lines to empty records.
        Parameters:
        ignoreEmptyLines - the empty line skipping behavior, true to ignore the empty lines between the records, false to translate empty lines to empty records.
        Returns:
        This instance.

      • setIgnoreHeaderCase

        public CSVFormat.Builder setIgnoreHeaderCase​(boolean ignoreHeaderCase)
        Sets the parser case mapping behavior, true to access name/values, false to leave the mapping as is.
        Parameters:
        ignoreHeaderCase - the case mapping behavior, true to access name/values, false to leave the mapping as is.
        Returns:
        This instance.

      • setIgnoreSurroundingSpaces

        public CSVFormat.Builder setIgnoreSurroundingSpaces​(boolean ignoreSurroundingSpaces)
        Sets the parser trimming behavior, true to remove the surrounding spaces, false to leave the spaces as is.
        Parameters:
        ignoreSurroundingSpaces - the parser trimming behavior, true to remove the surrounding spaces, false to leave the spaces as is.
        Returns:
        This instance.

      • setLenientEof

        public CSVFormat.Builder setLenientEof​(boolean lenientEof)
        Sets whether reading end-of-file is allowed even when input is malformed, helps Excel compatibility.
        Parameters:
        lenientEof - whether reading end-of-file is allowed even when input is malformed, helps Excel compatibility.
        Returns:
        This instance.
        Since:
        1.11.0

      • setMaxRows

        public CSVFormat.Builder setMaxRows​(long maxRows)
        Sets the maximum number of rows to process, excluding the header row.

        Values less than or equal to 0 mean no limit.

        Parameters:
        maxRows - the maximum number of rows to process, excluding the header row.
        Returns:
        This instance.
        Since:
        1.14.0

      • setNullString

        public CSVFormat.Builder setNullString​(java.lang.String nullString)
        Sets the String to convert to and from null. No substitution occurs if null.
        • Reading: Converts strings equal to the given nullString to null when reading records.
        • Writing: Writes null as the given nullString when writing records.
        Parameters:
        nullString - the String to convert to and from null. No substitution occurs if null.
        Returns:
        This instance.

      • setQuote

        public CSVFormat.Builder setQuote​(char quoteCharacter)
        Sets the quote character.
        Parameters:
        quoteCharacter - the quote character.
        Returns:
        This instance.

      • setQuote

        public CSVFormat.Builder setQuote​(java.lang.Character quoteCharacter)
        Sets the quote character, use null to disable.
        Parameters:
        quoteCharacter - the quote character, use null to disable.
        Returns:
        This instance.

      • setQuoteMode

        public CSVFormat.Builder setQuoteMode​(QuoteMode quoteMode)
        Sets the quote policy to use for output.
        Parameters:
        quoteMode - the quote policy to use for output.
        Returns:
        This instance.

      • setRecordSeparator

        public CSVFormat.Builder setRecordSeparator​(char recordSeparator)
        Sets the record separator to use for output.

        Note: This setting is only used during printing and does not affect parsing. Parsing currently only works for inputs with '\n', '\r' and "\r\n"

        Parameters:
        recordSeparator - the record separator to use for output.
        Returns:
        This instance.

      • setRecordSeparator

        public CSVFormat.Builder setRecordSeparator​(java.lang.String recordSeparator)
        Sets the record separator to use for output.

        Note: This setting is only used during printing and does not affect parsing. Parsing currently only works for inputs with '\n', '\r' and "\r\n"

        Parameters:
        recordSeparator - the record separator to use for output.
        Returns:
        This instance.

      • setSkipHeaderRecord

        public CSVFormat.Builder setSkipHeaderRecord​(boolean skipHeaderRecord)
        Sets whether to skip the header record.
        Parameters:
        skipHeaderRecord - whether to skip the header record.
        Returns:
        This instance.

      • setTrailingData

        public CSVFormat.Builder setTrailingData​(boolean trailingData)
        Sets whether reading trailing data is allowed in records, helps Excel compatibility.
        Parameters:
        trailingData - whether reading trailing data is allowed in records, helps Excel compatibility.
        Returns:
        This instance.
        Since:
        1.11.0

      • setTrailingDelimiter

        public CSVFormat.Builder setTrailingDelimiter​(boolean trailingDelimiter)
        Sets whether to add a trailing delimiter.
        Parameters:
        trailingDelimiter - whether to add a trailing delimiter.
        Returns:
        This instance.

      • setTrim

        public CSVFormat.Builder setTrim​(boolean trim)
        Sets whether to trim leading and trailing blanks.
        Parameters:
        trim - whether to trim leading and trailing blanks.
        Returns:
        This instance.