## 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, 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.

Since:
  3.0
Author:
  Peter Meijer, Arjen Poutsma
See Also:
  `setAliases(java.util.Map<java.lang.String, ?>)`, `setConverters(com.thoughtworks.xstream.converters.ConverterMatcher[])`, `setEncoding(java.lang.String)`

Field Summary
`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
`XStreamMarshaller()`

Method Summary
`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()` Returns 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)` 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 autodetection mode of XStream.
`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)` 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(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()

  Returns the XStream instance used by this marshaller.

### 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

  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)`

### setAliasesByType

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

  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)`

### setFieldAliases

    public void setFieldAliases(Map<String,String> aliases)
                         throws ClassNotFoundException,
                                NoSuchFieldException

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

  Parameters:
    `aliases` -
  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

    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)`

### setAnnotatedClasses

    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[])`

### setAutodetectAnnotations

    public void setAutodetectAnnotations(boolean autodetectAnnotations)

  Set the autodetection mode of XStream.

  Note that auto-detection implies that the XStream is 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`