Package org.apache.juneau.marshall.csv

Class CsvParser

java.lang.Object

org.apache.juneau.marshall.Context

org.apache.juneau.marshall.MarshallingContextable

org.apache.juneau.marshall.parser.Parser

org.apache.juneau.marshall.parser.ReaderParser

org.apache.juneau.marshall.csv.CsvParser

All Implemented Interfaces:

CsvMetaProvider, RecordReadable

public class CsvParser
extends ReaderParser
implements CsvMetaProvider, RecordReadable

Parses CSV (Comma Separated Values) input into Java objects.

Parses RFC 4180-compliant CSV into collections of beans, maps, or simple values. Each row becomes an element; the header row defines column names.

JSON Parity Features (opt-in):

• Type discriminator — Parse _type column when present; use beanDictionary() for polymorphic types.
• Byte arrays — byteArrayFormat(BASE64) or SEMICOLON_DELIMITED; primitive arrays from [1;2;3].
• Nested structures — allowNestedStructures(true) parses inline {key:val} and [val;val] in cells.
• Null marker — nullValue("<NULL>") (default); cells matching this are parsed as null.

Data Structures Not Supported:

• Parent/inherited properties — Bean hierarchy cannot be reconstructed from flat columns.
• Optional wrappers — Round-trip may differ from tree formats.

Best Supported:

Parsing into Collection of flat beans or maps, or single beans/maps with simple property types (primitives, strings, numbers, enums, dates, byte arrays, or nested structures when enabled).

Example input (list of maps with a,b):

a,b foo,bar

Complex (list of beans with nested address, flattened):

name,age,address_street,address_city,address_state,tags Alice,30,123 Main St,Boston,MA,"a,b,c"

Notes:

• This class is thread safe and reusable.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CsvParser.Builder	Builder class.

Nested classes/interfaces inherited from class org.apache.juneau.marshall.parser.ReaderParser

ReaderParser.DefaultBuilder

Nested classes/interfaces inherited from class org.apache.juneau.marshall.parser.Parser

Parser.Null

Field Summary

Fields

Modifier and Type	Field	Description
static final CsvParser	DEFAULT	Default parser, all default settings.

Fields inherited from class org.apache.juneau.marshall.parser.Parser

autoCloseStreams, consumes, debugOutputLines, listener, nulls, trimStrings, unbuffered

Fields inherited from class org.apache.juneau.marshall.MarshallingContextable

marshallingContext

Fields inherited from class org.apache.juneau.marshall.Context

CONTEXT_APPLY_FILTER

Constructor Summary

Constructors

Constructor	Description
CsvParser(CsvParser.Builder builder)	Constructor.

Method Summary

Modifier and Type	Method	Description
CsvParser.Builder	copy()	Creates a builder from this context object.
static CsvParser.Builder	create()	Creates a new builder for this object.
CsvParserSession.Builder	createSession()	Create a session builder based on the properties defined on this context.
CsvByteArrayCellFormat	getByteArrayFormat()	Returns the format for parsing byte[] arrays from CSV cells.
CsvBeanPropertyMeta	getCsvBeanPropertyMeta(BeanPropertyMeta bpm)	Returns the language-specific metadata on the specified bean property.
CsvClassMeta	getCsvClassMeta(ClassMeta<?> cm)	Returns the language-specific metadata on the specified class.
String	getNullValue()	Returns the string that denotes null when parsing.
CsvParserSession	getSession()	Returns a session to use for this context.
boolean	isAllowNestedStructures()	Returns whether inline {key:val} and [val;val] notation parsing is enabled.
boolean	isRecordStreaming()	Streaming-quality signal queryable before opening a cursor.
RecordReader	readRecords(Object input)	Convenience delegator that opens a RecordReader over the input using default session arguments (mirrors Parser.read(Object, Class)).

Methods inherited from class org.apache.juneau.marshall.parser.ReaderParser

getStreamCharset, isReaderParser, properties

Methods inherited from class org.apache.juneau.marshall.parser.Parser

canHandle, createParserBuilder, doRead, getDebugOutputLines, getListener, getMediaTypes, getNulls, getPrimaryMediaType, isAutoCloseStreams, isTrimStrings, isUnbuffered, read, read, read, read, read, read, readArgs, readIntoCollection, readIntoMap, readWithOuter

Methods inherited from class org.apache.juneau.marshall.MarshallingContextable

getDurationFormat, getMarshallingContext, getPeriodFormat

Methods inherited from class org.apache.juneau.marshall.Context

createBuilder, getAnnotationProvider, init, isDebug, toString

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT

public static final CsvParser DEFAULT

Default parser, all default settings.

Constructor Details

CsvParser

public CsvParser(CsvParser.Builder builder)

Constructor.

Parameters:

builder - The builder for this object.

Method Details

create

public static CsvParser.Builder create()

Creates a new builder for this object.

Returns:

A new builder.

getByteArrayFormat

public CsvByteArrayCellFormat getByteArrayFormat()

Returns the format for parsing byte[] arrays from CSV cells.

Returns:

The byte array format.

isAllowNestedStructures

public boolean isAllowNestedStructures()

Returns whether inline {key:val} and [val;val] notation parsing is enabled.

Returns:

Whether nested structures are allowed.

getNullValue

public String getNullValue()

Returns the string that denotes null when parsing.

Returns:

The null marker.

copy

public CsvParser.Builder copy()

Description copied from class: Context

Creates a builder from this context object.

Builders are used to define new contexts (e.g. serializers, parsers) based on existing configurations.

Overrides:

copy in class Parser

Returns:

A new Builder object.

createSession

public CsvParserSession.Builder createSession()

Description copied from class: Context

Create a session builder based on the properties defined on this context.

Use this method for creating sessions where you want to override basic settings. Otherwise, use Context.getSession() directly.

Overrides:

createSession in class ReaderParser

Returns:

A new session builder.

getCsvBeanPropertyMeta

public CsvBeanPropertyMeta getCsvBeanPropertyMeta(BeanPropertyMeta bpm)

Description copied from interface: CsvMetaProvider

Returns the language-specific metadata on the specified bean property.

Specified by:

getCsvBeanPropertyMeta in interface CsvMetaProvider

Parameters:

bpm - The bean property to return the metadata on.

Returns:

The metadata.

getCsvClassMeta

public CsvClassMeta getCsvClassMeta(ClassMeta<?> cm)

Description copied from interface: CsvMetaProvider

Returns the language-specific metadata on the specified class.

Specified by:

getCsvClassMeta in interface CsvMetaProvider

Parameters:

cm - The class to return the metadata on.

Returns:

The metadata.

getSession

public CsvParserSession getSession()

Description copied from class: Context

Returns a session to use for this context.

Note that subclasses may opt to return a reusable non-modifiable session.

Overrides:

getSession in class ReaderParser

Returns:

A new session object.

readRecords

public RecordReader readRecords(Object input)
                         throws IOException

Convenience delegator that opens a RecordReader over the input using default session arguments (mirrors Parser.read(Object, Class)).

CSV is naturally row-oriented — each row becomes one record — but the current cursor is buffered (the full row list is materialized at parse); a streaming implementation is a Phase 3b deferred item, so isRecordStreaming() returns false.

The real implementation lives on CsvParserSession.readRecords(Object). Callers that need request-derived configuration (locale, timezone, schema, swaps) should call createSession() and invoke CsvParserSession.readRecords(Object) on the built session instead.

Specified by:

readRecords in interface RecordReadable

Parameters:

input - The input.

Returns:

A new RecordReader cursor.

Throws:

IOException - If a problem occurred opening the underlying input.

isRecordStreaming

public boolean isRecordStreaming()

Description copied from interface: RecordReadable

Streaming-quality signal queryable before opening a cursor.

Specified by:

isRecordStreaming in interface RecordReadable

Returns:

true if RecordReadable.readRecords(Object) returns an O(1)-memory streaming cursor; false for buffered (whole-value) formats backed by RecordAdapter.