Package org.apache.juneau.serializer.annotation

Annotation Type SerializerConfig

@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Inherited
@ContextApply({SerializerApply.class,OutputStreamSerializerApply.class,WriterSerializerApply.class})
public @interface SerializerConfig

Annotation for specifying config properties defined in Serializer, OutputStreamSerializer, and WriterSerializer.

Used primarily for specifying bean configuration properties on REST classes and methods.

See Also:

• Serializers and Parsers

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	addBeanTypes	Add "_type" properties when needed.
String	addRootType	Add type attribute to root nodes.
String	binaryFormat	Binary output format.
String	detectRecursions	Automatically detect POJO recursions.
String	fileCharset	File charset.
String	ignoreRecursions	Ignore recursion errors.
String	initialDepth	Initial depth.
String	keepNullProperties	Don't trim null bean property values.
Class<? extends SerializerListener>	listener	Serializer listener.
String	maxDepth	Max traversal depth.
String	maxIndent	Maximum indentation.
String	quoteChar	Quote character.
int	rank	Optional rank for this config.
String	sortCollections	Sort arrays and collections alphabetically.
String	sortMaps	Sort maps alphabetically.
String	streamCharset	Output stream charset.
String	trimEmptyCollections	Trim empty lists and arrays.
String	trimEmptyMaps	Trim empty maps.
String	trimStrings	Trim strings.
String	uriContext	URI context bean.
String	uriRelativity	URI relativity.
String	uriResolution	URI resolution.
String	useWhitespace	Use whitespace.

Element Details

rank

int rank

Optional rank for this config.

Can be used to override default ordering and application of config annotations.

Returns:

The annotation value.

Default:

0

binaryFormat

String binaryFormat

Binary output format.

When using the Serializer.serializeToString(Object) method on stream-based serializers, this defines the format to use when converting the resulting byte array to a string.

• "SPACED_HEX"
• "HEX" (default)
• "BASE64"

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• OutputStreamSerializer.Builder.binaryFormat(BinaryFormat)

Returns:

The annotation value.

Default:

""

addBeanTypes

String addBeanTypes

Add "_type" properties when needed.

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

This is used to recreate the correct objects during parsing if the object types cannot be inferred.
For example, when serializing a Map<String,Object> field where the bean class cannot be determined from the type of the values.

Note the differences between the following settings:

• Serializer.Builder.addRootType() - Affects whether '_type' is added to root node.
• Serializer.Builder.addBeanTypes() - Affects whether '_type' is added to any nodes.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.addBeanTypes()

Returns:

The annotation value.

Default:

""

addRootType

String addRootType

Add type attribute to root nodes.

When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level type information that might normally be included to determine the data type will not be serialized.

For example, when serializing a top-level POJO with a @Bean(typeName) value, a '_type' attribute will only be added when this setting is enabled.

Note the differences between the following settings:

• Serializer.Builder.addRootType() - Affects whether '_type' is added to root node.
• Serializer.Builder.addBeanTypes() - Affects whether '_type' is added to any nodes.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.addRootType()

Returns:

The annotation value.

Default:

""

keepNullProperties

String keepNullProperties

Don't trim null bean property values.

If "true", null bean values will be serialized to the output.

Note that not enabling this setting has the following effects on parsing:

• Map entries with null values will be lost.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.keepNullProperties()

Returns:

The annotation value.

Default:

""

listener

Class<? extends SerializerListener> listener

Serializer listener.

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

See Also:

• Serializer.Builder.listener(Class)

Returns:

The annotation value.

Default:

org.apache.juneau.serializer.SerializerListener.Void.class

sortCollections

String sortCollections

Sort arrays and collections alphabetically.

Copies and sorts the contents of arrays and collections before serializing them.

Note that this introduces a performance penalty.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.sortCollections()

Returns:

The annotation value.

Default:

""

sortMaps

String sortMaps

Sort maps alphabetically.

Copies and sorts the contents of maps by their keys before serializing them.

Note that this introduces a performance penalty.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.sortMaps()

Returns:

The annotation value.

Default:

""

trimEmptyCollections

String trimEmptyCollections

Trim empty lists and arrays.

If "true", empty lists and arrays will not be serialized.

Note that enabling this setting has the following effects on parsing:

• Map entries with empty list values will be lost.
• Bean properties with empty list values will not be set.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.trimEmptyCollections()

Returns:

The annotation value.

Default:

""

trimEmptyMaps

String trimEmptyMaps

Trim empty maps.

If "true", empty map values will not be serialized to the output.

Note that enabling this setting has the following effects on parsing:

• Bean properties with empty map values will not be set.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.trimEmptyMaps()

Returns:

The annotation value.

Default:

""

trimStrings

String trimStrings

Trim strings.

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

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.trimStrings()

Returns:

The annotation value.

Default:

""

uriContext

String uriContext

URI context bean.

Description:

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

Notes:

• Format: JSON object representing a UriContext
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.uriContext(UriContext)

Returns:

The annotation value.

Default:

""

uriRelativity

String uriRelativity

URI relativity.

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

• URI
• URL
• Properties and classes annotated with @Uri

• "RESOURCE" (default) - Relative URIs should be considered relative to the servlet URI.
• "PATH_INFO" - Relative URIs should be considered relative to the request URI.

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.uriRelativity(UriRelativity)
• URIs

Returns:

The annotation value.

Default:

""

uriResolution

String uriResolution

URI resolution.

Defines the resolution level for URIs when serializing any of the following:

• URI
• URL
• Properties and classes annotated with @Uri

• "ABSOLUTE" - Resolve to an absolute URL (e.g. "http://host:port/context-root/servlet-path/path-info").
• "ROOT_RELATIVE" - Resolve to a root-relative URL (e.g. "/context-root/servlet-path/path-info").
• "NONE" (default) - Don't do any URL resolution.

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• Serializer.Builder.uriResolution(UriResolution)
• URIs

Returns:

The annotation value.

Default:

""

fileCharset

String fileCharset

File charset.

The character set to use for writing Files to the file system.

Used when passing in files to Serializer.serialize(Object, Object).

Notes:

• Format: string
• "DEFAULT" can be used to indicate the JVM default file system charset.
• Default: JVM system default.
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").
• This setting does not apply to the RDF serializers.

See Also:

• WriterSerializer.Builder.fileCharset(java.nio.charset.Charset)

Returns:

The annotation value.

Default:

""

maxIndent

String maxIndent

Maximum indentation.

Specifies the maximum indentation level in the serialized document.

Notes:

• Format: integer
• Default: 100
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").
• This setting does not apply to the RDF serializers.

See Also:

• WriterSerializer.Builder.maxIndent(int)

Returns:

The annotation value.

Default:

""

quoteChar

String quoteChar

Quote character.

This is the character used for quoting attributes and values.

Notes:

• Default: "
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").
• This setting does not apply to the RDF serializers.

See Also:

• WriterSerializer.Builder.quoteChar(char)

Returns:

The annotation value.

Default:

""

streamCharset

String streamCharset

Output stream charset.

The character set to use when writing to OutputStreams.

Used when passing in output streams and byte arrays to Serializer.serialize(Object, Object).

Notes:

• Format: string
• Default: "utf-8".
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").
• This setting does not apply to the RDF serializers.

See Also:

• WriterSerializer.Builder.streamCharset(Charset)

Returns:

The annotation value.

Default:

""

useWhitespace

String useWhitespace

Use whitespace.

If "true", whitespace is added to the output to improve readability.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• WriterSerializer.Builder.useWhitespace()

Returns:

The annotation value.

Default:

""

detectRecursions

String detectRecursions

Automatically detect POJO recursions.

Specifies that recursions should be checked for during traversal.

Recursions can occur when traversing models that aren't true trees but rather contain loops.
In general, unchecked recursions cause stack-overflow-errors.
These show up as ParseExceptions with the message "Depth too deep. Stack overflow occurred.".

The behavior when recursions are detected depends on the value for BeanTraverseContext.Builder.ignoreRecursions().

For example, if a model contains the links A->B->C->A, then the JSON generated will look like the following when BEANTRAVERSE_ignoreRecursions is true...

{A:{B:{C:null}}}

• "true"
• "false" (default)

Notes:

• Checking for recursion can cause a small performance penalty.
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.detectRecursions()

Returns:

The annotation value.

Default:

""

ignoreRecursions

String ignoreRecursions

Ignore recursion errors.

Used in conjunction with BeanTraverseContext.Builder.detectRecursions().
Setting is ignored if BEANTRAVERSE_detectRecursions is "false".

If "true", when we encounter the same object when traversing a tree, we set the value to null.
Otherwise, a BeanRecursionException is thrown with the message "Recursion occurred, stack=...".

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.ignoreRecursions()

Returns:

The annotation value.

Default:

""

initialDepth

String initialDepth

Initial depth.

The initial indentation level at the root.
Useful when constructing document fragments that need to be indented at a certain level.

Notes:

• Format: integer
• Default value: "0"
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.initialDepth(int)

Returns:

The annotation value.

Default:

""

maxDepth

String maxDepth

Max traversal depth.

Abort traversal if specified depth is reached in the POJO tree.
If this depth is exceeded, an exception is thrown.

Notes:

• Format: integer
• Default value: "100"
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.maxDepth(int)

Returns:

The annotation value.

Default:

""