CSVFormat.Builder (Apache Commons CSV 1.14.1 API)
Description: declaration: package: org.apache.commons.csv, class: CSVFormat, class: Builder

Package org.apache.commons.csv

# Class CSVFormat.Builder

java.lang.Object
org.apache.commons.csv.CSVFormat.Builder

All Implemented Interfaces:
  `Supplier<CSVFormat>`

Enclosing class:
  `CSVFormat`

public static class CSVFormat.Builder extends Object implements Supplier<CSVFormat>
Builds CSVFormat instances.

Since:
  1.9.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CSVFormat`
  `build()`
  Deprecated.
  Use `get()`.
  `static CSVFormat.Builder`
  `create()`
  Creates a new default builder, as for `CSVFormat.RFC4180` but allowing empty lines.
  `static CSVFormat.Builder`
  `create(CSVFormat csvFormat)`
  Creates a new builder from the given format.
  `CSVFormat`
  `get()`
  Builds a new CSVFormat instance.
  `CSVFormat.Builder`
  `setAllowDuplicateHeaderNames(boolean allowDuplicateHeaderNames)`
  Deprecated.
  Use `setDuplicateHeaderMode(DuplicateHeaderMode)`.
  `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.
  `CSVFormat.Builder`
  `setAutoFlush(boolean autoFlush)`
  Sets whether to flush on close.
  `CSVFormat.Builder`
  `setCommentMarker(char commentMarker)`
  Sets the comment marker character, use `null` to disable comments.
  `CSVFormat.Builder`
  `setCommentMarker(Character commentMarker)`
  Sets the comment marker character, use `null` to disable comments.
  `CSVFormat.Builder`
  `setDelimiter(char delimiter)`
  Sets the delimiter character.
  `CSVFormat.Builder`
  `setDelimiter(String delimiter)`
  Sets the delimiter character.
  `CSVFormat.Builder`
  `setDuplicateHeaderMode(DuplicateHeaderMode duplicateHeaderMode)`
  Sets the duplicate header names behavior.
  `CSVFormat.Builder`
  `setEscape(char escapeCharacter)`
  Sets the escape character.
  `CSVFormat.Builder`
  `setEscape(Character escapeCharacter)`
  Sets the escape character.
  `CSVFormat.Builder`
  `setHeader(Class<? extends Enum<?>> headerEnum)`
  Sets the header defined by the given `Enum` class.
  `CSVFormat.Builder`
  `setHeader(String... header)`
  Sets the header to the given values.
  `CSVFormat.Builder`
  `setHeader(ResultSet resultSet)`
  Sets the header from the result set metadata.
  `CSVFormat.Builder`
  `setHeader(ResultSetMetaData resultSetMetaData)`
  Sets the header from the result set metadata.
  `CSVFormat.Builder`
  `setHeaderComments(Object... headerComments)`
  Sets the header comments to write before the CSV data.
  `CSVFormat.Builder`
  `setHeaderComments(String... headerComments)`
  Sets the header comments to write before the CSV data.
  `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.
  `CSVFormat.Builder`
  `setIgnoreHeaderCase(boolean ignoreHeaderCase)`
  Sets the parser case mapping behavior, `true` to access name/values, `false` to leave the mapping as is.
  `CSVFormat.Builder`
  `setIgnoreSurroundingSpaces(boolean ignoreSurroundingSpaces)`
  Sets the parser trimming behavior, `true` to remove the surrounding spaces, `false` to leave the spaces as is.
  `CSVFormat.Builder`
  `setLenientEof(boolean lenientEof)`
  Sets whether reading end-of-file is allowed even when input is malformed, helps Excel compatibility.
  `CSVFormat.Builder`
  `setMaxRows(long maxRows)`
  Sets the maximum number of rows to process, excluding the header row.
  `CSVFormat.Builder`
  `setNullString(String nullString)`
  Sets the String to convert to and from `null`.
  `CSVFormat.Builder`
  `setQuote(char quoteCharacter)`
  Sets the quote character.
  `CSVFormat.Builder`
  `setQuote(Character quoteCharacter)`
  Sets the quote character, use `null` to disable.
  `CSVFormat.Builder`
  `setQuoteMode(QuoteMode quoteMode)`
  Sets the quote policy to use for output.
  `CSVFormat.Builder`
  `setRecordSeparator(char recordSeparator)`
  Sets the record separator to use for output.
  `CSVFormat.Builder`
  `setRecordSeparator(String recordSeparator)`
  Sets the record separator to use for output.
  `CSVFormat.Builder`
  `setSkipHeaderRecord(boolean skipHeaderRecord)`
  Sets whether to skip the header record.
  `CSVFormat.Builder`
  `setTrailingData(boolean trailingData)`
  Sets whether reading trailing data is allowed in records, helps Excel compatibility.
  `CSVFormat.Builder`
  `setTrailingDelimiter(boolean trailingDelimiter)`
  Sets whether to add a trailing delimiter.
  `CSVFormat.Builder`
  `setTrim(boolean trim)`
  Sets whether to trim leading and trailing blanks.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### create

    public static CSVFormat.Builder create()
    Creates a new default builder, as for `CSVFormat.RFC4180` but allowing empty lines.

    The `CSVFormat.Builder` settings are:

    - `setDelimiter``(',')`
    - `setQuote``('"')`
    - `setRecordSeparator``("\r\n")`
    - `setIgnoreEmptyLines``(true)`
    - `setDuplicateHeaderMode``(DuplicateHeaderMode.ALLOW_ALL)`
    - All other values take their Java defaults, `false` for booleans, `null` for object references.
    Returns:
      a copy of the builder
    See Also:
      - `CSVFormat.Predefined.Default`
      - `DuplicateHeaderMode.ALLOW_ALL`

  - ### 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 `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:
      `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`.

    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(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(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(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.