Package org.apache.juneau.serializer

Class Serializer

java.lang.Object

org.apache.juneau.Context

org.apache.juneau.BeanContextable

org.apache.juneau.BeanTraverseContext

org.apache.juneau.serializer.Serializer

Direct Known Subclasses:

OutputStreamSerializer, Serializer.Null, SerializerSet.Inherit, SerializerSet.NoInherit, WriterSerializer

public class Serializer
extends BeanTraverseContext

Parent class for all Juneau serializers.

Description

Base serializer class that serves as the parent class for all serializers.

The purpose of this class is:

• Maintain a read-only configuration state of a serializer.
• Create session objects used for serializing POJOs (i.e. SerializerSession).
• Provide convenience methods for serializing POJOs without having to construct session objects.

Subclasses should (but are not required to) extend directly from OutputStreamSerializer or WriterSerializer depending on whether it's a stream or character based serializer.

Subclasses must implement parsing via one of the following methods:

• doSerialize(SerializerSession, SerializerPipe, Object)
• SerializerSession.doSerialize(SerializerPipe, Object)

Notes:

• This class is thread safe and reusable.

See Also:

• Serializers and Parsers

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Serializer.Builder	Builder class.
static class	Serializer.Null	Represents no Serializer.

Field Summary

Fields

Modifier and Type	Field	Description
protected final String	accept
protected final boolean	addBeanTypes
protected final boolean	addRootType
protected final boolean	keepNullProperties
protected final Class<? extends SerializerListener>	listener
protected final String	produces
protected final boolean	sortCollections
protected final boolean	sortMaps
protected final boolean	trimEmptyCollections
protected final boolean	trimEmptyMaps
protected final boolean	trimStrings

Fields inherited from class org.apache.juneau.BeanContextable

beanContext

Fields inherited from class org.apache.juneau.Context

CONTEXT_APPLY_FILTER

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Serializer(Serializer.Builder builder)	Constructor

Method Summary

Modifier and Type	Method	Description
Serializer.Builder	copy()	Creates a builder from this context object.
static Serializer.Builder	create()	Creates a new builder for this object.
static Serializer.Builder	createSerializerBuilder(Class<? extends Serializer> c)	Instantiates a builder of the specified serializer class.
SerializerSession.Builder	createSession()	Create a session builder based on the properties defined on this context.
protected void	doSerialize(SerializerSession session, SerializerPipe pipe, Object o)	Serializes a POJO to the specified pipe.
final Serializer	forEachAcceptMediaType(Consumer<MediaType> action)	Performs an action on the media types handled based on the value of the accept parameter passed into the constructor.
protected final Class<? extends SerializerListener>	getListener()	Serializer listener.
final MediaRanges	getMediaTypeRanges()	Returns the media types handled based on the value of the accept parameter passed into the constructor.
final MediaType	getPrimaryMediaType()	Returns the first entry in the accept parameter passed into the constructor.
final MediaType	getResponseContentType()	Optional method that returns the response Content-Type for this serializer if it is different from the matched media type.
Map<String,String>	getResponseHeaders(SerializerSession session)	Optional method that specifies HTTP request headers for this serializer.
SerializerSession	getSession()	Returns a session to use for this context.
protected final UriContext	getUriContext()	URI context bean.
protected final UriRelativity	getUriRelativity()	URI relativity.
protected final UriResolution	getUriResolution()	URI resolution.
protected boolean	isAddBeanTypes()	Add "_type" properties when needed.
protected final boolean	isAddRootType()	Add type attribute to root nodes.
protected final boolean	isKeepNullProperties()	Don't trim null bean property values.
protected final boolean	isSortCollections()	Sort arrays and collections alphabetically.
protected final boolean	isSortMaps()	Sort maps alphabetically.
protected final boolean	isTrimEmptyCollections()	Trim empty lists and arrays.
protected final boolean	isTrimEmptyMaps()	Trim empty maps.
protected final boolean	isTrimStrings()	Trim strings.
boolean	isWriterSerializer()	Returns true if this serializer subclasses from WriterSerializer.
protected FluentMap<String,Object>	properties()	Returns the properties on this bean as a map for debugging.
Object	serialize(Object o)	Shortcut method for serializing objects directly to either a String or byte[] depending on the serializer type.
final void	serialize(Object o, Object output)	Serializes a POJO to the specified output stream or writer.
final String	serializeToString(Object o)	Convenience method for serializing an object to a String.

Methods inherited from class org.apache.juneau.BeanTraverseContext

getDetectRecursions, getIgnoreRecursions, getInitialDepth, getMaxDepth, isDetectRecursions, isIgnoreRecursions

Methods inherited from class org.apache.juneau.BeanContextable

getBeanContext

Methods inherited from class org.apache.juneau.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

addBeanTypes

protected final boolean addBeanTypes

addRootType

protected final boolean addRootType

keepNullProperties

protected final boolean keepNullProperties

sortCollections

protected final boolean sortCollections

sortMaps

protected final boolean sortMaps

trimEmptyCollections

protected final boolean trimEmptyCollections

trimEmptyMaps

protected final boolean trimEmptyMaps

trimStrings

protected final boolean trimStrings

listener

protected final Class<? extends SerializerListener> listener

accept

protected final String accept

produces

protected final String produces

Constructor Details

Serializer

protected Serializer(Serializer.Builder builder)

Constructor

Parameters:

builder - The builder this object.

Method Details

create

public static Serializer.Builder create()

Creates a new builder for this object.

Returns:

A new builder.

createSerializerBuilder

public static Serializer.Builder createSerializerBuilder(Class<? extends Serializer> c)

Instantiates a builder of the specified serializer class.

Looks for a public static method called create that returns an object that can be passed into a public or protected constructor of the class.

Parameters:

c - The builder to create.

Returns:

A new builder.

copy

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

Specified by:

copy in class BeanTraverseContext

Returns:

A new Builder object.

createSession

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

Returns:

A new session builder.

forEachAcceptMediaType

public final Serializer forEachAcceptMediaType(Consumer<MediaType> action)

Performs an action on the media types handled based on the value of the accept parameter passed into the constructor.

The order of the media types are the same as those in the accept parameter.

Parameters:

action - The action to perform on the media types.

Returns:

This object.

getMediaTypeRanges

public final MediaRanges getMediaTypeRanges()

Returns the media types handled based on the value of the accept parameter passed into the constructor.

Note that the order of these ranges are from high to low q-value.

Returns:

The list of media types. Never null.

getPrimaryMediaType

public final MediaType getPrimaryMediaType()

Returns the first entry in the accept parameter passed into the constructor.

This signifies the 'primary' media type for this serializer.

Returns:

The media type. Never null.

getResponseContentType

public final MediaType getResponseContentType()

Optional method that returns the response Content-Type for this serializer if it is different from the matched media type.

This method is specified to override the content type for this serializer. For example, the Json5Serializer class returns that it handles media type "text/json5", but returns "text/json" as the actual content type. This allows clients to request specific 'flavors' of content using specialized Accept header values.

This method is typically meaningless if the serializer is being used stand-alone (i.e. outside of a REST server or client).

Returns:

The response content type. If null, then the matched media type is used.

getResponseHeaders

public Map<String,String> getResponseHeaders(SerializerSession session)

Optional method that specifies HTTP request headers for this serializer.

For example, SoapXmlSerializer needs to set a SOAPAction header.

This method is typically meaningless if the serializer is being used stand-alone (i.e. outside of a REST server or client).

Parameters:

session - The current session.

Returns:

The HTTP headers to set on HTTP requests. Never null.

getSession

public SerializerSession 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 Context

Returns:

A new session object.

isWriterSerializer

public boolean isWriterSerializer()

Returns true if this serializer subclasses from WriterSerializer.

Returns:

true if this serializer subclasses from WriterSerializer.

serialize

public Object serialize(Object o)
                 throws SerializeException

Shortcut method for serializing objects directly to either a String or byte[] depending on the serializer type.

Parameters:

o - The object to serialize.

Returns:

The serialized object.
Character-based serializers will return a String
Stream-based serializers will return a byte[]

Throws:

SerializeException - If a problem occurred trying to convert the output.

serialize

public final void serialize(Object o,
 Object output)
                     throws SerializeException,
IOException

Serializes a POJO to the specified output stream or writer.

Equivalent to calling serializer.createSession().serialize(o, output);

Parameters:

o - The object to serialize.

output - The output object.
Character-based serializers can handle the following output class types:

• Writer
• OutputStream - Output will be written as UTF-8 encoded stream.
• File - Output will be written as system-default encoded stream.
• StringBuilder - Output will be written to the specified string builder.

Stream-based serializers can handle the following output class types:

• OutputStream
• File

Throws:

SerializeException - If a problem occurred trying to convert the output.

IOException - Thrown by the underlying stream.

serializeToString

public final String serializeToString(Object o)
                               throws SerializeException

Convenience method for serializing an object to a String.

For writer-based serializers, this is identical to calling serialize(Object).
For stream-based serializers, this converts the returned byte array to a string based on the OutputStreamSerializer.Builder.binaryFormat(BinaryFormat) setting.

Parameters:

o - The object to serialize.

Returns:

The output serialized to a string.

Throws:

SerializeException - If a problem occurred trying to convert the output.

doSerialize

protected void doSerialize(SerializerSession session,
 SerializerPipe pipe,
 Object o)
                    throws IOException,
SerializeException

Serializes a POJO to the specified pipe.

Parameters:

session - The current session.

pipe - Where to send the output from the serializer.

o - The object to serialize.

Throws:

IOException - Thrown by underlying stream.

SerializeException - Problem occurred trying to serialize object.

getListener

protected final Class<? extends SerializerListener> getListener()

Serializer listener.

Returns:

Class used to listen for errors and warnings that occur during serialization.

See Also:

• Serializer.Builder.listener(Class)

getUriContext

protected final UriContext getUriContext()

URI context bean.

Returns:

Bean used for resolution of URIs to absolute or root-relative form.

See Also:

• Serializer.Builder.uriContext(UriContext)

getUriRelativity

protected final UriRelativity getUriRelativity()

URI relativity.

Returns:

Defines what relative URIs are relative to when serializing any of the following:

See Also:

• Serializer.Builder.uriRelativity(UriRelativity)

getUriResolution

protected final UriResolution getUriResolution()

URI resolution.

Returns:

Defines the resolution level for URIs when serializing URIs.

See Also:

• Serializer.Builder.uriResolution(UriResolution)

isAddBeanTypes

protected boolean isAddBeanTypes()

Add "_type" properties when needed.

Returns:

true if "_type" properties added to beans if their type cannot be inferred through reflection.

See Also:

• Serializer.Builder.addBeanTypes()

isAddRootType

protected final boolean isAddRootType()

Add type attribute to root nodes.

Returns:

true if type property should be added to root node.

See Also:

• Serializer.Builder.addRootType()

isKeepNullProperties

protected final boolean isKeepNullProperties()

Don't trim null bean property values.

Returns:

true if null bean values are serialized to the output.

See Also:

• Serializer.Builder.keepNullProperties()

isSortCollections

protected final boolean isSortCollections()

Sort arrays and collections alphabetically.

Returns:

true if arrays and collections are copied and sorted before serialization.

See Also:

• Serializer.Builder.sortCollections()

isSortMaps

protected final boolean isSortMaps()

Sort maps alphabetically.

Returns:

true if maps are copied and sorted before serialization.

See Also:

• Serializer.Builder.sortMaps()

isTrimEmptyCollections

protected final boolean isTrimEmptyCollections()

Trim empty lists and arrays.

Returns:

true if empty lists and arrays are not serialized to the output.

See Also:

• Serializer.Builder.trimEmptyCollections()

isTrimEmptyMaps

protected final boolean isTrimEmptyMaps()

Trim empty maps.

Returns:

true if empty map values are not serialized to the output.

See Also:

• Serializer.Builder.trimEmptyMaps()

isTrimStrings

protected final boolean isTrimStrings()

Trim strings.

Returns:

true if string values will be trimmed of whitespace using String.trim() before being serialized.

See Also:

• Serializer.Builder.trimStrings()

properties

protected FluentMap<String,Object> properties()

Description copied from class: Context

Returns the properties on this bean as a map for debugging.

Overrides:

properties in class BeanTraverseContext

Returns:

The properties on this bean as a map for debugging.