public class

XStreamMarshaller

extends AbstractMarshaller
implements BeanClassLoaderAware InitializingBean
java.lang.Object
   ↳ org.springframework.oxm.support.AbstractMarshaller
     ↳ org.springframework.oxm.xstream.XStreamMarshaller

Class Overview

Implementation of the Marshaller interface for XStream.

By default, XStream does not require any further configuration, though class aliases can be used to have more control over the behavior of XStream.

Due to XStream's API, it is required to set the encoding used for writing to OutputStreams. It defaults to UTF-8.

NOTE: XStream is an XML serialization library, not a data binding library. Therefore, it has limited namespace support. As such, it is rather unsuitable for usage within Web services.

See Also

Summary

Constants
String DEFAULT_ENCODING The default encoding used for stream access: UTF-8.
[Expand]
Inherited Fields
From class org.springframework.oxm.support.AbstractMarshaller
Public Constructors
XStreamMarshaller()
Public Methods
final void afterPropertiesSet()
Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
XStream getXStream()
Returns the XStream instance used by this marshaller.
void setAliases(Map<String, ?> aliases)
Sets an alias/type map, consisting of string aliases mapped to classes.
void setAliasesByType(Map<String, ?> aliases)
Sets the aliases by type map, consisting of string aliases mapped to classes.
void setAnnotatedClass(Class<?> annotatedClass)
Set the classes for which mappings will be read from class-level JDK 1.5+ annotation metadata.
void setAnnotatedClasses(Class[]<?> annotatedClasses)
Set annotated classes for which aliases will be read from class-level JDK 1.5+ annotation metadata.
void setAutodetectAnnotations(boolean autodetectAnnotations)
Set the auto-detection mode of XStream.
void setBeanClassLoader(ClassLoader classLoader)
Callback that supplies the bean class loader to a bean instance.
void setConverters(ConverterMatcher[] converters)
Set the Converters or SingleValueConverters to be registered with the XStream instance.
void setEncoding(String encoding)
Set the encoding to be used for stream access.
void setFieldAliases(Map<String, String> aliases)
Sets a field alias/type map, consiting of field names
void setImplicitCollections(Map<Class<?>, String> implicitCollections)
Specify implicit collection fields, as a Map consisting of Class instances mapped to comma separated collection field names.
void setMode(int mode)
Set the XStream mode.
void setOmittedFields(Map<Class<?>, String> omittedFields)
Specify omitted fields, as a Map consisting of Class instances mapped to comma separated field names.
void setStreamDriver(HierarchicalStreamDriver streamDriver)
Set the XStream hierarchical stream driver to be used with stream readers and writers.
void setSupportedClasses(Class[] supportedClasses)
Set the classes supported by this marshaller.
void setUseAttributeFor(Map<?, ?> attributes)
Set the types to use XML attributes for.
void setUseAttributeForTypes(Class[] types)
Set types to use XML attributes for.
boolean supports(Class clazz)
Protected Methods
XmlMappingException convertXStreamException(Exception ex, boolean marshalling)
Convert the given XStream exception to an appropriate exception from the org.springframework.oxm hierarchy.
void customizeXStream(XStream xstream)
Template to allow for customizing of the given XStream.
void marshalDomNode(Object graph, Node node)
Abstract template method for marshalling the given object graph to a DOM Node.
void marshalOutputStream(Object graph, OutputStream outputStream)
Abstract template method for marshalling the given object graph to a OutputStream.
void marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)
Abstract template method for marshalling the given object graph to a SAX ContentHandler.
void marshalWriter(Object graph, Writer writer)
Abstract template method for marshalling the given object graph to a Writer.
void marshalXmlEventWriter(Object graph, XMLEventWriter eventWriter)
Abstract template method for marshalling the given object to a StAX XMLEventWriter.
void marshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter)
Abstract template method for marshalling the given object to a StAX XMLStreamWriter.
Object unmarshalDomNode(Node node)
Abstract template method for unmarshalling from a given DOM Node.
Object unmarshalInputStream(InputStream inputStream)
Abstract template method for unmarshalling from a given InputStream.
Object unmarshalReader(Reader reader)
Abstract template method for unmarshalling from a given Reader.
Object unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource)
Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.
Object unmarshalXmlEventReader(XMLEventReader eventReader)
Abstract template method for unmarshalling from a given Stax XMLEventReader.
Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
Abstract template method for unmarshalling from a given Stax XMLStreamReader.
[Expand]
Inherited Methods
From class org.springframework.oxm.support.AbstractMarshaller
From class java.lang.Object
From interface org.springframework.beans.factory.BeanClassLoaderAware
From interface org.springframework.beans.factory.InitializingBean
From interface org.springframework.oxm.Marshaller
From interface org.springframework.oxm.Unmarshaller

Constants

public static final String DEFAULT_ENCODING

The default encoding used for stream access: UTF-8.

Constant Value: "UTF-8"

Public Constructors

public XStreamMarshaller ()

Public Methods

public final void afterPropertiesSet ()

Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

Throws
Exception

public XStream getXStream ()

Returns the XStream instance used by this marshaller.

public void setAliases (Map<String, ?> aliases)

Sets an alias/type map, consisting of string aliases mapped to classes. Keys are aliases; values are either Class instances, or String class names.

Throws
ClassNotFoundException
See Also
  • XStream#alias(String, Class)

public void setAliasesByType (Map<String, ?> aliases)

Sets the aliases by type map, consisting of string aliases mapped to classes. Any class that is assignable to this type will be aliased to the same name. Keys are aliases; values are either Class instances, or String class names.

Throws
ClassNotFoundException
See Also
  • XStream#aliasType(String, Class)

public void setAnnotatedClass (Class<?> annotatedClass)

Set the classes for which mappings will be read from class-level JDK 1.5+ annotation metadata.

See Also
  • XStream#processAnnotations(Class)

public void setAnnotatedClasses (Class[]<?> annotatedClasses)

Set annotated classes for which aliases will be read from class-level JDK 1.5+ annotation metadata.

See Also
  • XStream#processAnnotations(Class[])

public void setAutodetectAnnotations (boolean autodetectAnnotations)

Set the auto-detection mode of XStream.

Note that auto-detection implies that the XStream is configured while it is processing the XML steams, and thus introduces a potential concurrency problem.

See Also
  • XStream#autodetectAnnotations(boolean)

public void setBeanClassLoader (ClassLoader classLoader)

Callback that supplies the bean class loader to a bean instance.

Invoked after the population of normal bean properties but before an initialization callback such as InitializingBean's afterPropertiesSet() method or a custom init-method.

Parameters
classLoader the owning class loader; may be null in which case a default ClassLoader must be used, for example the ClassLoader obtained via getDefaultClassLoader()

public void setConverters (ConverterMatcher[] converters)

Set the Converters or SingleValueConverters to be registered with the XStream instance.

See Also
  • Converter
  • SingleValueConverter

public void setEncoding (String encoding)

Set the encoding to be used for stream access.

See Also

public void setFieldAliases (Map<String, String> aliases)

Sets a field alias/type map, consiting of field names

Throws
ClassNotFoundException
NoSuchFieldException
ClassNotFoundException
NoSuchFieldException
See Also
  • XStream#aliasField(String, Class, String)

public void setImplicitCollections (Map<Class<?>, String> implicitCollections)

Specify implicit collection fields, as a Map consisting of Class instances mapped to comma separated collection field names.

See Also
  • XStream#addImplicitCollection(Class, String)

public void setMode (int mode)

Set the XStream mode.

See Also
  • XStream#XPATH_REFERENCES
  • XStream#ID_REFERENCES
  • XStream#NO_REFERENCES

public void setOmittedFields (Map<Class<?>, String> omittedFields)

Specify omitted fields, as a Map consisting of Class instances mapped to comma separated field names.

See Also
  • XStream#omitField(Class, String)

public void setStreamDriver (HierarchicalStreamDriver streamDriver)

Set the XStream hierarchical stream driver to be used with stream readers and writers.

public void setSupportedClasses (Class[] supportedClasses)

Set the classes supported by this marshaller.

If this property is empty (the default), all classes are supported.

See Also

public void setUseAttributeFor (Map<?, ?> attributes)

Set the types to use XML attributes for. The given map can contain either <String, Class> pairs, in which case XStream#useAttributeFor(String, Class) is called. Alternatively, the map can contain <Class, String> or <Class, List<String>> pairs, which results in XStream#useAttributeFor(Class, String) calls.

public void setUseAttributeForTypes (Class[] types)

Set types to use XML attributes for.

See Also
  • XStream#useAttributeFor(Class)

public boolean supports (Class clazz)

Protected Methods

protected XmlMappingException convertXStreamException (Exception ex, boolean marshalling)

Convert the given XStream exception to an appropriate exception from the org.springframework.oxm hierarchy.

A boolean flag is used to indicate whether this exception occurs during marshalling or unmarshalling, since XStream itself does not make this distinction in its exception hierarchy.

Parameters
ex XStream exception that occured
marshalling indicates whether the exception occurs during marshalling (true), or unmarshalling (false)
Returns
  • the corresponding XmlMappingException

protected void customizeXStream (XStream xstream)

Template to allow for customizing of the given XStream.

Default implementation is empty.

Parameters
xstream the XStream instance

protected void marshalDomNode (Object graph, Node node)

Abstract template method for marshalling the given object graph to a DOM Node.

In practice, node is be a Document node, a DocumentFragment node, or a Element node. In other words, a node that accepts children.

Parameters
graph the root of the object graph to marshal
node the DOM node that will contain the result tree
Throws
XmlMappingException

protected void marshalOutputStream (Object graph, OutputStream outputStream)

Abstract template method for marshalling the given object graph to a OutputStream.

Parameters
graph the root of the object graph to marshal
outputStream the OutputStream to write to
Throws
IOException
XmlMappingException

protected void marshalSaxHandlers (Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)

Abstract template method for marshalling the given object graph to a SAX ContentHandler.

Parameters
graph the root of the object graph to marshal
contentHandler the SAX ContentHandler
lexicalHandler the SAX2 LexicalHandler. Can be null.
Throws
XmlMappingException

protected void marshalWriter (Object graph, Writer writer)

Abstract template method for marshalling the given object graph to a Writer.

Parameters
graph the root of the object graph to marshal
writer the Writer to write to
Throws
IOException
XmlMappingException

protected void marshalXmlEventWriter (Object graph, XMLEventWriter eventWriter)

Abstract template method for marshalling the given object to a StAX XMLEventWriter.

Parameters
graph the root of the object graph to marshal
eventWriter the XMLEventWriter to write to
Throws
XmlMappingException

protected void marshalXmlStreamWriter (Object graph, XMLStreamWriter streamWriter)

Abstract template method for marshalling the given object to a StAX XMLStreamWriter.

Parameters
graph the root of the object graph to marshal
streamWriter the XMLStreamWriter to write to
Throws
XmlMappingException

protected Object unmarshalDomNode (Node node)

Abstract template method for unmarshalling from a given DOM Node.

Parameters
node the DOM node that contains the objects to be unmarshalled
Returns
  • the object graph
Throws
XmlMappingException

protected Object unmarshalInputStream (InputStream inputStream)

Abstract template method for unmarshalling from a given InputStream.

Parameters
inputStream the InputStreamStream to read from
Returns
  • the object graph
Throws
IOException
XmlMappingException

protected Object unmarshalReader (Reader reader)

Abstract template method for unmarshalling from a given Reader.

Parameters
reader the Reader to read from
Returns
  • the object graph
Throws
IOException
XmlMappingException

protected Object unmarshalSaxReader (XMLReader xmlReader, InputSource inputSource)

Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.

Parameters
xmlReader the SAX XMLReader to parse with
inputSource the input source to parse from
Returns
  • the object graph
Throws
IOException
XmlMappingException

protected Object unmarshalXmlEventReader (XMLEventReader eventReader)

Abstract template method for unmarshalling from a given Stax XMLEventReader.

Parameters
eventReader the XMLEventReader to read from
Returns
  • the object graph
Throws
XmlMappingException

protected Object unmarshalXmlStreamReader (XMLStreamReader streamReader)

Abstract template method for unmarshalling from a given Stax XMLStreamReader.

Parameters
streamReader the XMLStreamReader to read from
Returns
  • the object graph
Throws
XmlMappingException