org.springframework.oxm.xstream

Class XStreamMarshaller

java.lang.Object

org.springframework.oxm.support.AbstractMarshaller

org.springframework.oxm.xstream.XStreamMarshaller

All Implemented Interfaces:

Aware, BeanClassLoaderAware, InitializingBean, Marshaller, Unmarshaller

public class XStreamMarshaller
extends AbstractMarshaller
implements InitializingBean, BeanClassLoaderAware

Implementation of the Marshaller interface for XStream.

By default, XStream does not require any further configuration and can (un)marshal any class on the classpath. As such, it is not recommended to use the XStreamMarshaller to unmarshal XML from external sources (i.e. the Web), as this can result in security vulnerabilities. If you do use the XStreamMarshaller to unmarshal external XML, set the supportedClasses and converters properties (possibly using a CatchAllConverter) or override the customizeXStream(XStream) method to make sure it only accepts the classes you want it to support.

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.

This marshaller requires XStream 1.4.5 or higher, as of Spring 4.3. Note that XStream construction has been reworked in 4.0, with the stream driver and the class loader getting passed into XStream itself now.

Since:

3.0

Author:

Peter Meijer, Arjen Poutsma, Juergen Hoeller

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_ENCODING The default encoding used for stream access: UTF-8.

Fields inherited from class org.springframework.oxm.support.AbstractMarshaller

logger

Constructor Summary

Constructors

Constructor and Description
XStreamMarshaller()

Method Summary

Modifier and Type	Method and Description
void	afterPropertiesSet() Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
protected com.thoughtworks.xstream.XStream	buildXStream() Build the native XStream delegate to be used by this marshaller, delegating to constructXStream(), configureXStream(com.thoughtworks.xstream.XStream) and customizeXStream(com.thoughtworks.xstream.XStream).
protected void	configureXStream(com.thoughtworks.xstream.XStream xstream) Configure the XStream instance with this marshaller's bean properties.
protected com.thoughtworks.xstream.XStream	constructXStream() Construct an XStream instance, either using one of the standard constructors or creating a custom subclass.
protected XmlMappingException	convertXStreamException(Exception ex, boolean marshalling) Convert the given XStream exception to an appropriate exception from the org.springframework.oxm hierarchy.
protected void	customizeXStream(com.thoughtworks.xstream.XStream xstream) Template to allow for customizing the given XStream.
protected String	getDefaultEncoding() Determine the default encoding to use for marshalling or unmarshalling from a byte stream, or null if none.
com.thoughtworks.xstream.XStream	getXStream() Return the native XStream delegate used by this marshaller.
protected 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	marshalOutputStream(Object graph, OutputStream outputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder)
protected 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	marshalWriter(Object graph, Writer writer, com.thoughtworks.xstream.converters.DataHolder dataHolder)
protected void	marshalXmlEventWriter(Object graph, XMLEventWriter eventWriter) Abstract template method for marshalling the given object to a StAX XMLEventWriter.
protected void	marshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter) Abstract template method for marshalling the given object to a StAX XMLStreamWriter.
void	setAliases(Map<String,?> aliases) Set the alias/type map, consisting of string aliases mapped to classes.
void	setAliasesByType(Map<String,?> aliasesByType) Set the aliases by type map, consisting of string aliases mapped to classes.
void	setAnnotatedClasses(Class<?>... annotatedClasses) Set annotated classes for which aliases will be read from class-level annotation metadata.
void	setAutodetectAnnotations(boolean autodetectAnnotations) Activate XStream's autodetection mode.
void	setBeanClassLoader(ClassLoader classLoader) Callback that supplies the bean class loader to a bean instance.
void	setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup converterLookup) Set a custom XStream ConverterLookup to use.
void	setConverterRegistry(com.thoughtworks.xstream.converters.ConverterRegistry converterRegistry) Set a custom XStream ConverterRegistry to use.
void	setConverters(com.thoughtworks.xstream.converters.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> fieldAliases) Set the field alias/type map, consisting 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	setMapper(com.thoughtworks.xstream.mapper.Mapper mapper) Set a custom XStream Mapper to use.
void	setMapperWrappers(Class<?>... mapperWrappers) Set one or more custom XStream MapperWrapper classes.
void	setMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy) Set a custom XStream MarshallingStrategy to use.
void	setMode(int mode) Set the XStream mode to use.
void	setNameCoder(com.thoughtworks.xstream.io.naming.NameCoder nameCoder) Set a custom XStream NameCoder to use.
void	setOmittedFields(Map<Class<?>,String> omittedFields) Specify omitted fields, as a Map consisting of Class instances mapped to comma separated field names.
void	setReflectionProvider(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider) Set a custom XStream ReflectionProvider to use.
void	setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver) Set a XStream HierarchicalStreamDriver to be used for readers and writers.
void	setSupportedClasses(Class<?>... supportedClasses) Set the classes supported by this marshaller.
void	setUseAttributeFor(Map<?,?> useAttributeFor) Set the types to use XML attributes for.
void	setUseAttributeForTypes(Class<?>... useAttributeForTypes) Set types to use XML attributes for.
boolean	supports(Class<?> clazz) Indicate whether this marshaller can marshal instances of the supplied type.
protected 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	unmarshalInputStream(InputStream inputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder)
Object	unmarshalReader(Reader reader) Abstract template method for unmarshalling from a given Reader.
Object	unmarshalReader(Reader reader, com.thoughtworks.xstream.converters.DataHolder dataHolder)
protected Object	unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource) Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.
protected Object	unmarshalStreamSource(StreamSource streamSource) Template method for handling StreamSources.
protected Object	unmarshalXmlEventReader(XMLEventReader eventReader) Abstract template method for unmarshalling from a given Stax XMLEventReader.
protected Object	unmarshalXmlStreamReader(XMLStreamReader streamReader) Abstract template method for unmarshalling from a given Stax XMLStreamReader.

Methods inherited from class org.springframework.oxm.support.AbstractMarshaller

buildDocument, createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, isProcessExternalEntities, isSupportDtd, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, setProcessExternalEntities, setSupportDtd, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

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

See Also:

Constant Field Values

Constructor Detail

XStreamMarshaller

public XStreamMarshaller()

Method Detail

setReflectionProvider

public void setReflectionProvider(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)

Set a custom XStream ReflectionProvider to use.

Since:

4.0

setStreamDriver

public void setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver)

Set a XStream HierarchicalStreamDriver to be used for readers and writers.

As of Spring 4.0, this stream driver will also be passed to the XStream constructor and therefore used by streaming-related native API methods themselves.

setMapper

public void setMapper(com.thoughtworks.xstream.mapper.Mapper mapper)

Set a custom XStream Mapper to use.

Since:

4.0

setMapperWrappers

public void setMapperWrappers(Class<?>... mapperWrappers)

Set one or more custom XStream MapperWrapper classes. Each of those classes needs to have a constructor with a single argument of type Mapper or MapperWrapper.

Since:

4.0

setConverterLookup

public void setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup converterLookup)

Set a custom XStream ConverterLookup to use. Also used as ConverterRegistry if the given reference implements it as well.

Since:

4.0

See Also:

DefaultConverterLookup

setConverterRegistry

public void setConverterRegistry(com.thoughtworks.xstream.converters.ConverterRegistry converterRegistry)

Set a custom XStream ConverterRegistry to use.

Since:

4.0

See Also:

setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup), DefaultConverterLookup

setConverters

public void setConverters(com.thoughtworks.xstream.converters.ConverterMatcher... converters)

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

See Also:

Converter, SingleValueConverter

setMarshallingStrategy

public void setMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy)

Set a custom XStream MarshallingStrategy to use.

Since:

4.0

setMode

public void setMode(int mode)

Set the XStream mode to use.

See Also:

XStream.ID_REFERENCES, XStream.NO_REFERENCES

setAliases

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

Set the alias/type map, consisting of string aliases mapped to classes.

Keys are aliases; values are either Class instances, or String class names.

See Also:

XStream.alias(String, Class)

setAliasesByType

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

Set 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.

See Also:

XStream.aliasType(String, Class)

setFieldAliases

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

Set the field alias/type map, consisting of field names.

See Also:

XStream.aliasField(String, Class, String)

setUseAttributeForTypes

public void setUseAttributeForTypes(Class<?>... useAttributeForTypes)

Set types to use XML attributes for.

See Also:

XStream.useAttributeFor(Class)

setUseAttributeFor

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

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.

setImplicitCollections

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)

setOmittedFields

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)

setAnnotatedClasses

public void setAnnotatedClasses(Class<?>... annotatedClasses)

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

See Also:

XStream.processAnnotations(Class[])

setAutodetectAnnotations

public void setAutodetectAnnotations(boolean autodetectAnnotations)

Activate XStream's autodetection mode.

Note: Autodetection implies that the XStream instance is being configured while it is processing the XML streams, and thus introduces a potential concurrency problem.

See Also:

XStream.autodetectAnnotations(boolean)

setEncoding

public void setEncoding(String encoding)

Set the encoding to be used for stream access.

See Also:

DEFAULT_ENCODING

getDefaultEncoding

protected String getDefaultEncoding()

Description copied from class: AbstractMarshaller

Determine the default encoding to use for marshalling or unmarshalling from a byte stream, or null if none.

The default implementation returns null.

Overrides:

getDefaultEncoding in class AbstractMarshaller

setNameCoder

public void setNameCoder(com.thoughtworks.xstream.io.naming.NameCoder nameCoder)

Set a custom XStream NameCoder to use. The default is an XmlFriendlyNameCoder.

Since:

4.0.4

setSupportedClasses

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:

supports(Class)

setBeanClassLoader

public void setBeanClassLoader(ClassLoader classLoader)

Description copied from interface: BeanClassLoaderAware

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 InitializingBean.afterPropertiesSet() method or a custom init-method.

Specified by:

setBeanClassLoader in interface BeanClassLoaderAware

Parameters:

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

afterPropertiesSet

public void afterPropertiesSet()

Description copied from interface: InitializingBean

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.

Specified by:

afterPropertiesSet in interface InitializingBean

buildXStream

protected com.thoughtworks.xstream.XStream buildXStream()

Build the native XStream delegate to be used by this marshaller, delegating to constructXStream(), configureXStream(com.thoughtworks.xstream.XStream) and customizeXStream(com.thoughtworks.xstream.XStream).

constructXStream

protected com.thoughtworks.xstream.XStream constructXStream()

Construct an XStream instance, either using one of the standard constructors or creating a custom subclass.

Returns:

the XStream instance

configureXStream

protected void configureXStream(com.thoughtworks.xstream.XStream xstream)

Configure the XStream instance with this marshaller's bean properties.

Parameters:

xstream - the XStream instance

customizeXStream

protected void customizeXStream(com.thoughtworks.xstream.XStream xstream)

Template to allow for customizing the given XStream.

The default implementation is empty.

Parameters:

xstream - the XStream instance

getXStream

public final com.thoughtworks.xstream.XStream getXStream()

Return the native XStream delegate used by this marshaller.

NOTE: This method has been marked as final as of Spring 4.0. It can be used to access the fully configured XStream for marshalling but not configuration purposes anymore.

supports

public boolean supports(Class<?> clazz)

Description copied from interface: Marshaller

Indicate whether this marshaller can marshal instances of the supplied type.

Specified by:

supports in interface Marshaller

Specified by:

supports in interface Unmarshaller

Parameters:

clazz - the class that this marshaller is being asked if it can marshal

Returns:

true if this marshaller can indeed marshal instances of the supplied class; false otherwise

marshalDomNode

protected void marshalDomNode(Object graph,
                              Node node)
                       throws XmlMappingException

Description copied from class: AbstractMarshaller

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.

Specified by:

marshalDomNode in class AbstractMarshaller

Parameters:

graph - the root of the object graph to marshal

node - the DOM node that will contain the result tree

Throws:

XmlMappingException - if the given object cannot be marshalled to the DOM node

See Also:

Document, DocumentFragment, Element

marshalXmlEventWriter

protected void marshalXmlEventWriter(Object graph,
                                     XMLEventWriter eventWriter)
                              throws XmlMappingException

Description copied from class: AbstractMarshaller

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

Specified by:

marshalXmlEventWriter in class AbstractMarshaller

Parameters:

graph - the root of the object graph to marshal

eventWriter - the XMLEventWriter to write to

Throws:

XmlMappingException - if the given object cannot be marshalled to the DOM node

marshalXmlStreamWriter

protected void marshalXmlStreamWriter(Object graph,
                                      XMLStreamWriter streamWriter)
                               throws XmlMappingException

Description copied from class: AbstractMarshaller

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

Specified by:

marshalXmlStreamWriter in class AbstractMarshaller

Parameters:

graph - the root of the object graph to marshal

streamWriter - the XMLStreamWriter to write to

Throws:

XmlMappingException - if the given object cannot be marshalled to the DOM node

marshalSaxHandlers

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

Description copied from class: AbstractMarshaller

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

Specified by:

marshalSaxHandlers in class AbstractMarshaller

Parameters:

graph - the root of the object graph to marshal

contentHandler - the SAX ContentHandler

lexicalHandler - the SAX2 LexicalHandler. Can be null.

Throws:

XmlMappingException - if the given object cannot be marshalled to the handlers

marshalOutputStream

public void marshalOutputStream(Object graph,
                                OutputStream outputStream)
                         throws XmlMappingException,
                                IOException

Description copied from class: AbstractMarshaller

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

Specified by:

marshalOutputStream in class AbstractMarshaller

Parameters:

graph - the root of the object graph to marshal

outputStream - the OutputStream to write to

Throws:

XmlMappingException - if the given object cannot be marshalled to the writer

IOException - if an I/O exception occurs

marshalOutputStream

public void marshalOutputStream(Object graph,
                                OutputStream outputStream,
                                com.thoughtworks.xstream.converters.DataHolder dataHolder)
                         throws XmlMappingException,
                                IOException

Throws:

XmlMappingException

IOException

marshalWriter

public void marshalWriter(Object graph,
                          Writer writer)
                   throws XmlMappingException,
                          IOException

Description copied from class: AbstractMarshaller

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

Specified by:

marshalWriter in class AbstractMarshaller

Parameters:

graph - the root of the object graph to marshal

writer - the Writer to write to

Throws:

XmlMappingException - if the given object cannot be marshalled to the writer

IOException - if an I/O exception occurs

marshalWriter

public void marshalWriter(Object graph,
                          Writer writer,
                          com.thoughtworks.xstream.converters.DataHolder dataHolder)
                   throws XmlMappingException,
                          IOException

Throws:

XmlMappingException

IOException

unmarshalStreamSource

protected Object unmarshalStreamSource(StreamSource streamSource)
                                throws XmlMappingException,
                                       IOException

Description copied from class: AbstractMarshaller

Template method for handling StreamSources.

This implementation delegates to unmarshalInputStream or unmarshalReader.

Overrides:

unmarshalStreamSource in class AbstractMarshaller

Parameters:

streamSource - the StreamSource

Returns:

the object graph

Throws:

XmlMappingException - if the given source cannot be mapped to an object

IOException - if an I/O exception occurs

unmarshalDomNode

protected Object unmarshalDomNode(Node node)
                           throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given DOM Node.

Specified by:

unmarshalDomNode in class AbstractMarshaller

Parameters:

node - the DOM node that contains the objects to be unmarshalled

Returns:

the object graph

Throws:

XmlMappingException - if the given DOM node cannot be mapped to an object

unmarshalXmlEventReader

protected Object unmarshalXmlEventReader(XMLEventReader eventReader)
                                  throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given Stax XMLEventReader.

Specified by:

unmarshalXmlEventReader in class AbstractMarshaller

Parameters:

eventReader - the XMLEventReader to read from

Returns:

the object graph

Throws:

XmlMappingException - if the given event reader cannot be converted to an object

unmarshalXmlStreamReader

protected Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
                                   throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given Stax XMLStreamReader.

Specified by:

unmarshalXmlStreamReader in class AbstractMarshaller

Parameters:

streamReader - the XMLStreamReader to read from

Returns:

the object graph

Throws:

XmlMappingException - if the given stream reader cannot be converted to an object

unmarshalSaxReader

protected Object unmarshalSaxReader(XMLReader xmlReader,
                                    InputSource inputSource)
                             throws XmlMappingException,
                                    IOException

Description copied from class: AbstractMarshaller

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

Specified by:

unmarshalSaxReader in class AbstractMarshaller

Parameters:

xmlReader - the SAX XMLReader to parse with

inputSource - the input source to parse from

Returns:

the object graph

Throws:

XmlMappingException - if the given reader and input source cannot be converted to an object

IOException - if an I/O exception occurs

unmarshalInputStream

public Object unmarshalInputStream(InputStream inputStream)
                            throws XmlMappingException,
                                   IOException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given InputStream.

Specified by:

unmarshalInputStream in class AbstractMarshaller

Parameters:

inputStream - the InputStreamStream to read from

Returns:

the object graph

Throws:

XmlMappingException - if the given stream cannot be converted to an object

IOException - if an I/O exception occurs

unmarshalInputStream

public Object unmarshalInputStream(InputStream inputStream,
                                   com.thoughtworks.xstream.converters.DataHolder dataHolder)
                            throws XmlMappingException,
                                   IOException

Throws:

XmlMappingException

IOException

unmarshalReader

public Object unmarshalReader(Reader reader)
                       throws XmlMappingException,
                              IOException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given Reader.

Specified by:

unmarshalReader in class AbstractMarshaller

Parameters:

reader - the Reader to read from

Returns:

the object graph

Throws:

XmlMappingException - if the given reader cannot be converted to an object

IOException - if an I/O exception occurs

unmarshalReader

public Object unmarshalReader(Reader reader,
                              com.thoughtworks.xstream.converters.DataHolder dataHolder)
                       throws XmlMappingException,
                              IOException

Throws:

XmlMappingException

IOException

convertXStreamException

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 occurred

marshalling - indicates whether the exception occurs during marshalling (true), or unmarshalling (false)

Returns:

the corresponding XmlMappingException