org.apache.juneau.xml

Class XmlSerializer

java.lang.Object

org.apache.juneau.Context

org.apache.juneau.BeanContext

org.apache.juneau.serializer.Serializer

org.apache.juneau.serializer.WriterSerializer

org.apache.juneau.xml.XmlSerializer

Direct Known Subclasses:

HtmlSerializer, SoapXmlSerializer, XmlDocSerializer, XmlSchemaSerializer, XmlSerializer.Ns, XmlSerializer.NsSq, XmlSerializer.NsSqReadable, XmlSerializer.Sq, XmlSerializer.SqReadable

public class XmlSerializer
extends WriterSerializer

Serializes POJO models to XML.

Media types

Handles Accept types: text/xml

Produces Content-Type types: text/xml

Description

See the JsonSerializer class for details on how Java models map to JSON.

For example, the following JSON...

{ name:'John Smith', address: { streetAddress: '21 2nd Street', city: 'New York', state: 'NY', postalCode: 10021 }, phoneNumbers: [ '212 555-1111', '212 555-2222' ], additionalInfo: null, remote: false, height: 62.4, 'fico score': ' > 640' }

...maps to the following XML using the default serializer...

<object> <name>John Smith</name> <address> <streetAddress>21 2nd Street</streetAddress> <city>New York</city> <state>NY</state> <postalCode>10021</postalCode> </address> <phoneNumbers> <string>212 555-1111</string> <string>212 555-2222</string> </phoneNumbers> <additionalInfo _type='null'></additionalInfo> <remote>false</remote> <height>62.4</height> <fico_x0020_score> &gt; 640</fico_x0020_score> </object>

An additional "add-json-properties" mode is also provided to prevent loss of JSON data types...

<name _type='string'>John Smith</name> <address _type='object'> <streetAddress _type='string'>21 2nd Street</streetAddress> <city _type='string'>New York</city> <state _type='string'>NY</state> <postalCode _type='number'>10021</postalCode> </address> <phoneNumbers _type='array'> <string>212 555-1111</string> <string>212 555-2222</string> </phoneNumbers> <additionalInfo _type='null'></additionalInfo> <remote _type='boolean'>false</remote> <height _type='number'>62.4</height> <fico_x0020_score _type='string'> &gt; 640</fico_x0020_score> </object>

This serializer provides several serialization options. Typically, one of the predefined DEFAULT serializers will be sufficient. However, custom serializers can be constructed to fine-tune behavior.

If an attribute name contains any non-valid XML element characters, they will be escaped using standard _x####_ notation.

Behavior-specific subclasses

The following direct subclasses are provided for convenience:

• XmlSerializer.Sq - Default serializer, single quotes.
• XmlSerializer.SqReadable - Default serializer, single quotes, whitespace added.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XmlSerializer.Ns Default serializer without namespaces.
static class	XmlSerializer.NsSq Default serializer without namespaces, single quotes.
static class	XmlSerializer.NsSqReadable Default serializer without namespaces, single quotes, with whitespace.
static class	XmlSerializer.Sq Default serializer, single quotes.
static class	XmlSerializer.SqReadable Default serializer, single quotes, whitespace added.

Field Summary

Fields

Modifier and Type	Field and Description
static XmlSerializer	DEFAULT Default serializer without namespaces.
static XmlSerializer	DEFAULT_NS Default serializer, all default settings.
static XmlSerializer	DEFAULT_NS_SQ Default serializer, single quotes.
static XmlSerializer	DEFAULT_NS_SQ_READABLE Default serializer, single quotes, whitespace added.
static XmlSerializer	DEFAULT_SQ Default serializer without namespaces, with single quotes.
static XmlSerializer	DEFAULT_SQ_READABLE Default serializer without namespaces, with single quotes, whitespace added.
static String	XML_addBeanTypeProperties Configuration property: Add "_type" properties when needed.
static String	XML_addNamespaceUrisToRoot Configuration property: Add namespace URLs to the root element.
static String	XML_autoDetectNamespaces Configuration property: Auto-detect namespace usage.
static String	XML_defaultNamespace Configuration property: Default namespace.
static String	XML_enableNamespaces Configuration property: Enable support for XML namespaces.
static String	XML_namespaces Configuration property: Default namespaces.
static String	XML_xsNamespace Configuration property: XMLSchema namespace.

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

SERIALIZER_abridged, SERIALIZER_addBeanTypeProperties, SERIALIZER_detectRecursions, SERIALIZER_ignoreRecursions, SERIALIZER_initialDepth, SERIALIZER_listener, SERIALIZER_maxDepth, SERIALIZER_maxIndent, SERIALIZER_quoteChar, SERIALIZER_sortCollections, SERIALIZER_sortMaps, SERIALIZER_trimEmptyCollections, SERIALIZER_trimEmptyMaps, SERIALIZER_trimNullProperties, SERIALIZER_trimStrings, SERIALIZER_uriContext, SERIALIZER_uriRelativity, SERIALIZER_uriResolution, SERIALIZER_useWhitespace

Fields inherited from class org.apache.juneau.BeanContext

BEAN_beanClassVisibility, BEAN_beanConstructorVisibility, BEAN_beanDictionary, BEAN_beanDictionary_add, BEAN_beanDictionary_remove, BEAN_beanFieldVisibility, BEAN_beanFilters, BEAN_beanFilters_add, BEAN_beanFilters_remove, BEAN_beanMapPutReturnsOldValue, BEAN_beanMethodVisibility, BEAN_beansRequireDefaultConstructor, BEAN_beansRequireSerializable, BEAN_beansRequireSettersForGetters, BEAN_beansRequireSomeProperties, BEAN_beanTypePropertyName, BEAN_debug, BEAN_excludeProperties, BEAN_ignoreInvocationExceptionsOnGetters, BEAN_ignoreInvocationExceptionsOnSetters, BEAN_ignorePropertiesWithoutSetters, BEAN_ignoreUnknownBeanProperties, BEAN_ignoreUnknownNullBeanProperties, BEAN_implClasses, BEAN_includeProperties, BEAN_locale, BEAN_mediaType, BEAN_notBeanClasses, BEAN_notBeanClasses_add, BEAN_notBeanClasses_remove, BEAN_notBeanPackages, BEAN_notBeanPackages_add, BEAN_notBeanPackages_remove, BEAN_pojoSwaps, BEAN_pojoSwaps_add, BEAN_pojoSwaps_remove, BEAN_propertyNamer, BEAN_sortProperties, BEAN_timeZone, BEAN_useInterfaceProxies, BEAN_useJavaBeanIntrospector, DEFAULT_SORTED

Constructor Summary

Constructors

Constructor and Description
XmlSerializer(PropertyStore ps) Constructor.
XmlSerializer(PropertyStore ps, String produces, String... accept) Constructor.

Method Summary

Modifier and Type	Method and Description
ObjectMap	asMap() Returns the properties defined on this bean context as a simple map for debugging purposes.
XmlSerializerBuilder	builder() Creates a builder from this context object.
static XmlSerializerBuilder	create() Instantiates a new clean-slate XmlSerializerBuilder object.
WriterSerializerSession	createSession(SerializerSessionArgs args) Create the session object used for actual serialization of objects.
XmlSerializer	getSchemaSerializer() Returns the schema serializer based on the settings of this serializer.

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

isWriterSerializer, println, serialize, toString, toStringObject

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

createDefaultSessionArgs, createSession, getMediaTypes, getResponseContentType, serialize

Methods inherited from class org.apache.juneau.BeanContext

_class, createBeanSession, createBeanSession, createDefaultBeanSessionArgs, createSession, createSession, dumpCacheStats, getBeanMeta, getBeanRegistry, getBeanTypePropertyName, getClassMeta, getClassMeta, getClassMetaForObject, getExcludeProperties, getImplClassConstructor, getIncludeProperties, hasSameCache, isBean, isNotABean, newInstance, newInstance, newInstanceFromOuter, object, resolveClassMeta, string

Methods inherited from class org.apache.juneau.Context

equals, getArrayProperty, getArrayProperty, getBooleanProperty, getClassArrayProperty, getClassArrayProperty, getClassArrayProperty, getClassListProperty, getClassListProperty, getClassMapProperty, getClassMapProperty, getClassProperty, getClassSetProperty, getClassSetProperty, getInstanceArrayProperty, getInstanceArrayProperty, getInstanceArrayProperty, getInstanceProperty, getInstanceProperty, getInstanceProperty, getIntegerProperty, getListProperty, getListProperty, getLongProperty, getMapProperty, getProperty, getProperty, getPropertyKeys, getPropertyStore, getSetProperty, getSetProperty, getStringProperty, hashCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

XML_addBeanTypeProperties

public static final String XML_addBeanTypeProperties

Configuration property: Add "_type" properties when needed.

Property:

• Name: "XmlSerializer.addBeanTypeProperties.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.addBeanTypeProperties(boolean)

Description:

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

When present, this value overrides the Serializer.SERIALIZER_addBeanTypeProperties setting and is provided to customize the behavior of specific serializers in a SerializerGroup.

See Also:

Constant Field Values

XML_addNamespaceUrisToRoot

public static final String XML_addNamespaceUrisToRoot

Configuration property: Add namespace URLs to the root element.

Property:

• Name: "XmlSerializer.addNamespaceUrisToRoot.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.addNamespaceUrisToRoot(boolean)
  • XmlSerializerBuilder.addNamespaceUrisToRoot()

Description:

Use this setting to add xmlns:x attributes to the root element for the default and all mapped namespaces.

This setting is ignored if XML_enableNamespaces is not enabled.

See Also:

• org.apache.juneau.xml > Namespaces

See Also:

Constant Field Values

XML_autoDetectNamespaces

public static final String XML_autoDetectNamespaces

Configuration property: Auto-detect namespace usage.

Property:

• Name: "XmlSerializer.autoDetectNamespaces.b"
• Data type: Boolean
• Default: true
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.autoDetectNamespaces(boolean)

Description:

Detect namespace usage before serialization.

Used in conjunction with XML_addNamespaceUrisToRoot to reduce the list of namespace URLs appended to the root element to only those that will be used in the resulting document.

If enabled, then the data structure will first be crawled looking for namespaces that will be encountered before the root element is serialized.

This setting is ignored if XML_enableNamespaces is not enabled.

Notes:

• Auto-detection of namespaces can be costly performance-wise.
  In high-performance environments, it's recommended that namespace detection be disabled, and that namespaces be manually defined through the XML_namespaces property.

See Also:

• org.apache.juneau.xml > Namespaces

See Also:

Constant Field Values

XML_defaultNamespace

public static final String XML_defaultNamespace

Configuration property: Default namespace.

Property:

• Name: "XmlSerializer.defaultNamespace.s"
• Data type: String (Namespace)
• Default: "juneau: http://www.apache.org/2013/Juneau"
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.defaultNamespace(String)

Description:

Specifies the default namespace URI for this document.

See Also:

• org.apache.juneau.xml > Namespaces

See Also:

Constant Field Values

XML_enableNamespaces

public static final String XML_enableNamespaces

Configuration property: Enable support for XML namespaces.

Property:

• Name: "XmlSerializer.enableNamespaces.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.enableNamespaces(boolean)

Description:

If not enabled, XML output will not contain any namespaces regardless of any other settings.

See Also:

• org.apache.juneau.xml > Namespaces

See Also:

Constant Field Values

XML_namespaces

public static final String XML_namespaces

Configuration property: Default namespaces.

Property:

• Name: "XmlSerializer.namespaces.ls"
• Data type: Set<String> (Namespace)
• Default: empty set
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.defaultNamespace(String)

Description:

The default list of namespaces associated with this serializer.

See Also:

• org.apache.juneau.xml > Namespaces

See Also:

Constant Field Values

XML_xsNamespace

public static final String XML_xsNamespace

Configuration property: XMLSchema namespace.

Property:

• Name: "XmlSerializer.xsNamespace.s"
• Data type: String (Namespace)
• Default: "xs: http://www.w3.org/2001/XMLSchema"
• Session-overridable: true
• Methods:
  • XmlSerializerBuilder.xsNamespace(Namespace)

Description:

Specifies the namespace for the XMLSchema namespace, used by the schema generated by the XmlSchemaSerializer class.

See Also:

• org.apache.juneau.xml > Namespaces

See Also:

Constant Field Values

DEFAULT

public static final XmlSerializer DEFAULT

Default serializer without namespaces.

DEFAULT_SQ

public static final XmlSerializer DEFAULT_SQ

Default serializer without namespaces, with single quotes.

DEFAULT_SQ_READABLE

public static final XmlSerializer DEFAULT_SQ_READABLE

Default serializer without namespaces, with single quotes, whitespace added.

DEFAULT_NS

public static final XmlSerializer DEFAULT_NS

Default serializer, all default settings.

DEFAULT_NS_SQ

public static final XmlSerializer DEFAULT_NS_SQ

Default serializer, single quotes.

DEFAULT_NS_SQ_READABLE

public static final XmlSerializer DEFAULT_NS_SQ_READABLE

Default serializer, single quotes, whitespace added.

Constructor Detail

XmlSerializer

public XmlSerializer(PropertyStore ps)

Constructor.

Parameters:

ps - The property store containing all the settings for this object.

XmlSerializer

public XmlSerializer(PropertyStore ps,
                     String produces,
                     String... accept)

Constructor.

Parameters:

ps - The property store containing all the settings for this object.

produces - The media type that this serializer produces.

accept - The accept media types that the serializer can handle.

Can contain meta-characters per the media-type specification of RFC2616/14.1

If empty, then assumes the only media type supported is produces.

For example, if this serializer produces "application/json" but should handle media types of "application/json" and "text/json", then the arguments should be:

super(ps, "application/json", "application/json", "text/json");

...or...

super(ps, "application/json", "*/json");

Method Detail

builder

public XmlSerializerBuilder builder()

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:

builder in class Serializer

Returns:

A new ContextBuilder object.

create

public static XmlSerializerBuilder create()

Instantiates a new clean-slate XmlSerializerBuilder object.

This is equivalent to simply calling new XmlSerializerBuilder().

Note that this method creates a builder initialized to all default settings, whereas builder() copies the settings of the object called on.

Returns:

A new XmlSerializerBuilder object.

getSchemaSerializer

public XmlSerializer getSchemaSerializer()

Returns the schema serializer based on the settings of this serializer.

Returns:

The schema serializer.

createSession

public WriterSerializerSession createSession(SerializerSessionArgs args)

Description copied from class: Serializer

Create the session object used for actual serialization of objects.

Specified by:

createSession in class WriterSerializer

Parameters:

args - Runtime arguments. These specify session-level information such as locale and URI context. It also include session-level properties that override the properties defined on the bean and serializer contexts.

Returns:

The new session object.

asMap

public ObjectMap asMap()

Description copied from class: Context

Returns the properties defined on this bean context as a simple map for debugging purposes.

Overrides:

asMap in class Serializer

Returns:

A new map containing the properties defined on this context.