org.springframework.oxm.xstream
Class XStreamMarshaller

java.lang.Object
  org.springframework.oxm.AbstractMarshaller
      org.springframework.oxm.xstream.XStreamMarshaller

All Implemented Interfaces:

Marshaller, Unmarshaller

Direct Known Subclasses:

AnnotationXStreamMarshaller

public class XStreamMarshaller
extends AbstractMarshaller

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 that 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:

1.0.0

Author:

Peter Meijer, Arjen Poutsma

See Also:

setEncoding(String), DEFAULT_ENCODING, setAliases(Map), setConverters(ConverterMatcher[])

Field Summary

static String

DEFAULT_ENCODING The default encoding used for stream access.

Fields inherited from class org.springframework.oxm.AbstractMarshaller

logger

Constructor Summary

XStreamMarshaller()

Method Summary

void	addAlias(String name, Class type) Adds an alias for the given type.
void	addImplicitCollection(String name, Class type) Adds an implicit Collection for the given type.
void	addOmittedField(Class type, String fieldName) Adds an omitted field for the given type.
XmlMappingException	convertXStreamException(Exception ex, boolean marshalling) Convert the given XStream exception to an appropriate exception from the org.springframework.oxm hierarchy.
String	getEncoding() Returns the encoding to be used for stream access.
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 aliases) Set a alias/type map, consisting of string aliases mapped to Class instances (or Strings to be converted to Class instances).
void	setConverters(com.thoughtworks.xstream.converters.ConverterMatcher[] converters) Sets the Converters or SingleValueConverters to be registered with the XStream instance.
void	setEncoding(String encoding) Sets the encoding to be used for stream access.
void	setImplicitCollection(Map implicitCollection) Set a implicit colletion/type map, consisting of string implicit collection mapped to Class instances (or Strings to be converted to Class instances).
void	setMode(int mode) Sets the XStream mode.
void	setOmittedFields(Map omittedFields) Sets a ommited field map, consisting of Class instances (or Strings to be converted to Class instances) mapped to comma separated field names.
void	setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver) Sets the XStream hierarchical stream driver to be used with stream readers and writers
void	setSupportedClasses(Class[] supportedClasses) Sets the classes supported by this marshaller.
void	setUseAttributeFor(Map attributes) Sets the types to use XML attributes for.
void	setUseAttributeForTypes(Class[] types) Sets 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.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.

See Also:

Constant Field Values

Constructor Detail

XStreamMarshaller

public XStreamMarshaller()

Method Detail

getEncoding

public String getEncoding()

Returns the encoding to be used for stream access. If this property is not set, the default encoding is used.

See Also:

DEFAULT_ENCODING

setEncoding

public void setEncoding(String encoding)

Sets the encoding to be used for stream access. If this property is not set, the default encoding is used.

See Also:

DEFAULT_ENCODING

getXStream

public com.thoughtworks.xstream.XStream getXStream()

Returns the XStream instance used by this marshaller.

setMode

public void setMode(int mode)

Sets the XStream mode.

See Also:

XStream.XPATH_REFERENCES, XStream.ID_REFERENCES, XStream.NO_REFERENCES

setSupportedClasses

public void setSupportedClasses(Class[] supportedClasses)

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

See Also:

supports(Class)

setConverters

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

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

See Also:

Converter, SingleValueConverter

setStreamDriver

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

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

setAliases

public void setAliases(Map aliases)

Set a alias/type map, consisting of string aliases mapped to Class instances (or Strings to be converted to Class instances).

See Also:

ClassEditor

addAlias

public void addAlias(String name,
                     Class type)

Adds an alias for the given type.

Parameters:

name - alias to be used for the type

type - the type to be aliased

setUseAttributeForTypes

public void setUseAttributeForTypes(Class[] types)

Sets types to use XML attributes for.

See Also:

XStream.useAttributeFor(Class)

setUseAttributeFor

public void setUseAttributeFor(Map attributes)

Sets 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, or <Class, String> pairs, which results in XStream.useAttributeFor(Class,String).

addImplicitCollection

public void addImplicitCollection(String name,
                                  Class type)

Adds an implicit Collection for the given type.

See Also:

XStream.addImplicitCollection(Class, String)

setImplicitCollection

public void setImplicitCollection(Map implicitCollection)

Set a implicit colletion/type map, consisting of string implicit collection mapped to Class instances (or Strings to be converted to Class instances).

See Also:

XStream.addImplicitCollection(Class, String)

addOmittedField

public void addOmittedField(Class type,
                            String fieldName)

Adds an omitted field for the given type.

Parameters:

type - the type to be containing the field

fieldName - field to omitt

See Also:

XStream.omitField(Class, String)

setOmittedFields

public void setOmittedFields(Map omittedFields)

Sets a ommited field map, consisting of Class instances (or Strings to be converted to Class instances) mapped to comma separated field names.

See Also:

XStream.omitField(Class, String)

supports

public boolean supports(Class clazz)

Description copied from interface: Marshaller

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

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

convertXStreamException

public XmlMappingException convertXStreamException(Exception ex,
                                                   boolean marshalling)

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

The default implementation delegates to XStreamUtils. Can be overridden in subclasses.

Parameters:

ex - exception that occured

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

Returns:

the corresponding XmlMappingException instance

See Also:

XStreamUtils.convertXStreamException(Exception,boolean)

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