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 the 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.7 or higher.

As of Spring Framework 6.0, the default HierarchicalStreamDriver is a DomDriver that uses the configured encoding and NameCoder. The driver can be changed via setStreamDriver(HierarchicalStreamDriver).

Since:
3.0
Author:
Peter Meijer, Arjen Poutsma, Juergen Hoeller, Sam Brannen

  • Field Details

    • DEFAULT_ENCODING

      public static final String DEFAULT_ENCODING
      The default encoding used for stream access: UTF-8.
      See Also:

  • Constructor Details

    • XStreamMarshaller

      public XStreamMarshaller()

  • Method Details

    • setReflectionProvider

      public void setReflectionProvider(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)
      Set a custom XStream ReflectionProvider to use.
      Since:
      4.0

    • setStreamDriver

      public void setStreamDriver(com.thoughtworks.xstream.io.HierarchicalStreamDriver streamDriver)
      Set an XStream 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.

    • setMapper

      public void setMapper(com.thoughtworks.xstream.mapper.Mapper mapper)
      Set a custom XStream Mapper to use.
      Since:
      4.0

    • setMapperWrappers

      public void setMapperWrappers(Class<? extends com.thoughtworks.xstream.mapper.MapperWrapper>... mapperWrappers)
      Set one or more custom XStream MapperWrapper classes. Each of those classes needs to have a constructor with a single argument of type Mapper or MapperWrapper.
      Since:
      4.0

    • setConverterLookup

      public void setConverterLookup(com.thoughtworks.xstream.converters.ConverterLookup converterLookup)
      Set a custom XStream ConverterLookup to use. Also used as ConverterRegistry if 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 XStream ConverterRegistry to use.
      Since:
      4.0
      See Also:

    • 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

    • setTypePermissions

      public void setTypePermissions(com.thoughtworks.xstream.security.TypePermission... typePermissions)
      Set XStream type permissions such as AnyTypePermission, ExplicitTypePermission etc, as an alternative to overriding the customizeXStream(XStream) method.

      Note: As of XStream 1.4.18, the default type permissions are restricted to well-known core JDK types. For any custom types, explicit type permissions need to be registered.

      Since:
      5.2.17

    • setMarshallingStrategy

      public void setMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy)
      Set a custom XStream MarshallingStrategy to 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 Class instances, 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 Class instances, 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 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)

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

    • getDefaultEncoding

      protected String getDefaultEncoding()
      Description copied from class: AbstractMarshaller
      Determine the default encoding to use for marshalling or unmarshalling from a byte stream, or null if none.

      The default implementation returns null.

      Overrides:
      getDefaultEncoding in class AbstractMarshaller

    • setNameCoder

      public void setNameCoder(com.thoughtworks.xstream.io.naming.NameCoder nameCoder)
      Set a custom XStream NameCoder to use. The default is an XmlFriendlyNameCoder.
      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:

    • 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

    • afterPropertiesSet

      public void afterPropertiesSet()
      Description copied from interface: InitializingBean
      Invoked by the containing 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.

      Specified by:
      afterPropertiesSet in interface InitializingBean

    • buildXStream

      protected com.thoughtworks.xstream.XStream buildXStream()
      Build the native XStream delegate to be used by this marshaller, delegating to constructXStream(), configureXStream(XStream), and customizeXStream(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 XStream instance

    • configureXStream

      protected void configureXStream(com.thoughtworks.xstream.XStream xstream)
      Configure the XStream instance with this marshaller's bean properties.
      Parameters:
      xstream - the XStream instance

    • customizeXStream

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

      The default implementation is empty.

      Parameters:
      xstream - the XStream instance

    • getXStream

      public final com.thoughtworks.xstream.XStream getXStream()
      Return the native XStream delegate used by this marshaller.

      The creation of the XStream instance returned by this method is thread safe.

      NOTE: This method is marked as final. It can be used to access the fully configured XStream for marshalling but not configuration purposes.

    • supports

      public boolean supports(Class<?> clazz)
      Description copied from interface: Marshaller
      Indicate 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 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:

    • 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

    • marshalSaxHandlers

      protected void marshalSaxHandlers(Object graph, ContentHandler contentHandler, @Nullable 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

    • marshalOutputStream

      public 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

    • marshalOutputStream

      public void marshalOutputStream(Object graph, OutputStream outputStream, @Nullable com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
      Throws:
      XmlMappingException
      IOException

    • marshalWriter

      public 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

    • marshalWriter

      public void marshalWriter(Object graph, Writer writer, @Nullable com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
      Throws:
      XmlMappingException
      IOException

    • unmarshalStreamSource

      protected Object unmarshalStreamSource(StreamSource streamSource) throws XmlMappingException, IOException
      Description copied from class: AbstractMarshaller
      Template method for handling StreamSources.

      This implementation delegates to unmarshalInputStream or unmarshalReader.

      Overrides:
      unmarshalStreamSource in class AbstractMarshaller
      Parameters:
      streamSource - the StreamSource
      Returns:
      the object graph
      Throws:
      XmlMappingException - if the given source cannot be mapped to an object
      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

    • 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

    • unmarshalInputStream

      public 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

    • unmarshalInputStream

      public Object unmarshalInputStream(InputStream inputStream, @Nullable com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
      Throws:
      XmlMappingException
      IOException

    • unmarshalReader

      public 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

    • unmarshalReader

      public Object unmarshalReader(Reader reader, @Nullable com.thoughtworks.xstream.converters.DataHolder dataHolder) throws XmlMappingException, IOException
      Throws:
      XmlMappingException
      IOException

    • 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 - the XStream exception that occurred
      marshalling - indicates whether the exception occurs during marshalling (true), or unmarshalling (false)
      Returns:
      the corresponding XmlMappingException