com.fasterxml.jackson.dataformat.csv

Class CsvSchema

java.lang.Object

com.fasterxml.jackson.dataformat.csv.CsvSchema

All Implemented Interfaces:

com.fasterxml.jackson.core.FormatSchema, Iterable<CsvSchema.Column>

public class CsvSchema
extends Object
implements com.fasterxml.jackson.core.FormatSchema, Iterable<CsvSchema.Column>

Simple 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 ('|')
• 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)

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:

• Manually build one, using CsvSchema.Builder
• Modify existing schema (using withXxx methods or rebuild() for creating CsvSchema.Builder)
• Create schema based on a POJO definition (Class), using CsvMapper methods like CsvMapper.schemaFor(java.lang.Class).
• Request that CsvParser reads schema from the first line: enable "useHeader" property for the initial schema, and let parser read column names from the document itself.

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

Modifier and Type	Field and Description
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 char[]	_lineSeparator
protected int	_quoteChar
protected boolean	_skipFirstDataRow
protected boolean	_useHeader
static char	DEFAULT_COLUMN_SEPARATOR
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_QUOTE_CHAR
static boolean	DEFAULT_SKIP_FIRST_DATA_ROW
static boolean	DEFAULT_USE_HEADER By default we do NOT expect the first line to be header.
protected static CsvSchema.Column[]	NO_COLUMNS

Constructor Summary

Constructors

Modifier	Constructor and Description
	CsvSchema(CsvSchema.Column[] columns, boolean useHeader, boolean skipFirstDataRow, char columnSeparator, int quoteChar, int escapeChar, char[] lineSeparator)
protected	CsvSchema(CsvSchema.Column[] columns, boolean useHeader, boolean skipFirstDataRow, char columnSeparator, int quoteChar, int escapeChar, char[] lineSeparator, Map<String,CsvSchema.Column> columnsByName) Copy constructor used for creating variants using withXxx() methods.
protected	CsvSchema(CsvSchema base, CsvSchema.Column[] columns) Copy constructor used for creating variants using sortedBy() methods.

Method Summary

Methods

Modifier and Type	Method and Description
static CsvSchema.Builder	builder()
CsvSchema.Column	column(int index)
CsvSchema.Column	column(String name)
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	getColumnDesc() Method for getting description of column definitions in developer-readable form
char	getColumnSeparator()
int	getEscapeChar()
char[]	getLineSeparator()
int	getQuoteChar()
String	getSchemaType()
Iterator<CsvSchema.Column>	iterator()
CsvSchema.Builder	rebuild() Helper method for constructing Builder that can be used to create modified schema.
int	size()
boolean	skipFirstDataRow()
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.
String	toString()
boolean	useHeader()
boolean	usesEscapeChar()
boolean	usesQuoteChar()
CsvSchema	withColumnSeparator(char sep)
CsvSchema	withEscapeChar(char c)
CsvSchema	withHeader() Helper method for construcing and returning schema instance that is similar to this one, except that it will be using header line.
CsvSchema	withLineSeparator(String sep)
CsvSchema	withoutColumns()
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	withUseHeader(boolean state)

Methods inherited from class java.lang.Object

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

Field Detail

NO_COLUMNS

protected static final CsvSchema.Column[] NO_COLUMNS

DEFAULT_COLUMN_SEPARATOR

public static final char DEFAULT_COLUMN_SEPARATOR

See Also:

Constant Field Values

DEFAULT_QUOTE_CHAR

public static final char DEFAULT_QUOTE_CHAR

See Also:

Constant Field Values

DEFAULT_ESCAPE_CHAR

public static final 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

See Also:

Constant Field Values

DEFAULT_LINEFEED

public static final char[] DEFAULT_LINEFEED

DEFAULT_USE_HEADER

public static final boolean DEFAULT_USE_HEADER

By default we do NOT expect the first line to be header.

See Also:

Constant Field Values

DEFAULT_SKIP_FIRST_DATA_ROW

public static final boolean DEFAULT_SKIP_FIRST_DATA_ROW

See Also:

Constant Field Values

_columns

protected final CsvSchema.Column[] _columns

Column definitions, needed for optional header and/or mapping of field names to column positions.

_columnsByName

protected final Map<String,CsvSchema.Column> _columnsByName

_useHeader

protected final boolean _useHeader

_skipFirstDataRow

protected final boolean _skipFirstDataRow

_columnSeparator

protected final char _columnSeparator

_quoteChar

protected final int _quoteChar

_escapeChar

protected final int _escapeChar

_lineSeparator

protected final char[] _lineSeparator

Constructor Detail

CsvSchema

public CsvSchema(CsvSchema.Column[] columns,
         boolean useHeader,
         boolean skipFirstDataRow,
         char columnSeparator,
         int quoteChar,
         int escapeChar,
         char[] lineSeparator)

CsvSchema

protected CsvSchema(CsvSchema.Column[] columns,
         boolean useHeader,
         boolean skipFirstDataRow,
         char columnSeparator,
         int quoteChar,
         int escapeChar,
         char[] lineSeparator,
         Map<String,CsvSchema.Column> columnsByName)

Copy constructor used for creating variants using withXxx() methods.

CsvSchema

protected CsvSchema(CsvSchema base,
         CsvSchema.Column[] columns)

Copy constructor used for creating variants using sortedBy() methods.

Method Detail

builder

public static CsvSchema.Builder builder()

emptySchema

public 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

rebuild

public CsvSchema.Builder rebuild()

Helper method for constructing Builder that can be used to create modified schema.

withUseHeader

public CsvSchema withUseHeader(boolean state)

withHeader

public CsvSchema withHeader()

Helper method for construcing and returning schema instance that is similar to this one, except that it will be using header line.

withoutHeader

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

withSkipFirstDataRow

public CsvSchema withSkipFirstDataRow(boolean state)

withColumnSeparator

public CsvSchema withColumnSeparator(char sep)

withQuoteChar

public CsvSchema withQuoteChar(char c)

withoutQuoteChar

public CsvSchema withoutQuoteChar()

withEscapeChar

public CsvSchema withEscapeChar(char c)

withoutEscapeChar

public CsvSchema withoutEscapeChar()

withLineSeparator

public CsvSchema withLineSeparator(String sep)

withoutColumns

public CsvSchema withoutColumns()

sortedBy

public CsvSchema sortedBy(String... columnNames)

Mutant factory method that will construct a new instance in which columns are sorted based on names given as argument. Columns not listed in argument will be sorted after those within list, using existing ordering.

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"

Since:

2.4

sortedBy

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

Since:

2.4

getSchemaType

public String getSchemaType()

Specified by:

getSchemaType in interface com.fasterxml.jackson.core.FormatSchema

useHeader

public boolean useHeader()

skipFirstDataRow

public boolean skipFirstDataRow()

getColumnSeparator

public char getColumnSeparator()

getQuoteChar

public int getQuoteChar()

getEscapeChar

public int getEscapeChar()

getLineSeparator

public char[] getLineSeparator()

usesQuoteChar

public boolean usesQuoteChar()

usesEscapeChar

public boolean usesEscapeChar()

iterator

public Iterator<CsvSchema.Column> iterator()

Specified by:

iterator in interface Iterable<CsvSchema.Column>

size

public int size()

column

public CsvSchema.Column column(int index)

column

public CsvSchema.Column column(String name)

getColumnDesc

public String getColumnDesc()

Method for getting description of column definitions in developer-readable form

toString

public String toString()

Overrides:

toString in class Object