org.springframework.oxm.xstream
Class XStreamMarshaller

java.lang.Object
  extended by org.springframework.oxm.support.AbstractMarshaller
      extended by 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), 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 auto-detection 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 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)

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)

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.

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

customizeXStream

protected void customizeXStream(com.thoughtworks.xstream.XStream xstream)
Template to allow for customizing of the given XStream.

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