Module tools.jackson.dataformat.csv
Package tools.jackson.dataformat.csv

Enum Class CsvReadFeature

java.lang.Object
java.lang.Enum<CsvReadFeature>
tools.jackson.dataformat.csv.CsvReadFeature
All Implemented Interfaces:
Serializable, Comparable<CsvReadFeature>, Constable, tools.jackson.core.FormatFeature, tools.jackson.core.util.JacksonFeature
public enum CsvReadFeature extends Enum<CsvReadFeature> implements tools.jackson.core.FormatFeature
Enumeration that defines all togglable features for CSV parsers

NOTE: in Jackson 2.x this was named CsvParser.Feature.

  • Nested Class Summary

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    ALLOW_COMMENTS
    Feature that allows accepting "hash comments" by default, similar to CsvSchema.withAllowComments(boolean).
    ALLOW_TRAILING_COMMA
    Feature that allows there to be a trailing single extraneous data column that is empty.
    CASE_INSENSITIVE_HEADERS
    Feature that enables case-insensitive matching of header column names against schema column names.
    EMPTY_STRING_AS_NULL
    Feature that enables coercing an empty String (quoted or unquoted) to null.
    EMPTY_UNQUOTED_STRING_AS_MISSING
    Feature that enables treating empty unquoted cell values as "missing", effectively suppressing the token pair (property name + value) for such cells.
    EMPTY_UNQUOTED_STRING_AS_NULL
    Feature that enables coercing an empty un-quoted String to null.
    FAIL_ON_DUPLICATE_HEADER_COLUMNS
    Feature that enables failing (with a CsvReadException) when duplicate column names are encountered in the header line.
    FAIL_ON_MISSING_COLUMNS
    Feature that allows failing (with a CsvReadException) in cases where number of column values encountered is less than number of columns declared in the active schema ("missing columns").
    FAIL_ON_MISSING_HEADER_COLUMNS
    Feature that allows failing (with a CsvReadException) in cases where number of header columns encountered is less than number of columns declared in the active schema (if there is one).
    IGNORE_TRAILING_UNMAPPABLE
    Feature that allows ignoring of unmappable "extra" columns; that is, values for columns that appear after columns for which types are defined.
    INSERT_NULLS_FOR_MISSING_COLUMNS
    Feature that allows "inserting" virtual key / `null` value pairs in case a row contains fewer columns than declared by configured schema.
    ONLY_UNQUOTED_NULL_VALUES_AS_NULL
    Feature that enables treating only un-quoted values matching the configured "null value" String (see CsvSchema.getNullValueString()) as null, but not quoted values: differentiating between a quoted null value String (like "null") which remains as a String, and an unquoted null value (like null) which becomes null.
    SKIP_EMPTY_LINES
    Feature that allows skipping input lines that are completely empty or blank (composed only of whitespace), instead of being decoded as lines of just a single column with an empty/blank String value (or, depending on binding, `null`).
    SKIP_EMPTY_ROWS
    Feature that allows skipping input rows that consist solely of column separator characters (for example, a line containing only ,, with the default comma separator).
    TRIM_HEADER_SPACES
    Feature determines whether spaces around separator characters (commas) in header line entries (header names) are to be automatically trimmed before being reported or not.
    TRIM_SPACES
    Feature determines whether spaces around separator characters (commas) are to be automatically trimmed before being reported or not.
    WRAP_AS_ARRAY
    Feature that determines how stream of records (usually CSV lines, but sometimes multiple lines when line-feeds are included in quoted values) is exposed: either as a sequence of Objects (false), or as an Array of Objects (true).

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    collectDefaults()
    Method that calculates bit set (flags) of all features that are enabled by default.
    boolean
    enabledByDefault()
     
    boolean
    enabledIn(int flags)
     
    int
    getMask()
     
    static CsvReadFeature
    valueOf(String name)
    Returns the enum constant of this class with the specified name.
    static CsvReadFeature[]
    values()
    Returns an array containing the constants of this enum class, in the order they are declared.

    Methods inherited from class java.lang.Enum

    clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • TRIM_SPACES

      public static final CsvReadFeature TRIM_SPACES
      Feature determines whether spaces around separator characters (commas) are to be automatically trimmed before being reported or not. Note that this does NOT force trimming of possible white space from within double-quoted values, but only those surrounding unquoted values (white space outside of double-quotes is never included regardless of trimming).

      Default value is false, as per RFC-4180.

    • TRIM_HEADER_SPACES

      public static final CsvReadFeature TRIM_HEADER_SPACES
      Feature determines whether spaces around separator characters (commas) in header line entries (header names) are to be automatically trimmed before being reported or not. Note that this does NOT force trimming of possible white space from within double-quoted values, but only those surrounding unquoted values (white space outside of double-quotes is never included regardless of trimming).

      Default value is true.

    • WRAP_AS_ARRAY

      public static final CsvReadFeature WRAP_AS_ARRAY
      Feature that determines how stream of records (usually CSV lines, but sometimes multiple lines when line-feeds are included in quoted values) is exposed: either as a sequence of Objects (false), or as an Array of Objects (true). Using stream of Objects is convenient when using ObjectMapper.readValues(...) and array of Objects convenient when binding to Lists or arrays of values.

      Default value is false, meaning that by default a CSV document is exposed as a sequence of root-level Object entries.

    • IGNORE_TRAILING_UNMAPPABLE

      public static final CsvReadFeature IGNORE_TRAILING_UNMAPPABLE
      Feature that allows ignoring of unmappable "extra" columns; that is, values for columns that appear after columns for which types are defined. When disabled, an exception is thrown for such column values, but if enabled, they are silently ignored.

      Feature is disabled by default.

    • SKIP_EMPTY_LINES

      public static final CsvReadFeature SKIP_EMPTY_LINES
      Feature that allows skipping input lines that are completely empty or blank (composed only of whitespace), instead of being decoded as lines of just a single column with an empty/blank String value (or, depending on binding, `null`).

      Feature is disabled by default.

    • ALLOW_TRAILING_COMMA

      public static final CsvReadFeature ALLOW_TRAILING_COMMA
      Feature that allows there to be a trailing single extraneous data column that is empty. When this feature is disabled, any extraneous column, regardless of content will cause an exception to be thrown. Disabling this feature is only useful when IGNORE_TRAILING_UNMAPPABLE is also disabled.

    • ALLOW_COMMENTS

      public static final CsvReadFeature ALLOW_COMMENTS
      Feature that allows accepting "hash comments" by default, similar to CsvSchema.withAllowComments(boolean). If enabled, such comments are by default allowed on all columns of all documents.

    • FAIL_ON_MISSING_COLUMNS

      public static final CsvReadFeature FAIL_ON_MISSING_COLUMNS
      Feature that allows failing (with a CsvReadException) in cases where number of column values encountered is less than number of columns declared in the active schema ("missing columns").

      Note that this feature has precedence over INSERT_NULLS_FOR_MISSING_COLUMNS

      Feature is disabled by default.

    • FAIL_ON_MISSING_HEADER_COLUMNS

      public static final CsvReadFeature FAIL_ON_MISSING_HEADER_COLUMNS
      Feature that allows failing (with a CsvReadException) in cases where number of header columns encountered is less than number of columns declared in the active schema (if there is one).

      Feature is enabled by default.

    • INSERT_NULLS_FOR_MISSING_COLUMNS

      public static final CsvReadFeature INSERT_NULLS_FOR_MISSING_COLUMNS
      Feature that allows "inserting" virtual key / `null` value pairs in case a row contains fewer columns than declared by configured schema. This typically has the effect of forcing an explicit `null` assigment (or corresponding "null value", if so configured) at databinding level. If disabled, no extra work is done and values for "missing" columns are not exposed as part of the token stream.

      Note that this feature is only considered if FAIL_ON_MISSING_COLUMNS is disabled.

      Feature is disabled by default.

    • EMPTY_STRING_AS_NULL

      public static final CsvReadFeature EMPTY_STRING_AS_NULL
      Feature that enables coercing an empty String (quoted or unquoted) to null.

      Note that if this setting is enabled, EMPTY_UNQUOTED_STRING_AS_NULL has no effect. Feature is disabled by default for backwards compatibility.

    • EMPTY_UNQUOTED_STRING_AS_NULL

      public static final CsvReadFeature EMPTY_UNQUOTED_STRING_AS_NULL
      Feature that enables coercing an empty un-quoted String to null. This feature allow differentiating between an empty quoted String and an empty un-quoted String.

      Note that this feature is only considered if EMPTY_STRING_AS_NULL is disabled.

      Feature is disabled by default for backwards compatibility.

    • EMPTY_UNQUOTED_STRING_AS_MISSING

      public static final CsvReadFeature EMPTY_UNQUOTED_STRING_AS_MISSING
      Feature that enables treating empty unquoted cell values as "missing", effectively suppressing the token pair (property name + value) for such cells. This means that if the target POJO field has a default value, it will be preserved instead of being overwritten with an empty String.

      This is different from EMPTY_STRING_AS_NULL which coerces the value to null: this feature causes the value to not be included in the token stream at all, similar to how truly missing columns (row shorter than schema) are handled.

      Only applies to unquoted empty values; a quoted empty string ("") is still reported normally.

      Feature is disabled by default for backwards compatibility.

      Since:
      3.2

    • ONLY_UNQUOTED_NULL_VALUES_AS_NULL

      public static final CsvReadFeature ONLY_UNQUOTED_NULL_VALUES_AS_NULL
      Feature that enables treating only un-quoted values matching the configured "null value" String (see CsvSchema.getNullValueString()) as null, but not quoted values: differentiating between a quoted null value String (like "null") which remains as a String, and an unquoted null value (like null) which becomes null.

      This is similar to EMPTY_UNQUOTED_STRING_AS_NULL but applies to the explicitly configured null value rather than empty strings.

      Note: This feature only has an effect if a null value is configured via CsvSchema.Builder.setNullValue(String).

      Feature is disabled by default for backwards compatibility.

      Since:
      3.1

    • SKIP_EMPTY_ROWS

      public static final CsvReadFeature SKIP_EMPTY_ROWS
      Feature that allows skipping input rows that consist solely of column separator characters (for example, a line containing only ,, with the default comma separator). This is different from SKIP_EMPTY_LINES which only skips lines that are completely empty or blank (whitespace only): this feature skips lines that contain only consecutive separator characters followed by a linefeed.

      Feature is disabled by default.

      Since:
      3.2

    • FAIL_ON_DUPLICATE_HEADER_COLUMNS

      public static final CsvReadFeature FAIL_ON_DUPLICATE_HEADER_COLUMNS
      Feature that enables failing (with a CsvReadException) when duplicate column names are encountered in the header line.

      When enabled, parsing will fail if the header line contains two or more columns with the same name. When disabled, duplicates are allowed and the last column with a given name will be the one accessible by name (earlier columns with the same name are effectively hidden).

      Feature is enabled by default.

      Since:
      3.2

    • CASE_INSENSITIVE_HEADERS

      public static final CsvReadFeature CASE_INSENSITIVE_HEADERS
      Feature that enables case-insensitive matching of header column names against schema column names. When enabled, a CSV header column named "TEMP_MAX" will match a schema column named "temp_max" (and vice versa).

      This is useful when used together with MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES to allow case-insensitive header matching at the parser level, preventing FAIL_ON_MISSING_HEADER_COLUMNS from incorrectly reporting columns as missing when they differ only by case.

      Feature is disabled by default.

      Since:
      3.2

  • Method Details

    • values

      public static CsvReadFeature[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static CsvReadFeature valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • collectDefaults

      public static int collectDefaults()
      Method that calculates bit set (flags) of all features that are enabled by default.

    • enabledByDefault

      public boolean enabledByDefault()
      Specified by:
      enabledByDefault in interface tools.jackson.core.util.JacksonFeature

    • enabledIn

      public boolean enabledIn(int flags)
      Specified by:
      enabledIn in interface tools.jackson.core.util.JacksonFeature

    • getMask

      public int getMask()
      Specified by:
      getMask in interface tools.jackson.core.util.JacksonFeature