Package org.apache.commons.csv

Class CSVFormat.Builder

java.lang.Object
org.apache.commons.csv.CSVFormat.Builder
Enclosing class:
CSVFormat
public static class CSVFormat.Builder extends Object
Builds CSVFormat instances.
Since:
1.9.0

  • Method Details

    • create

      public static CSVFormat.Builder create()
      Creates a new default builder.
      Returns:
      a copy of the builder

    • create

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

    • build

      public CSVFormat build()
      Builds a new CSVFormat instance.
      Returns:
      a new CSVFormat instance.

    • 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:
      IllegalArgumentException - thrown if the specified character is a line break

    • setCommentMarker

      public CSVFormat.Builder setCommentMarker(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:
      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(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:
      IllegalArgumentException - thrown if the specified character is a line break

    • setEscape

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

    • setHeader

      public CSVFormat.Builder setHeader(Class<? extends 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(ResultSet resultSet) throws 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:
      SQLException - SQLException if a database access error occurs or this method is called on a closed result set.

    • setHeader

      public CSVFormat.Builder setHeader(ResultSetMetaData resultSetMetaData) throws 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:
      SQLException - SQLException if a database access error occurs or this method is called on a closed result set.

    • setHeader

      public CSVFormat.Builder setHeader(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.

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

    • setHeaderComments

      public CSVFormat.Builder setHeaderComments(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
      Parameters:
      headerComments - the headerComments which will be printed by the Printer before the CSV data.
      Returns:
      This instance.

    • setHeaderComments

      public CSVFormat.Builder setHeaderComments(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
      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

    • setNullString

      public CSVFormat.Builder setNullString(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(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(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.