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 BeanClassLoaderAware, InitializingBean
Implementation of theMarshallerinterface 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
XStreamMarshallerto unmarshal XML from external sources (i.e. the Web), as this can result in security vulnerabilities. If you do use theXStreamMarshallerto unmarshal external XML, set thesupportedClassesandconvertersproperties (possibly using aCatchAllConverter) or override thecustomizeXStream(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
XStreamconstruction has been reworked in 4.0, with the stream driver and the class loader getting passed into XStream itself now.- Since:
- 3.0
- Author:
- Peter Meijer, Arjen Poutsma, Juergen Hoeller
Field Summary
Fields Modifier and Type Field Description static StringDEFAULT_ENCODINGThe default encoding used for stream access: UTF-8.Fields inherited from class org.springframework.oxm.support.AbstractMarshaller
logger
Constructor Summary
Constructors Constructor Description XStreamMarshaller()
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidafterPropertiesSet()Invoked by the containingBeanFactoryafter it has set all bean properties and satisfiedBeanFactoryAware,ApplicationContextAwareetc.protected com.thoughtworks.xstream.XStreambuildXStream()Build the native XStream delegate to be used by this marshaller, delegating toconstructXStream(),configureXStream(com.thoughtworks.xstream.XStream)andcustomizeXStream(com.thoughtworks.xstream.XStream).protected voidconfigureXStream(com.thoughtworks.xstream.XStream xstream)Configure the XStream instance with this marshaller's bean properties.protected com.thoughtworks.xstream.XStreamconstructXStream()Construct an XStream instance, either using one of the standard constructors or creating a custom subclass.protected XmlMappingExceptionconvertXStreamException(Exception ex, boolean marshalling)Convert the given XStream exception to an appropriate exception from theorg.springframework.oxmhierarchy.protected voidcustomizeXStream(com.thoughtworks.xstream.XStream xstream)Template to allow for customizing the givenXStream.protected StringgetDefaultEncoding()Determine the default encoding to use for marshalling or unmarshalling from a byte stream, ornullif none.com.thoughtworks.xstream.XStreamgetXStream()Return the native XStream delegate used by this marshaller.protected voidmarshalDomNode(Object graph, Node node)Abstract template method for marshalling the given object graph to a DOMNode.voidmarshalOutputStream(Object graph, OutputStream outputStream)Abstract template method for marshalling the given object graph to aOutputStream.voidmarshalOutputStream(Object graph, OutputStream outputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder)protected voidmarshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)Abstract template method for marshalling the given object graph to a SAXContentHandler.voidmarshalWriter(Object graph, Writer writer)Abstract template method for marshalling the given object graph to aWriter.voidmarshalWriter(Object graph, Writer writer, com.thoughtworks.xstream.converters.DataHolder dataHolder)protected voidmarshalXmlEventWriter(Object graph, XMLEventWriter eventWriter)Abstract template method for marshalling the given object to a StAXXMLEventWriter.protected voidmarshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter)Abstract template method for marshalling the given object to a StAXXMLStreamWriter.voidsetAliases(Map<String,?> aliases)Set the alias/type map, consisting of string aliases mapped to classes.voidsetAliasesByType(Map<String,?> aliasesByType)Set the aliases by type map, consisting of string aliases mapped to classes.voidsetAnnotatedClasses(Class<?>... annotatedClasses)Set annotated classes for which aliases will be read from class-level annotation metadata.voidsetAutodetectAnnotations(boolean autodetectAnnotations)Activate XStream's autodetection mode.voidsetBeanClassLoader(ClassLoader classLoader)Callback that supplies the beanclass loaderto a bean instance.voidsetConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup converterLookup)Set a custom XStreamConverterLookupto use.voidsetConverterRegistry(com.thoughtworks.xstream.converters.ConverterRegistry converterRegistry)Set a custom XStreamConverterRegistryto use.voidsetConverters(com.thoughtworks.xstream.converters.ConverterMatcher... converters)Set theConvertersorSingleValueConvertersto be registered with theXStreaminstance.voidsetEncoding(String encoding)Set the encoding to be used for stream access.voidsetFieldAliases(Map<String,String> fieldAliases)Set the field alias/type map, consisting of field names.voidsetImplicitCollections(Map<Class<?>,String> implicitCollections)Specify implicit collection fields, as a Map consisting ofClassinstances mapped to comma separated collection field names.voidsetMapper(com.thoughtworks.xstream.mapper.Mapper mapper)Set a custom XStreamMapperto use.voidsetMapperWrappers(Class<? extends com.thoughtworks.xstream.mapper.MapperWrapper>... mapperWrappers)Set one or more custom XStreamMapperWrapperclasses.voidsetMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy)Set a custom XStreamMarshallingStrategyto use.voidsetMode(int mode)Set the XStream mode to use.voidsetNameCoder(com.thoughtworks.xstream.io.naming.NameCoder nameCoder)Set a custom XStreamNameCoderto use.voidsetOmittedFields(Map<Class<?>,String> omittedFields)Specify omitted fields, as a Map consisting ofClassinstances mapped to comma separated field names.voidsetReflectionProvider(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)Set a custom XStreamReflectionProviderto use.voidsetStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver)Set a XStreamHierarchicalStreamDriverto be used for readers and writers.voidsetSupportedClasses(Class<?>... supportedClasses)Set the classes supported by this marshaller.voidsetUseAttributeFor(Map<?,?> useAttributeFor)Set the types to use XML attributes for.voidsetUseAttributeForTypes(Class<?>... useAttributeForTypes)Set types to use XML attributes for.booleansupports(Class<?> clazz)Indicate whether this marshaller can marshal instances of the supplied type.protected ObjectunmarshalDomNode(Node node)Abstract template method for unmarshalling from a given DOMNode.ObjectunmarshalInputStream(InputStream inputStream)Abstract template method for unmarshalling from a givenInputStream.ObjectunmarshalInputStream(InputStream inputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder)ObjectunmarshalReader(Reader reader)Abstract template method for unmarshalling from a givenReader.ObjectunmarshalReader(Reader reader, com.thoughtworks.xstream.converters.DataHolder dataHolder)protected ObjectunmarshalSaxReader(XMLReader xmlReader, InputSource inputSource)Abstract template method for unmarshalling using a given SAXXMLReaderandInputSource.protected ObjectunmarshalStreamSource(StreamSource streamSource)Template method for handlingStreamSources.protected ObjectunmarshalXmlEventReader(XMLEventReader eventReader)Abstract template method for unmarshalling from a given StaxXMLEventReader.protected ObjectunmarshalXmlStreamReader(XMLStreamReader streamReader)Abstract template method for unmarshalling from a given StaxXMLStreamReader.Methods inherited from class org.springframework.oxm.support.AbstractMarshaller
buildDocument, createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, isProcessExternalEntities, isSupportDtd, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, setProcessExternalEntities, setSupportDtd, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource
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
setReflectionProvider
public void setReflectionProvider(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)
Set a custom XStreamReflectionProviderto use.- Since:
- 4.0
setStreamDriver
public void setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver)
Set a XStreamHierarchicalStreamDriverto be used for readers and writers.As of Spring 4.0, this stream driver will also be passed to the
XStreamconstructor and therefore used by streaming-related native API methods themselves.
setMapper
public void setMapper(com.thoughtworks.xstream.mapper.Mapper mapper)
Set a custom XStreamMapperto use.- Since:
- 4.0
setMapperWrappers
public void setMapperWrappers(Class<? extends com.thoughtworks.xstream.mapper.MapperWrapper>... mapperWrappers)
Set one or more custom XStreamMapperWrapperclasses. Each of those classes needs to have a constructor with a single argument of typeMapperorMapperWrapper.- Since:
- 4.0
setConverterLookup
public void setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup converterLookup)
Set a custom XStreamConverterLookupto use. Also used asConverterRegistryif the given reference implements it as well.- Since:
- 4.0
- See Also:
DefaultConverterLookup
setConverterRegistry
public void setConverterRegistry(com.thoughtworks.xstream.converters.ConverterRegistry converterRegistry)
Set a custom XStreamConverterRegistryto use.- Since:
- 4.0
- See Also:
setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup),DefaultConverterLookup
setConverters
public void setConverters(com.thoughtworks.xstream.converters.ConverterMatcher... converters)
Set theConvertersorSingleValueConvertersto be registered with theXStreaminstance.- See Also:
Converter,SingleValueConverter
setMarshallingStrategy
public void setMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy)
Set a custom XStreamMarshallingStrategyto use.- Since:
- 4.0
setMode
public void setMode(int mode)
Set the XStream mode to use.- See Also:
XStream.ID_REFERENCES,XStream.NO_REFERENCES
setAliases
public void setAliases(Map<String,?> aliases)
Set the alias/type map, consisting of string aliases mapped to classes.Keys are aliases; values are either
Classinstances, or String class names.- See Also:
XStream.alias(String, Class)
setAliasesByType
public void setAliasesByType(Map<String,?> aliasesByType)
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
Classinstances, or String class names.- See Also:
XStream.aliasType(String, Class)
setFieldAliases
public void setFieldAliases(Map<String,String> fieldAliases)
Set the field alias/type map, consisting of field names.- See Also:
XStream.aliasField(String, Class, String)
setUseAttributeForTypes
public void setUseAttributeForTypes(Class<?>... useAttributeForTypes)
Set types to use XML attributes for.- See Also:
XStream.useAttributeFor(Class)
setUseAttributeFor
public void setUseAttributeFor(Map<?,?> useAttributeFor)
Set the types to use XML attributes for. The given map can contain either<String, Class>pairs, in which caseXStream.useAttributeFor(String, Class)is called. Alternatively, the map can contain<Class, String>or<Class, List<String>>pairs, which results inXStream.useAttributeFor(Class, String)calls.
setImplicitCollections
public void setImplicitCollections(Map<Class<?>,String> implicitCollections)
Specify implicit collection fields, as a Map consisting ofClassinstances 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 ofClassinstances mapped to comma separated field names.- See Also:
XStream.omitField(Class, String)
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)
setEncoding
public void setEncoding(String encoding)
Set the encoding to be used for stream access.- See Also:
DEFAULT_ENCODING
getDefaultEncoding
protected String getDefaultEncoding()
Description copied from class:AbstractMarshallerDetermine the default encoding to use for marshalling or unmarshalling from a byte stream, ornullif none.The default implementation returns
null.- Overrides:
getDefaultEncodingin classAbstractMarshaller
setNameCoder
public void setNameCoder(com.thoughtworks.xstream.io.naming.NameCoder nameCoder)
Set a custom XStreamNameCoderto use. The default is anXmlFriendlyNameCoder.- Since:
- 4.0.4
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:BeanClassLoaderAwareCallback that supplies the beanclass loaderto a bean instance.Invoked after the population of normal bean properties but before an initialization callback such as
InitializingBean'sInitializingBean.afterPropertiesSet()method or a custom init-method.- Specified by:
setBeanClassLoaderin interfaceBeanClassLoaderAware- Parameters:
classLoader- the owning class loader; may benullin which case a defaultClassLoadermust be used, for example theClassLoaderobtained viaClassUtils.getDefaultClassLoader()
afterPropertiesSet
public void afterPropertiesSet()
Description copied from interface:InitializingBeanInvoked by the containingBeanFactoryafter it has set all bean properties and satisfiedBeanFactoryAware,ApplicationContextAwareetc.This method allows the bean instance to perform validation of its overall configuration and final initialization when all bean properties have been set.
- Specified by:
afterPropertiesSetin interfaceInitializingBean
buildXStream
protected com.thoughtworks.xstream.XStream buildXStream()
Build the native XStream delegate to be used by this marshaller, delegating toconstructXStream(),configureXStream(com.thoughtworks.xstream.XStream)andcustomizeXStream(com.thoughtworks.xstream.XStream).
constructXStream
protected com.thoughtworks.xstream.XStream constructXStream()
Construct an XStream instance, either using one of the standard constructors or creating a custom subclass.- Returns:
- the
XStreaminstance
configureXStream
protected void configureXStream(com.thoughtworks.xstream.XStream xstream)
Configure the XStream instance with this marshaller's bean properties.- Parameters:
xstream- theXStreaminstance
customizeXStream
protected void customizeXStream(com.thoughtworks.xstream.XStream xstream)
Template to allow for customizing the givenXStream.The default implementation is empty.
- Parameters:
xstream- theXStreaminstance
getXStream
public final com.thoughtworks.xstream.XStream getXStream()
Return the native XStream delegate used by this marshaller.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.
supports
public boolean supports(Class<?> clazz)
Description copied from interface:MarshallerIndicate whether this marshaller can marshal instances of the supplied type.- Specified by:
supportsin interfaceMarshaller- Specified by:
supportsin interfaceUnmarshaller- Parameters:
clazz- the class that this marshaller is being asked if it can marshal- Returns:
trueif this marshaller can indeed marshal instances of the supplied class;falseotherwise
marshalDomNode
protected void marshalDomNode(Object graph, Node node) throws XmlMappingException
Description copied from class:AbstractMarshallerAbstract template method for marshalling the given object graph to a DOMNode.In practice, node is be a
Documentnode, aDocumentFragmentnode, or aElementnode. In other words, a node that accepts children.- Specified by:
marshalDomNodein classAbstractMarshaller- Parameters:
graph- the root of the object graph to marshalnode- 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:AbstractMarshallerAbstract template method for marshalling the given object to a StAXXMLEventWriter.- Specified by:
marshalXmlEventWriterin classAbstractMarshaller- Parameters:
graph- the root of the object graph to marshaleventWriter- theXMLEventWriterto 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:AbstractMarshallerAbstract template method for marshalling the given object to a StAXXMLStreamWriter.- Specified by:
marshalXmlStreamWriterin classAbstractMarshaller- Parameters:
graph- the root of the object graph to marshalstreamWriter- theXMLStreamWriterto write to- Throws:
XmlMappingException- if the given object cannot be marshalled to the DOM node
marshalSaxHandlers
protected void marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler) throws XmlMappingException
Description copied from class:AbstractMarshallerAbstract template method for marshalling the given object graph to a SAXContentHandler.- Specified by:
marshalSaxHandlersin classAbstractMarshaller- Parameters:
graph- the root of the object graph to marshalcontentHandler- the SAXContentHandlerlexicalHandler- the SAX2LexicalHandler. Can benull.- Throws:
XmlMappingException- if the given object cannot be marshalled to the handlers
marshalOutputStream
public void marshalOutputStream(Object graph, OutputStream outputStream) throws XmlMappingException, IOException
Description copied from class:AbstractMarshallerAbstract template method for marshalling the given object graph to aOutputStream.- Specified by:
marshalOutputStreamin classAbstractMarshaller- Parameters:
graph- the root of the object graph to marshaloutputStream- theOutputStreamto write to- Throws:
XmlMappingException- if the given object cannot be marshalled to the writerIOException- if an I/O exception occurs
marshalOutputStream
public void marshalOutputStream(Object graph, OutputStream outputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
marshalWriter
public void marshalWriter(Object graph, Writer writer) throws XmlMappingException, IOException
Description copied from class:AbstractMarshallerAbstract template method for marshalling the given object graph to aWriter.- Specified by:
marshalWriterin classAbstractMarshaller- Parameters:
graph- the root of the object graph to marshalwriter- theWriterto write to- Throws:
XmlMappingException- if the given object cannot be marshalled to the writerIOException- if an I/O exception occurs
marshalWriter
public void marshalWriter(Object graph, Writer writer, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
unmarshalStreamSource
protected Object unmarshalStreamSource(StreamSource streamSource) throws XmlMappingException, IOException
Description copied from class:AbstractMarshallerTemplate method for handlingStreamSources.This implementation delegates to
unmarshalInputStreamorunmarshalReader.- Overrides:
unmarshalStreamSourcein classAbstractMarshaller- Parameters:
streamSource- theStreamSource- Returns:
- the object graph
- Throws:
XmlMappingException- if the given source cannot be mapped to an objectIOException- if an I/O exception occurs
unmarshalDomNode
protected Object unmarshalDomNode(Node node) throws XmlMappingException
Description copied from class:AbstractMarshallerAbstract template method for unmarshalling from a given DOMNode.- Specified by:
unmarshalDomNodein classAbstractMarshaller- 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:AbstractMarshallerAbstract template method for unmarshalling from a given StaxXMLEventReader.- Specified by:
unmarshalXmlEventReaderin classAbstractMarshaller- Parameters:
eventReader- theXMLEventReaderto 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:AbstractMarshallerAbstract template method for unmarshalling from a given StaxXMLStreamReader.- Specified by:
unmarshalXmlStreamReaderin classAbstractMarshaller- Parameters:
streamReader- theXMLStreamReaderto read from- Returns:
- the object graph
- Throws:
XmlMappingException- if the given stream reader cannot be converted to an object
unmarshalSaxReader
protected Object unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource) throws XmlMappingException, IOException
Description copied from class:AbstractMarshallerAbstract template method for unmarshalling using a given SAXXMLReaderandInputSource.- Specified by:
unmarshalSaxReaderin classAbstractMarshaller- Parameters:
xmlReader- the SAXXMLReaderto parse withinputSource- the input source to parse from- Returns:
- the object graph
- Throws:
XmlMappingException- if the given reader and input source cannot be converted to an objectIOException- if an I/O exception occurs
unmarshalInputStream
public Object unmarshalInputStream(InputStream inputStream) throws XmlMappingException, IOException
Description copied from class:AbstractMarshallerAbstract template method for unmarshalling from a givenInputStream.- Specified by:
unmarshalInputStreamin classAbstractMarshaller- Parameters:
inputStream- theInputStreamStreamto read from- Returns:
- the object graph
- Throws:
XmlMappingException- if the given stream cannot be converted to an objectIOException- if an I/O exception occurs
unmarshalInputStream
public Object unmarshalInputStream(InputStream inputStream, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
unmarshalReader
public Object unmarshalReader(Reader reader) throws XmlMappingException, IOException
Description copied from class:AbstractMarshallerAbstract template method for unmarshalling from a givenReader.- Specified by:
unmarshalReaderin classAbstractMarshaller- Parameters:
reader- theReaderto read from- Returns:
- the object graph
- Throws:
XmlMappingException- if the given reader cannot be converted to an objectIOException- if an I/O exception occurs
unmarshalReader
public Object unmarshalReader(Reader reader, com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
convertXStreamException
protected XmlMappingException convertXStreamException(Exception ex, boolean marshalling)
Convert the given XStream exception to an appropriate exception from theorg.springframework.oxmhierarchy.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 occurredmarshalling- indicates whether the exception occurs during marshalling (true), or unmarshalling (false)- Returns:
- the corresponding
XmlMappingException