XStreamMarshaller (Spring Framework 3.2.4.RELEASE API)

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 converters and supportedClasses properties 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 is compatible with XStream 1.3 and 1.4.

Since:

3.0

Author:

Peter Meijer, Arjen Poutsma

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

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

Constructor Summary

Constructors
Constructor and Description

XStreamMarshaller()

Constructors
Constructor and Description
`XStreamMarshaller()`

Method Summary

Methods
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 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 of the given `XStream`.
`com.thoughtworks.xstream.XStream`	`getXStream()` Return the XStream instance used by this marshaller.
`protected void`	`marshalDomNode(Object graph, Node node)` Abstract template method for marshalling the given object graph to a DOM `Node`.
`protected void`	`marshalOutputStream(Object graph, OutputStream outputStream)` Abstract template method for marshalling the given object graph to a `OutputStream`.
`protected void`	`marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)` Abstract template method for marshalling the given object graph to a SAX `ContentHandler`.
`protected void`	`marshalWriter(Object graph, Writer writer)` Abstract template method for marshalling the given object graph to a `Writer`.
`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 an alias/type map, consisting of String aliases mapped to classes.
`void`	`setAliasesByType(Map<String,?> aliases)` Set the aliases by type map, consisting of String aliases mapped to classes.
`void`	`setAnnotatedClass(Class<?> annotatedClass)` Deprecated. in favor of `setAnnotatedClasses(java.lang.Class<?>...)` with varargs
`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`	`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> aliases)` Set a 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`	`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(com.thoughtworks.xstream.io.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)` Indicates 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`.
`protected Object`	`unmarshalInputStream(InputStream inputStream)` Abstract template method for unmarshalling from a given `InputStream`.
`protected Object`	`unmarshalReader(Reader reader)` Abstract template method for unmarshalling from a given `Reader`.
`protected Object`	`unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource)` Abstract template method for unmarshalling using a given SAX `XMLReader` and `InputSource`.
`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
createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource, unmarshalStreamSource

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
  - getXStream
```
public com.thoughtworks.xstream.XStream getXStream()
```
    Return the XStream instance used by this marshaller.
    NOTE: While this method can be overridden in Spring 3.x, it wasn't originally meant to be. As of Spring 4.0, it will be marked as final, with all of XStream 1.4's configurable strategies to be exposed on XStreamMarshaller itself.
  - setMode
```
public void setMode(int mode)
```
    Set the XStream mode.
    
    See Also:
    XStream.XPATH_REFERENCES, XStream.ID_REFERENCES, XStream.NO_REFERENCES
  - 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
  - setAliases
```
public void setAliases(Map<String,?> aliases)
                throws ClassNotFoundException
```
    Set an alias/type map, consisting of String aliases mapped to classes.
    Keys are aliases; values are either Class objects or String class names.
    
    Throws:
    
    ClassNotFoundException
    See Also:
    XStream.alias(String, Class)
  - setAliasesByType
```
public void setAliasesByType(Map<String,?> aliases)
                      throws ClassNotFoundException
```
    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 objects or String class names.
    
    Throws:
    
    ClassNotFoundException
    See Also:
    XStream.aliasType(String, Class)
  - setFieldAliases
```
public void setFieldAliases(Map<String,String> aliases)
                     throws ClassNotFoundException,
                            NoSuchFieldException
```
    Set a field alias/type map, consisting of field names.
    
    Throws:
    
    ClassNotFoundException
    
    NoSuchFieldException
    See Also:
    XStream.aliasField(String, Class, String)
  - setUseAttributeForTypes
```
public void setUseAttributeForTypes(Class<?>... types)
```
    Set types to use XML attributes for.
    
    See Also:
    XStream.useAttributeFor(Class)
  - setUseAttributeFor
```
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.
  - 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)
  - setAnnotatedClass
```
@Deprecated
public void setAnnotatedClass(Class<?> annotatedClass)
```
    Deprecated. in favor of setAnnotatedClasses(java.lang.Class<?>...) with varargs
    
    Set the classes for which mappings will be read from class-level annotation metadata.
    
    See Also:
    XStream.processAnnotations(Class)
  - 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)
  - setStreamDriver
```
public void setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver)
```
    Set the XStream hierarchical stream driver to be used with stream readers and writers.
  - setEncoding
```
public void setEncoding(String encoding)
```
    Set the encoding to be used for stream access.
    
    See Also:
    DEFAULT_ENCODING
  - 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 final void afterPropertiesSet()
                              throws Exception
```
    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
    
    Throws:
    
    Exception - in the event of misconfiguration (such as failure to set an essential property) or if initialization fails.
  - customizeXStream
```
protected void customizeXStream(com.thoughtworks.xstream.XStream xstream)
```
    Template to allow for customizing of the given XStream.
    The default implementation is empty.
    
    Parameters:
    xstream - the XStream instance
  - supports
```
public boolean supports(Class<?> clazz)
```
    Description copied from interface: Marshaller
    
    Indicates 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
  - marshalOutputStream
```
protected 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
  - 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
  - marshalWriter
```
protected 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
  - 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
  - unmarshalInputStream
```
protected 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
  - unmarshalReader
```
protected 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
  - 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
  - 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 occured
    marshalling - indicates whether the exception occurs during marshalling (true), or unmarshalling (false)
    
    Returns:
    the corresponding XmlMappingException

Class XStreamMarshaller

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_ENCODING

Constructor Detail

XStreamMarshaller

Method Detail

getXStream

setMode

setConverters

setAliases

setAliasesByType

setFieldAliases

setUseAttributeForTypes

setUseAttributeFor

setImplicitCollections

setOmittedFields

setAnnotatedClass

setAnnotatedClasses

setAutodetectAnnotations

setStreamDriver

setEncoding

setSupportedClasses

setBeanClassLoader

afterPropertiesSet

customizeXStream

supports

marshalDomNode

marshalXmlEventWriter

marshalXmlStreamWriter

marshalOutputStream

marshalSaxHandlers

marshalWriter

unmarshalDomNode

unmarshalXmlEventReader

unmarshalXmlStreamReader

unmarshalInputStream

unmarshalReader

unmarshalSaxReader

convertXStreamException