Package org.apache.juneau.marshall.csv

Class CsvSerializer

java.lang.Object

org.apache.juneau.marshall.Context

org.apache.juneau.marshall.MarshallingContextable

org.apache.juneau.marshall.MarshallingTraverseContext

org.apache.juneau.marshall.serializer.Serializer

org.apache.juneau.marshall.serializer.WriterSerializer

org.apache.juneau.marshall.csv.CsvSerializer

All Implemented Interfaces:

Function<Object,String>, ThrowingFunction<Object,String>, CsvMetaProvider, RecordWritable

public class CsvSerializer
extends WriterSerializer
implements CsvMetaProvider, RecordWritable

Serializes POJO models to CSV (Comma Separated Values) format.

This serializer converts Java objects (primarily collections of beans) into CSV format, where each bean becomes a row and bean properties become columns. The first row typically contains column headers derived from bean property names.

JSON Parity Features (opt-in):

• Type discriminator — addBeanTypes().addRootType() adds a _type column for polymorphic parsing.
• Byte arrays — byteArrayFormat(BASE64) (default) or SEMICOLON_DELIMITED for byte[]; primitive arrays as [1;2;3].
• Nested structures — allowNestedStructures(true) enables inline {key:val} and [val;val] in cells.
• Null marker — nullValue("<NULL>") (default) for unambiguous null.

Data Structures Not Supported:

• Parent/inherited properties — Hierarchy flattens; may collide with child names.
• Optional wrappers — May serialize as the inner value; round-trip differs from tree formats.

Best Supported:

Collections of flat beans or maps whose properties are primitives, strings, numbers, enums, dates, byte arrays, or (with allowNestedStructures) nested beans, maps, and lists.

Example output (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	CsvSerializer.Builder	Builder class.

Nested classes/interfaces inherited from class org.apache.juneau.marshall.serializer.WriterSerializer

WriterSerializer.DefaultBuilder

Nested classes/interfaces inherited from class org.apache.juneau.marshall.serializer.Serializer

Serializer.Null

Field Summary

Fields

Modifier and Type	Field	Description
static final CsvSerializer	DEFAULT	Default serializer, all default settings.

Fields inherited from class org.apache.juneau.marshall.serializer.WriterSerializer

maxIndent, quoteChar, quoteCharOverride, useWhitespace

Fields inherited from class org.apache.juneau.marshall.serializer.Serializer

accept, addBeanTypes, addRootType, keepNullProperties, listener, nonDefault, produces, sortCollections, sortMaps, trimEmptyCollections, trimEmptyMaps, trimStrings

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
CsvSerializer(CsvSerializer.Builder builder)	Constructor.

Method Summary

Modifier and Type	Method	Description
CsvSerializer.Builder	copy()	Creates a builder from this context object.
static CsvSerializer.Builder	create()	Creates a new builder for this object.
CsvSerializerSession.Builder	createSession()	Create a session builder based on the properties defined on this context.
CsvByteArrayCellFormat	getByteArrayFormat()	Returns the format for serializing byte[] arrays in 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 written for null values.
CsvSerializerSession	getSession()	Returns a session to use for this context.
boolean	isAllowNestedStructures()	Returns whether inline {key:val} and [val;val] notation is enabled.
boolean	isRecordStreaming()	Streaming-quality signal queryable before opening a cursor.
RecordWriter	writeRecords(Object output)	Convenience delegator that opens a RecordWriter over the output using default session arguments (mirrors WriterSerializer.write(Object)).

Methods inherited from class org.apache.juneau.marshall.serializer.WriterSerializer

applyThrows, getMaxIndent, getQuoteChar, getStreamCharset, isUseWhitespace, isWriterSerializer, println, properties, quoteChar, toString, write

Methods inherited from class org.apache.juneau.marshall.serializer.Serializer

createSerializerBuilder, doWrite, forEachAcceptMediaType, getListener, getMediaTypeRanges, getPrimaryMediaType, getResponseContentType, getResponseHeaders, getUriContext, getUriRelativity, getUriResolution, isAddBeanTypes, isAddRootType, isKeepNullProperties, isNonDefault, isSortCollections, isSortMaps, isTrimEmptyCollections, isTrimEmptyMaps, isTrimStrings, write, writeToString

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

getDetectRecursions, getIgnoreRecursions, getInitialDepth, getMaxDepth, isDetectRecursions, isIgnoreRecursions, shouldDetectRecursions

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

Methods inherited from interface java.util.function.Function

andThen, compose

Methods inherited from interface org.apache.juneau.commons.function.ThrowingFunction

apply

Field Details

DEFAULT

public static final CsvSerializer DEFAULT

Default serializer, all default settings.

Constructor Details

CsvSerializer

public CsvSerializer(CsvSerializer.Builder builder)

Constructor.

Parameters:

builder - The builder for this object.

Method Details

create

public static CsvSerializer.Builder create()

Creates a new builder for this object.

Returns:

A new builder.

getByteArrayFormat

public CsvByteArrayCellFormat getByteArrayFormat()

Returns the format for serializing byte[] arrays in CSV cells.

Returns:

The byte array format.

isAllowNestedStructures

public boolean isAllowNestedStructures()

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

Returns:

Whether nested structures are allowed.

getNullValue

public String getNullValue()

Returns the string written for null values.

Returns:

The null marker.

copy

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

Returns:

A new Builder object.

createSession

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

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 CsvSerializerSession 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 WriterSerializer

Returns:

A new session object.

writeRecords

public RecordWriter writeRecords(Object output)
                          throws IOException

Convenience delegator that opens a RecordWriter over the output using default session arguments (mirrors WriterSerializer.write(Object)).

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

The real implementation lives on CsvSerializerSession.writeRecords(Object). Callers that need request-derived configuration should call createSession() and invoke CsvSerializerSession.writeRecords(Object) on the built session instead.

Specified by:

writeRecords in interface RecordWritable

Parameters:

output - The output.

Returns:

A new RecordWriter.

Throws:

IOException - If a problem occurred opening the underlying output.

isRecordStreaming

public boolean isRecordStreaming()

Description copied from interface: RecordWritable

Streaming-quality signal queryable before opening a cursor.

Specified by:

isRecordStreaming in interface RecordWritable

Returns:

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