public class CsvSchema extends Object implements com.fasterxml.jackson.core.FormatSchema, Iterable<CsvSchema.Column>, Serializable
FormatSchema
sub-type that defines properties of
a CSV document to read or write.
Properties supported currently are:
columns
(List of ColumnDef) [default: empty List]: Ordered list of columns (which may be empty, see below).
Each column has name (mandatory) as well as type (optional; if not
defined, defaults to "String").
Note that
useHeader
(boolean) [default: false]: whether the first line of physical document defines
column names (true) or not (false): if enabled, parser will take
first-line values to define column names; and generator will output
column names as the first line
quoteChar
(char) [default: double-quote ('")]: character used for quoting values
that contain quote characters or linefeeds.
columnSeparator
(char) [default: comma (',')]: character used to separate values.
Other commonly used values include tab ('\t') and pipe ('|')
arrayElementSeparator
(String) [default: semicolon (";")]: string used to separate array elements.
lineSeparator
(String) [default: "\n"]: character used to separate data rows.
Only used by generator; parser accepts three standard linefeeds ("\r", "\r\n", "\n").
escapeChar
(int) [default: -1 meaning "none"]: character, if any, used to
escape values. Most commonly defined as backslash ('\'). Only used by parser;
generator only uses quoting, including doubling up of quotes to indicate quote char
itself.
skipFirstDataRow
(boolean) [default: false]: whether the first data line (either
first line of the document, if useHeader=false, or second, if useHeader=true)
should be completely ignored by parser. Needed to support CSV-like file formats
that include additional non-data content before real data begins (specifically
some database dumps do this)
nullValue
(String) [default: "" (empty String)]: When asked to write Java `null`,
this String value will be used instead.strictHeaders
(boolean) [default: false] (added in Jackson 2.7): whether names of
columns defined in the schema MUST match with actual declaration from
the header row (if header row handling enabled): if true, they must be and
an exception if thrown if order differs: if false, no verification is performed.
allowComments
(boolean) [default: false]: whether lines that start with character "#"
are processed as comment lines and skipped/ignored.
anyProperty
(String] [default: none]: if "any properties" (properties for
'extra' columns; ones not specified in schema) are enabled, they are mapped to
this name: leaving it as null
disables use of
"any properties" (and they are either ignored, or an exception
is thrown, depending on other settings); setting it to a non-null
String value will expose all extra properties under one specified name.
Most often used with Jackson @JsonAnySetter
annotation.
Note that schemas without any columns are legal, but if no columns are added, behavior of parser/generator is usually different and content will be exposed as logical Arrays instead of Objects.
There are 4 ways to create CsvSchema
instances:
CsvSchema.Builder
withXxx
methods
or rebuild()
for creating CsvSchema.Builder
)
CsvMapper
methods like CsvMapper.schemaFor(java.lang.Class)
.
CsvParser
reads schema from the first line:
enable "useHeader" property for the initial schema, and let parser
read column names from the document itself.
Modifier and Type | Class and Description |
---|---|
static class |
CsvSchema.Builder
Class used for building
CsvSchema instances. |
static class |
CsvSchema.Column
Representation of info for a single column
|
static class |
CsvSchema.ColumnType
Enumeration that defines optional type indicators that can be passed
with schema.
|
Modifier and Type | Field and Description |
---|---|
protected String |
_anyPropertyName
If "any properties" (properties for 'extra' columns; ones
not specified in schema) are enabled, they are mapped to
this name: leaving it as
null disables use of
"any properties" (and they are either ignored, or an exception
is thrown, depending on other settings); setting it to a non-null
String value will expose all extra properties under one specified
name. |
protected String |
_arrayElementSeparator |
protected CsvSchema.Column[] |
_columns
Column definitions, needed for optional header and/or mapping
of field names to column positions.
|
protected Map<String,CsvSchema.Column> |
_columnsByName |
protected char |
_columnSeparator |
protected int |
_escapeChar |
protected int |
_features
Bitflag for general-purpose on/off features.
|
protected char[] |
_lineSeparator |
protected char[] |
_nullValue |
protected String |
_nullValueAsString |
protected int |
_quoteChar |
static String |
DEFAULT_ANY_PROPERTY_NAME
By default no "any properties" (properties for 'extra' columns; ones
not specified in schema) are used, so
null is used as marker. |
static String |
DEFAULT_ARRAY_ELEMENT_SEPARATOR
Default separator for array elements within a column value is
semicolon.
|
static char |
DEFAULT_COLUMN_SEPARATOR
Default separator for column values is comma (hence "Comma-Separated Values")
|
protected static int |
DEFAULT_ENCODING_FEATURES |
static int |
DEFAULT_ESCAPE_CHAR
By default, no escape character is used -- this is denoted by
int value that does not map to a valid character
|
static char[] |
DEFAULT_LINEFEED |
static char[] |
DEFAULT_NULL_VALUE
By default, nulls are written as empty Strings (""); and no coercion
is performed from any String (higher level databind may, however,
coerce Strings into Java nulls).
|
static char |
DEFAULT_QUOTE_CHAR |
protected static int |
ENCODING_FEATURE_ALLOW_COMMENTS |
protected static int |
ENCODING_FEATURE_REORDER_COLUMNS |
protected static int |
ENCODING_FEATURE_SKIP_FIRST_DATA_ROW |
protected static int |
ENCODING_FEATURE_STRICT_HEADERS |
protected static int |
ENCODING_FEATURE_USE_HEADER |
static String |
NO_ARRAY_ELEMENT_SEPARATOR
Marker for the case where no array element separator is used
|
protected static char[] |
NO_CHARS |
protected static CsvSchema.Column[] |
NO_COLUMNS |
Modifier | Constructor and Description |
---|---|
|
CsvSchema(CsvSchema.Column[] columns,
int features,
char columnSeparator,
int quoteChar,
int escapeChar,
char[] lineSeparator,
int arrayElementSeparator,
char[] nullValue)
Deprecated.
|
protected |
CsvSchema(CsvSchema.Column[] columns,
int features,
char columnSeparator,
int quoteChar,
int escapeChar,
char[] lineSeparator,
String arrayElementSeparator,
char[] nullValue,
Map<String,CsvSchema.Column> columnsByName,
String anyPropertyName)
Copy constructor used for creating variants using
withXxx() methods. |
|
CsvSchema(CsvSchema.Column[] columns,
int features,
char columnSeparator,
int quoteChar,
int escapeChar,
char[] lineSeparator,
String arrayElementSeparator,
char[] nullValue,
String anyPropertyName) |
protected |
CsvSchema(CsvSchema base,
CsvSchema.Column[] columns)
Copy constructor used for creating variants using
sortedBy() methods. |
protected |
CsvSchema(CsvSchema base,
int features)
Copy constructor used for creating variants for on/off features
|
Modifier and Type | Method and Description |
---|---|
protected static String |
_validArrayElementSeparator(String sep) |
protected CsvSchema |
_withFeature(int feature,
boolean state) |
boolean |
allowsComments() |
static CsvSchema.Builder |
builder() |
CsvSchema.Column |
column(int index)
Accessor for column at specified index (0-based); index having to be within
|
CsvSchema.Column |
column(String name) |
CsvSchema.Column |
column(String name,
int probableIndex)
Optimized variant where a hint is given as to likely index of the column
name.
|
String |
columnName(int index) |
static CsvSchema |
emptySchema()
Accessor for creating a "default" CSV schema instance, with following
settings:
Does NOT use header line
Uses double quotes ('"') for quoting of field values (if necessary)
Uses comma (',') as the field separator
Uses Unix linefeed ('\n') as row separator
Does NOT use any escape characters
Does NOT have any columns defined
|
String |
getAnyPropertyName() |
String |
getArrayElementSeparator() |
String |
getColumnDesc()
Method for getting description of column definitions in
developer-readable form
|
List<String> |
getColumnNames()
Accessor for getting names of included columns, in the order they are
included in the schema.
|
Collection<String> |
getColumnNames(Collection<String> names)
Accessor for getting names of included columns, added in given
Collection . |
char |
getColumnSeparator() |
int |
getEscapeChar() |
char[] |
getLineSeparator() |
char[] |
getNullValue() |
char[] |
getNullValueOrEmpty()
Same as
getNullValue() except that undefined null value (one that remains as null ,
or explicitly set as such) will be returned as empty char[] |
String |
getNullValueString() |
int |
getQuoteChar() |
String |
getSchemaType() |
boolean |
hasArrayElementSeparator() |
Iterator<CsvSchema.Column> |
iterator() |
CsvSchema.Builder |
rebuild()
Helper method for constructing Builder that can be used to create modified
schema.
|
boolean |
reordersColumns() |
int |
size()
Accessor for finding out how many columns this schema defines.
|
boolean |
skipFirstDataRow()
Deprecated.
Use
skipsFirstDataRow() instead |
boolean |
skipsFirstDataRow() |
CsvSchema |
sortedBy(Comparator<String> cmp)
Mutant factory method that will construct a new instance in which columns
are sorted using given
Comparator over column names. |
CsvSchema |
sortedBy(String... columnNames)
Mutant factory method that will construct a new instance in which columns
are sorted based on names given as argument.
|
boolean |
strictHeaders() |
String |
toString() |
boolean |
useHeader()
Deprecated.
Use
usesHeader() instead |
boolean |
usesEscapeChar() |
boolean |
usesHeader() |
boolean |
usesQuoteChar() |
CsvSchema |
withAllowComments(boolean state)
Method to indicate whether "hash comments" are allowed
for document described by this schema.
|
CsvSchema |
withAnyPropertyName(String name) |
CsvSchema |
withArrayElementSeparator(char c)
Deprecated.
use
withArrayElementSeparator(String) instead |
CsvSchema |
withArrayElementSeparator(String separator) |
CsvSchema |
withColumnReordering(boolean state)
Returns a clone of this instance by changing or setting the
column reordering flag
|
CsvSchema |
withColumnSeparator(char sep) |
CsvSchema |
withColumnsFrom(CsvSchema toAppend)
Mutant factory method that will try to combine columns of this schema with those
from `toAppend`, starting with columns of this instance, and ignoring
duplicates (if any) from argument `toAppend`.
|
CsvSchema |
withComments()
Method to indicate that "hash comments" ARE allowed
for document described by this schema.
|
CsvSchema |
withEscapeChar(char c) |
CsvSchema |
withHeader()
Helper method for constructing and returning schema instance that
is similar to this one, except that it will be using header line.
|
CsvSchema |
withLineSeparator(String sep) |
CsvSchema |
withNullValue(String nvl) |
CsvSchema |
withoutArrayElementSeparator() |
CsvSchema |
withoutColumns() |
CsvSchema |
withoutComments()
Method to indicate that "hash comments" are NOT allowed for document
described by this schema.
|
CsvSchema |
withoutEscapeChar() |
CsvSchema |
withoutHeader()
Helper method for construcing and returning schema instance that
is similar to this one, except that it will not be using header line.
|
CsvSchema |
withoutQuoteChar() |
CsvSchema |
withQuoteChar(char c) |
CsvSchema |
withSkipFirstDataRow(boolean state) |
CsvSchema |
withStrictHeaders(boolean state)
Returns a clone of this instance by changing or setting the
strict headers flag
|
CsvSchema |
withUseHeader(boolean state) |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
forEach, spliterator
protected static final int ENCODING_FEATURE_USE_HEADER
protected static final int ENCODING_FEATURE_SKIP_FIRST_DATA_ROW
protected static final int ENCODING_FEATURE_ALLOW_COMMENTS
protected static final int ENCODING_FEATURE_REORDER_COLUMNS
protected static final int ENCODING_FEATURE_STRICT_HEADERS
protected static final int DEFAULT_ENCODING_FEATURES
protected static final char[] NO_CHARS
public static final char DEFAULT_COLUMN_SEPARATOR
public static final String DEFAULT_ARRAY_ELEMENT_SEPARATOR
public static final String NO_ARRAY_ELEMENT_SEPARATOR
public static final String DEFAULT_ANY_PROPERTY_NAME
null
is used as marker.public static final char DEFAULT_QUOTE_CHAR
public static final char[] DEFAULT_NULL_VALUE
NOTE: before 2.6, this value default to empty char[]
; changed
to Java null in 2.6.
public static final int DEFAULT_ESCAPE_CHAR
public static final char[] DEFAULT_LINEFEED
protected static final CsvSchema.Column[] NO_COLUMNS
protected final CsvSchema.Column[] _columns
protected final Map<String,CsvSchema.Column> _columnsByName
protected int _features
protected final char _columnSeparator
protected final String _arrayElementSeparator
protected final int _quoteChar
protected final int _escapeChar
protected final char[] _lineSeparator
protected final char[] _nullValue
protected transient String _nullValueAsString
protected final String _anyPropertyName
null
disables use of
"any properties" (and they are either ignored, or an exception
is thrown, depending on other settings); setting it to a non-null
String value will expose all extra properties under one specified
name.@Deprecated public CsvSchema(CsvSchema.Column[] columns, int features, char columnSeparator, int quoteChar, int escapeChar, char[] lineSeparator, int arrayElementSeparator, char[] nullValue)
CsvSchema(Column[], int, char, int, int, char[], String, char[], String)
insteadpublic CsvSchema(CsvSchema.Column[] columns, int features, char columnSeparator, int quoteChar, int escapeChar, char[] lineSeparator, String arrayElementSeparator, char[] nullValue, String anyPropertyName)
protected CsvSchema(CsvSchema.Column[] columns, int features, char columnSeparator, int quoteChar, int escapeChar, char[] lineSeparator, String arrayElementSeparator, char[] nullValue, Map<String,CsvSchema.Column> columnsByName, String anyPropertyName)
withXxx()
methods.protected CsvSchema(CsvSchema base, CsvSchema.Column[] columns)
sortedBy()
methods.protected CsvSchema(CsvSchema base, int features)
public static CsvSchema.Builder builder()
public static CsvSchema emptySchema()
public CsvSchema.Builder rebuild()
public CsvSchema withUseHeader(boolean state)
public CsvSchema withColumnReordering(boolean state)
state
- New value for settingpublic CsvSchema withStrictHeaders(boolean state)
state
- New value for settingpublic CsvSchema withHeader()
public CsvSchema withoutHeader()
public CsvSchema withSkipFirstDataRow(boolean state)
public CsvSchema withAllowComments(boolean state)
public CsvSchema withComments()
public CsvSchema withoutComments()
protected CsvSchema _withFeature(int feature, boolean state)
public CsvSchema withColumnSeparator(char sep)
public CsvSchema withQuoteChar(char c)
public CsvSchema withoutQuoteChar()
public CsvSchema withEscapeChar(char c)
public CsvSchema withoutEscapeChar()
@Deprecated public CsvSchema withArrayElementSeparator(char c)
withArrayElementSeparator(String)
insteadpublic CsvSchema withoutArrayElementSeparator()
public CsvSchema withoutColumns()
public CsvSchema withColumnsFrom(CsvSchema toAppend)
As with all `withXxx()` methods this method never modifies `this` but either returns it unmodified (if no new columns found from `toAppend`), or constructs a new instance and returns that.
public CsvSchema sortedBy(String... columnNames)
For example, schema that has columns:
"a", "d", "c", "b"ordered with
schema.sortedBy("a", "b");
would result instance that columns in order:
"a", "b", "d", "c"
public CsvSchema sortedBy(Comparator<String> cmp)
Comparator
over column names.public String getSchemaType()
getSchemaType
in interface com.fasterxml.jackson.core.FormatSchema
public boolean usesHeader()
public boolean reordersColumns()
public boolean skipsFirstDataRow()
public boolean allowsComments()
public boolean strictHeaders()
@Deprecated public boolean useHeader()
usesHeader()
instead@Deprecated public boolean skipFirstDataRow()
skipsFirstDataRow()
insteadpublic char getColumnSeparator()
public String getArrayElementSeparator()
public int getQuoteChar()
public int getEscapeChar()
public char[] getLineSeparator()
public char[] getNullValue()
public char[] getNullValueOrEmpty()
getNullValue()
except that undefined null value (one that remains as null
,
or explicitly set as such) will be returned as empty char[]
public String getNullValueString()
public boolean usesQuoteChar()
public boolean usesEscapeChar()
public boolean hasArrayElementSeparator()
public String getAnyPropertyName()
public Iterator<CsvSchema.Column> iterator()
iterator
in interface Iterable<CsvSchema.Column>
public int size()
public CsvSchema.Column column(int index)
0 <= index < size()
public String columnName(int index)
public CsvSchema.Column column(String name)
public CsvSchema.Column column(String name, int probableIndex)
public List<String> getColumnNames()
public Collection<String> getColumnNames(Collection<String> names)
Collection
.public String getColumnDesc()
Copyright © 2022 FasterXML. All rights reserved.