public class XStreamMarshaller extends AbstractMarshaller implements BeanClassLoaderAware, InitializingBean
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEFAULT_ENCODING
The default encoding used for stream access: UTF-8.
|
logger
Constructor and Description |
---|
XStreamMarshaller() |
Modifier and Type | Method and Description |
---|---|
void |
afterPropertiesSet()
Invoked by the containing
BeanFactory after it has set all bean properties
and satisfied BeanFactoryAware , ApplicationContextAware etc. |
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(java.lang.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 java.lang.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(java.lang.Object graph,
org.w3c.dom.Node node)
Abstract template method for marshalling the given object graph to a DOM
Node . |
void |
marshalOutputStream(java.lang.Object graph,
java.io.OutputStream outputStream)
Abstract template method for marshalling the given object graph to a
OutputStream . |
void |
marshalOutputStream(java.lang.Object graph,
java.io.OutputStream outputStream,
com.thoughtworks.xstream.converters.DataHolder dataHolder) |
protected void |
marshalSaxHandlers(java.lang.Object graph,
org.xml.sax.ContentHandler contentHandler,
org.xml.sax.ext.LexicalHandler lexicalHandler)
Abstract template method for marshalling the given object graph to a SAX
ContentHandler . |
void |
marshalWriter(java.lang.Object graph,
java.io.Writer writer)
Abstract template method for marshalling the given object graph to a
Writer . |
void |
marshalWriter(java.lang.Object graph,
java.io.Writer writer,
com.thoughtworks.xstream.converters.DataHolder dataHolder) |
protected void |
marshalXmlEventWriter(java.lang.Object graph,
javax.xml.stream.XMLEventWriter eventWriter)
Abstract template method for marshalling the given object to a StAX
XMLEventWriter . |
protected void |
marshalXmlStreamWriter(java.lang.Object graph,
javax.xml.stream.XMLStreamWriter streamWriter)
Abstract template method for marshalling the given object to a StAX
XMLStreamWriter . |
void |
setAliases(java.util.Map<java.lang.String,?> aliases)
Set the alias/type map, consisting of string aliases mapped to classes.
|
void |
setAliasesByType(java.util.Map<java.lang.String,?> aliasesByType)
Set the aliases by type map, consisting of string aliases mapped to classes.
|
void |
setAnnotatedClasses(java.lang.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(java.lang.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(java.lang.String encoding)
Set the encoding to be used for stream access.
|
void |
setFieldAliases(java.util.Map<java.lang.String,java.lang.String> fieldAliases)
Set the field alias/type map, consisting of field names.
|
void |
setImplicitCollections(java.util.Map<java.lang.Class<?>,java.lang.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(java.lang.Class<? extends com.thoughtworks.xstream.mapper.MapperWrapper>... 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(java.util.Map<java.lang.Class<?>,java.lang.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(java.lang.Class<?>... supportedClasses)
Set the classes supported by this marshaller.
|
void |
setUseAttributeFor(java.util.Map<?,?> useAttributeFor)
Set the types to use XML attributes for.
|
void |
setUseAttributeForTypes(java.lang.Class<?>... useAttributeForTypes)
Set types to use XML attributes for.
|
boolean |
supports(java.lang.Class<?> clazz)
Indicate whether this marshaller can marshal instances of the supplied type.
|
protected java.lang.Object |
unmarshalDomNode(org.w3c.dom.Node node)
Abstract template method for unmarshalling from a given DOM
Node . |
java.lang.Object |
unmarshalInputStream(java.io.InputStream inputStream)
Abstract template method for unmarshalling from a given
InputStream . |
java.lang.Object |
unmarshalInputStream(java.io.InputStream inputStream,
com.thoughtworks.xstream.converters.DataHolder dataHolder) |
java.lang.Object |
unmarshalReader(java.io.Reader reader)
Abstract template method for unmarshalling from a given
Reader . |
java.lang.Object |
unmarshalReader(java.io.Reader reader,
com.thoughtworks.xstream.converters.DataHolder dataHolder) |
protected java.lang.Object |
unmarshalSaxReader(org.xml.sax.XMLReader xmlReader,
org.xml.sax.InputSource inputSource)
Abstract template method for unmarshalling using a given SAX
XMLReader
and InputSource . |
protected java.lang.Object |
unmarshalStreamSource(javax.xml.transform.stream.StreamSource streamSource)
Template method for handling
StreamSource s. |
protected java.lang.Object |
unmarshalXmlEventReader(javax.xml.stream.XMLEventReader eventReader)
Abstract template method for unmarshalling from a given Stax
XMLEventReader . |
protected java.lang.Object |
unmarshalXmlStreamReader(javax.xml.stream.XMLStreamReader streamReader)
Abstract template method for unmarshalling from a given Stax
XMLStreamReader . |
buildDocument, createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, isProcessExternalEntities, isSupportDtd, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, setProcessExternalEntities, setSupportDtd, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource
public static final java.lang.String DEFAULT_ENCODING
public void setReflectionProvider(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)
ReflectionProvider
to use.public void setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver)
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.
public void setMapper(com.thoughtworks.xstream.mapper.Mapper mapper)
Mapper
to use.public void setMapperWrappers(java.lang.Class<? extends com.thoughtworks.xstream.mapper.MapperWrapper>... mapperWrappers)
MapperWrapper
classes.
Each of those classes needs to have a constructor with a single argument
of type Mapper
or MapperWrapper
.public void setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup converterLookup)
ConverterLookup
to use.
Also used as ConverterRegistry
if the given reference implements it as well.DefaultConverterLookup
public void setConverterRegistry(com.thoughtworks.xstream.converters.ConverterRegistry converterRegistry)
ConverterRegistry
to use.setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup)
,
DefaultConverterLookup
public void setConverters(com.thoughtworks.xstream.converters.ConverterMatcher... converters)
Converters
or SingleValueConverters
to be registered
with the XStream
instance.Converter
,
SingleValueConverter
public void setMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy)
MarshallingStrategy
to use.public void setMode(int mode)
XStream.ID_REFERENCES
,
XStream.NO_REFERENCES
public void setAliases(java.util.Map<java.lang.String,?> aliases)
Keys are aliases; values are either Class
instances, or String class names.
XStream.alias(String, Class)
public void setAliasesByType(java.util.Map<java.lang.String,?> aliasesByType)
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.
XStream.aliasType(String, Class)
public void setFieldAliases(java.util.Map<java.lang.String,java.lang.String> fieldAliases)
XStream.aliasField(String, Class, String)
public void setUseAttributeForTypes(java.lang.Class<?>... useAttributeForTypes)
XStream.useAttributeFor(Class)
public void setUseAttributeFor(java.util.Map<?,?> useAttributeFor)
<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.public void setImplicitCollections(java.util.Map<java.lang.Class<?>,java.lang.String> implicitCollections)
Class
instances
mapped to comma separated collection field names.XStream.addImplicitCollection(Class, String)
public void setOmittedFields(java.util.Map<java.lang.Class<?>,java.lang.String> omittedFields)
Class
instances
mapped to comma separated field names.XStream.omitField(Class, String)
public void setAnnotatedClasses(java.lang.Class<?>... annotatedClasses)
XStream.processAnnotations(Class[])
public void setAutodetectAnnotations(boolean autodetectAnnotations)
Note: Autodetection implies that the XStream instance is being configured while it is processing the XML streams, and thus introduces a potential concurrency problem.
XStream.autodetectAnnotations(boolean)
public void setEncoding(java.lang.String encoding)
DEFAULT_ENCODING
protected java.lang.String getDefaultEncoding()
AbstractMarshaller
null
if none.
The default implementation returns null
.
getDefaultEncoding
in class AbstractMarshaller
public void setNameCoder(com.thoughtworks.xstream.io.naming.NameCoder nameCoder)
NameCoder
to use.
The default is an XmlFriendlyNameCoder
.public void setSupportedClasses(java.lang.Class<?>... supportedClasses)
If this property is empty (the default), all classes are supported.
supports(Class)
public void setBeanClassLoader(java.lang.ClassLoader classLoader)
BeanClassLoaderAware
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.
setBeanClassLoader
in interface BeanClassLoaderAware
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()
public void afterPropertiesSet()
InitializingBean
BeanFactory
after it has set all bean properties
and satisfied BeanFactoryAware
, ApplicationContextAware
etc.
This method allows the bean instance to perform validation of its overall configuration and final initialization when all bean properties have been set.
afterPropertiesSet
in interface InitializingBean
protected com.thoughtworks.xstream.XStream buildXStream()
constructXStream()
, configureXStream(com.thoughtworks.xstream.XStream)
and customizeXStream(com.thoughtworks.xstream.XStream)
.protected com.thoughtworks.xstream.XStream constructXStream()
XStream
instanceprotected void configureXStream(com.thoughtworks.xstream.XStream xstream)
xstream
- the XStream
instanceprotected void customizeXStream(com.thoughtworks.xstream.XStream xstream)
XStream
.
The default implementation is empty.
xstream
- the XStream
instancepublic final com.thoughtworks.xstream.XStream getXStream()
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.
public boolean supports(java.lang.Class<?> clazz)
Marshaller
supports
in interface Marshaller
supports
in interface Unmarshaller
clazz
- the class that this marshaller is being asked if it can marshaltrue
if this marshaller can indeed marshal instances of the supplied class;
false
otherwiseprotected void marshalDomNode(java.lang.Object graph, org.w3c.dom.Node node) throws XmlMappingException
AbstractMarshaller
Node
.
In practice, node is be a Document
node, a DocumentFragment
node,
or a Element
node. In other words, a node that accepts children.
marshalDomNode
in class AbstractMarshaller
graph
- the root of the object graph to marshalnode
- the DOM node that will contain the result treeXmlMappingException
- if the given object cannot be marshalled to the DOM nodeDocument
,
DocumentFragment
,
Element
protected void marshalXmlEventWriter(java.lang.Object graph, javax.xml.stream.XMLEventWriter eventWriter) throws XmlMappingException
AbstractMarshaller
XMLEventWriter
.marshalXmlEventWriter
in class AbstractMarshaller
graph
- the root of the object graph to marshaleventWriter
- the XMLEventWriter
to write toXmlMappingException
- if the given object cannot be marshalled to the DOM nodeprotected void marshalXmlStreamWriter(java.lang.Object graph, javax.xml.stream.XMLStreamWriter streamWriter) throws XmlMappingException
AbstractMarshaller
XMLStreamWriter
.marshalXmlStreamWriter
in class AbstractMarshaller
graph
- the root of the object graph to marshalstreamWriter
- the XMLStreamWriter
to write toXmlMappingException
- if the given object cannot be marshalled to the DOM nodeprotected void marshalSaxHandlers(java.lang.Object graph, org.xml.sax.ContentHandler contentHandler, org.xml.sax.ext.LexicalHandler lexicalHandler) throws XmlMappingException
AbstractMarshaller
ContentHandler
.marshalSaxHandlers
in class AbstractMarshaller
graph
- the root of the object graph to marshalcontentHandler
- the SAX ContentHandler
lexicalHandler
- the SAX2 LexicalHandler
. Can be null
.XmlMappingException
- if the given object cannot be marshalled to the handlerspublic void marshalOutputStream(java.lang.Object graph, java.io.OutputStream outputStream) throws XmlMappingException, java.io.IOException
AbstractMarshaller
OutputStream
.marshalOutputStream
in class AbstractMarshaller
graph
- the root of the object graph to marshaloutputStream
- the OutputStream
to write toXmlMappingException
- if the given object cannot be marshalled to the writerjava.io.IOException
- if an I/O exception occurspublic void marshalOutputStream(java.lang.Object graph, java.io.OutputStream outputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, java.io.IOException
XmlMappingException
java.io.IOException
public void marshalWriter(java.lang.Object graph, java.io.Writer writer) throws XmlMappingException, java.io.IOException
AbstractMarshaller
Writer
.marshalWriter
in class AbstractMarshaller
graph
- the root of the object graph to marshalwriter
- the Writer
to write toXmlMappingException
- if the given object cannot be marshalled to the writerjava.io.IOException
- if an I/O exception occurspublic void marshalWriter(java.lang.Object graph, java.io.Writer writer, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, java.io.IOException
XmlMappingException
java.io.IOException
protected java.lang.Object unmarshalStreamSource(javax.xml.transform.stream.StreamSource streamSource) throws XmlMappingException, java.io.IOException
AbstractMarshaller
StreamSource
s.
This implementation delegates to unmarshalInputStream
or unmarshalReader
.
unmarshalStreamSource
in class AbstractMarshaller
streamSource
- the StreamSource
XmlMappingException
- if the given source cannot be mapped to an objectjava.io.IOException
- if an I/O exception occursprotected java.lang.Object unmarshalDomNode(org.w3c.dom.Node node) throws XmlMappingException
AbstractMarshaller
Node
.unmarshalDomNode
in class AbstractMarshaller
node
- the DOM node that contains the objects to be unmarshalledXmlMappingException
- if the given DOM node cannot be mapped to an objectprotected java.lang.Object unmarshalXmlEventReader(javax.xml.stream.XMLEventReader eventReader) throws XmlMappingException
AbstractMarshaller
XMLEventReader
.unmarshalXmlEventReader
in class AbstractMarshaller
eventReader
- the XMLEventReader
to read fromXmlMappingException
- if the given event reader cannot be converted to an objectprotected java.lang.Object unmarshalXmlStreamReader(javax.xml.stream.XMLStreamReader streamReader) throws XmlMappingException
AbstractMarshaller
XMLStreamReader
.unmarshalXmlStreamReader
in class AbstractMarshaller
streamReader
- the XMLStreamReader
to read fromXmlMappingException
- if the given stream reader cannot be converted to an objectprotected java.lang.Object unmarshalSaxReader(org.xml.sax.XMLReader xmlReader, org.xml.sax.InputSource inputSource) throws XmlMappingException, java.io.IOException
AbstractMarshaller
XMLReader
and InputSource
.unmarshalSaxReader
in class AbstractMarshaller
xmlReader
- the SAX XMLReader
to parse withinputSource
- the input source to parse fromXmlMappingException
- if the given reader and input source cannot be converted to an objectjava.io.IOException
- if an I/O exception occurspublic java.lang.Object unmarshalInputStream(java.io.InputStream inputStream) throws XmlMappingException, java.io.IOException
AbstractMarshaller
InputStream
.unmarshalInputStream
in class AbstractMarshaller
inputStream
- the InputStreamStream
to read fromXmlMappingException
- if the given stream cannot be converted to an objectjava.io.IOException
- if an I/O exception occurspublic java.lang.Object unmarshalInputStream(java.io.InputStream inputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, java.io.IOException
XmlMappingException
java.io.IOException
public java.lang.Object unmarshalReader(java.io.Reader reader) throws XmlMappingException, java.io.IOException
AbstractMarshaller
Reader
.unmarshalReader
in class AbstractMarshaller
reader
- the Reader
to read fromXmlMappingException
- if the given reader cannot be converted to an objectjava.io.IOException
- if an I/O exception occurspublic java.lang.Object unmarshalReader(java.io.Reader reader, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, java.io.IOException
XmlMappingException
java.io.IOException
protected XmlMappingException convertXStreamException(java.lang.Exception ex, boolean marshalling)
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.
ex
- XStream exception that occurredmarshalling
- indicates whether the exception occurs during marshalling (true
),
or unmarshalling (false
)XmlMappingException