com.thoughtworks.xstream
Class XStream

java.lang.Object
  extended by com.thoughtworks.xstream.XStream

public class XStream
extends java.lang.Object

Simple facade to XStream library, a Java-XML serialization tool.


Example
 XStream xstream = new XStream();
 String xml = xstream.toXML(myObject); // serialize to XML
 Object myObject2 = xstream.fromXML(xml); // deserialize from XML
 

Aliasing classes

To create shorter XML, you can specify aliases for classes using the alias() method. For example, you can shorten all occurrences of element <com.blah.MyThing> to <my-thing> by registering an alias for the class.


 xstream.alias("my-thing", MyThing.class);
 

Converters

XStream contains a map of Converter instances, each of which acts as a strategy for converting a particular type of class to XML and back again. Out of the box, XStream contains converters for most basic types (String, Date, int, boolean, etc) and collections (Map, List, Set, Properties, etc). For other objects reflection is used to serialize each field recursively.

Extra converters can be registered using the registerConverter() method. Some non-standard converters are supplied in the com.thoughtworks.xstream.converters.extended package and you can create your own by implementing the Converter interface.


Example
 xstream.registerConverter(new SqlTimestampConverter());
 xstream.registerConverter(new DynamicProxyConverter());
 

The converters can be registered with an explicit priority. By default they are registered with XStream.PRIORITY_NORMAL. Converters of same priority will be used in the reverse sequence they have been registered. The default converter, i.e. the converter which will be used if no other registered converter is suitable, can be registered with priority XStream.PRIORITY_VERY_LOW. XStream uses by default the ReflectionConverter as the fallback converter (override createDefaultConverter() to change this).


Example
 xstream.registerConverter(new CustomDefaultConverter(), XStream.PRIORITY_VERY_LOW);
 

Object graphs

XStream has support for object graphs; a deserialized object graph will keep references intact, including circular references.

XStream can signify references in XML using either relative/absolute XPath or IDs. The mode can be changed using setMode():

xstream.setMode(XStream.XPATH_RELATIVE_REFERENCES); (Default) Uses XPath relative references to signify duplicate references. This produces XML with the least clutter.
xstream.setMode(XStream.XPATH_ABSOLUTE_REFERENCES); Uses XPath absolute references to signify duplicate references. This produces XML with the least clutter.
xstream.setMode(XStream.ID_REFERENCES); Uses ID references to signify duplicate references. In some scenarios, such as when using hand-written XML, this is easier to work with.
xstream.setMode(XStream.NO_REFERENCES); This disables object graph support and treats the object structure like a tree. Duplicate references are treated as two separate objects and circular references cause an exception. This is slightly faster and uses less memory than the other two modes.

Thread safety

The XStream instance is thread-safe. That is, once the XStream instance has been created and configured, it may be shared across multiple threads allowing objects to be serialized/deserialized concurrently. Note, that this only applies if annotations are not auto-detected on -the-fly.

Implicit collections

To avoid the need for special tags for collections, you can define implicit collections using one of the addImplicitCollection methods.

Author:
Joe Walnes, Jörg Schaible, Mauro Talevi, Guilherme Silveira

Nested Class Summary
static class XStream.InitializationException
          Deprecated. since 1.3, use InitializationException instead
 
Field Summary
static int ID_REFERENCES
           
static int NO_REFERENCES
           
static int PRIORITY_LOW
           
static int PRIORITY_NORMAL
           
static int PRIORITY_VERY_HIGH
           
static int PRIORITY_VERY_LOW
           
static int XPATH_ABSOLUTE_REFERENCES
           
static int XPATH_REFERENCES
          Deprecated. since 1.2, use XPATH_RELATIVE_REFERENCES or XPATH_ABSOLUTE_REFERENCES instead.
static int XPATH_RELATIVE_REFERENCES
           
 
Constructor Summary
XStream()
          Constructs a default XStream.
XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
          Constructs an XStream with a special HierarchicalStreamDriver.
XStream(ReflectionProvider reflectionProvider)
          Constructs an XStream with a special ReflectionProvider.
XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver)
          Deprecated. As of 1.2, use XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)
XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, java.lang.String classAttributeIdentifier)
          Deprecated. As of 1.2, use XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver) and register classAttributeIdentifier as alias
XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver hierarchicalStreamDriver)
          Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider.
XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, java.lang.ClassLoader classLoader)
          Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared ClassLoader to use.
XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, java.lang.ClassLoader classLoader, Mapper mapper)
          Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared Mapper and the ClassLoader in use.
XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, java.lang.ClassLoader classLoader, Mapper mapper, ConverterLookup converterLookup, ConverterRegistry converterRegistry)
          Constructs an XStream with a special HierarchicalStreamDriver, ReflectionProvider, a prepared Mapper and the ClassLoader in use and an own ConverterRegistry.
XStream(ReflectionProvider reflectionProvider, Mapper mapper, HierarchicalStreamDriver driver)
          Deprecated. since 1.3, use #XStream(ReflectionProvider, HierarchicalStreamDriver, Mapper, ClassLoader) instead
 
Method Summary
 void addDefaultImplementation(java.lang.Class defaultImplementation, java.lang.Class ofType)
          Associate a default implementation of a class with an object.
 void addImmutableType(java.lang.Class type)
          Add immutable types.
 void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName)
          Adds a default implicit collection which is used for any unmapped XML tag.
 void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName, java.lang.Class itemType)
          Adds implicit collection which is used for all items of the given itemType.
 void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName, java.lang.String itemFieldName, java.lang.Class itemType)
          Adds implicit collection which is used for all items of the given element name defined by itemFieldName.
 void alias(java.lang.String name, java.lang.Class type)
          Alias a Class to a shorter name to be used in XML elements.
 void alias(java.lang.String name, java.lang.Class type, java.lang.Class defaultImplementation)
          Alias a Class to a shorter name to be used in XML elements.
 void aliasAttribute(java.lang.Class definedIn, java.lang.String attributeName, java.lang.String alias)
          Create an alias for an attribute.
 void aliasAttribute(java.lang.String alias, java.lang.String attributeName)
          Create an alias for an attribute
 void aliasField(java.lang.String alias, java.lang.Class definedIn, java.lang.String fieldName)
          Create an alias for a field name.
 void aliasPackage(java.lang.String name, java.lang.String pkgName)
          Alias a package to a shorter name to be used in XML elements.
 void aliasSystemAttribute(java.lang.String alias, java.lang.String systemAttributeName)
          Create an alias for a system attribute.
 void aliasType(java.lang.String name, java.lang.Class type)
          Alias a type to a shorter name to be used in XML elements.
 void autodetectAnnotations(boolean mode)
          Set the auto-detection mode of the AnnotationMapper.
protected  Converter createDefaultConverter()
           
 java.io.ObjectInputStream createObjectInputStream(HierarchicalStreamReader reader)
          Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
 java.io.ObjectInputStream createObjectInputStream(java.io.InputStream in)
          Creates an ObjectInputStream that deserializes a stream of objects from an InputStream using XStream.
 java.io.ObjectInputStream createObjectInputStream(java.io.Reader xmlReader)
          Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
 java.io.ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer)
          Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
 java.io.ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer, java.lang.String rootNodeName)
          Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
 java.io.ObjectOutputStream createObjectOutputStream(java.io.OutputStream out)
          Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.
 java.io.ObjectOutputStream createObjectOutputStream(java.io.OutputStream out, java.lang.String rootNodeName)
          Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.
 java.io.ObjectOutputStream createObjectOutputStream(java.io.Writer writer)
          Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
 java.io.ObjectOutputStream createObjectOutputStream(java.io.Writer writer, java.lang.String rootNodeName)
          Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
 java.lang.Object fromXML(java.io.InputStream input)
          Deserialize an object from an XML InputStream.
 java.lang.Object fromXML(java.io.InputStream xml, java.lang.Object root)
          Deserialize an object from an XML InputStream, populating the fields of the given root object instead of instantiating a new one.
 java.lang.Object fromXML(java.io.Reader xml)
          Deserialize an object from an XML Reader.
 java.lang.Object fromXML(java.io.Reader xml, java.lang.Object root)
          Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one.
 java.lang.Object fromXML(java.lang.String xml)
          Deserialize an object from an XML String.
 java.lang.Object fromXML(java.lang.String xml, java.lang.Object root)
          Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one.
 java.lang.ClassLoader getClassLoader()
          Retrieve the ClassLoader XStream uses to load classes.
 ClassMapper getClassMapper()
          Deprecated. As of 1.2, use getMapper()
 ConverterLookup getConverterLookup()
           
 ConverterRegistry getConverterRegistry()
           
 com.thoughtworks.xstream.core.JVM getJvm()
           
 Mapper getMapper()
          Retrieve the Mapper.
 ReflectionProvider getReflectionProvider()
          Retrieve the ReflectionProvider in use.
 void marshal(java.lang.Object obj, HierarchicalStreamWriter writer)
          Serialize and object to a hierarchical data structure (such as XML).
 void marshal(java.lang.Object obj, HierarchicalStreamWriter writer, DataHolder dataHolder)
          Serialize and object to a hierarchical data structure (such as XML).
 DataHolder newDataHolder()
          Create a DataHolder that can be used to pass data to the converters.
 void omitField(java.lang.Class definedIn, java.lang.String fieldName)
          Prevents a field from being serialized.
 void processAnnotations(java.lang.Class type)
          Process the annotations of the given type and configure the XStream.
 void processAnnotations(java.lang.Class[] types)
          Process the annotations of the given types and configure the XStream.
 void registerConverter(Converter converter)
           
 void registerConverter(Converter converter, int priority)
           
 void registerConverter(SingleValueConverter converter)
           
 void registerConverter(SingleValueConverter converter, int priority)
           
 void registerLocalConverter(java.lang.Class definedIn, java.lang.String fieldName, Converter converter)
          Register a local Converter for a field.
 void registerLocalConverter(java.lang.Class definedIn, java.lang.String fieldName, SingleValueConverter converter)
          Register a local SingleValueConverter for a field.
 void setClassLoader(java.lang.ClassLoader classLoader)
          Change the ClassLoader XStream uses to load classes.
 void setMarshallingStrategy(MarshallingStrategy marshallingStrategy)
           
 void setMode(int mode)
          Change mode for dealing with duplicate references.
protected  void setupAliases()
           
protected  void setupConverters()
           
protected  void setupDefaultImplementations()
           
protected  void setupImmutableTypes()
           
 java.lang.String toXML(java.lang.Object obj)
          Serialize an object to a pretty-printed XML String.
 void toXML(java.lang.Object obj, java.io.OutputStream out)
          Serialize an object to the given OutputStream as pretty-printed XML.
 void toXML(java.lang.Object obj, java.io.Writer out)
          Serialize an object to the given Writer as pretty-printed XML.
 java.lang.Object unmarshal(HierarchicalStreamReader reader)
          Deserialize an object from a hierarchical data structure (such as XML).
 java.lang.Object unmarshal(HierarchicalStreamReader reader, java.lang.Object root)
          Deserialize an object from a hierarchical data structure (such as XML), populating the fields of the given root object instead of instantiating a new one.
 java.lang.Object unmarshal(HierarchicalStreamReader reader, java.lang.Object root, DataHolder dataHolder)
          Deserialize an object from a hierarchical data structure (such as XML).
 void useAttributeFor(java.lang.Class type)
          Use an attribute for an arbitrary type.
 void useAttributeFor(java.lang.Class definedIn, java.lang.String fieldName)
          Use an attribute for a field declared in a specific type.
 void useAttributeFor(java.lang.String fieldName, java.lang.Class type)
          Use an attribute for a field or a specific type.
protected  boolean useXStream11XmlFriendlyMapper()
           
protected  MapperWrapper wrapMapper(MapperWrapper next)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_REFERENCES

public static final int NO_REFERENCES
See Also:
Constant Field Values

ID_REFERENCES

public static final int ID_REFERENCES
See Also:
Constant Field Values

XPATH_RELATIVE_REFERENCES

public static final int XPATH_RELATIVE_REFERENCES
See Also:
Constant Field Values

XPATH_ABSOLUTE_REFERENCES

public static final int XPATH_ABSOLUTE_REFERENCES
See Also:
Constant Field Values

XPATH_REFERENCES

public static final int XPATH_REFERENCES
Deprecated. since 1.2, use XPATH_RELATIVE_REFERENCES or XPATH_ABSOLUTE_REFERENCES instead.
See Also:
Constant Field Values

PRIORITY_VERY_HIGH

public static final int PRIORITY_VERY_HIGH
See Also:
Constant Field Values

PRIORITY_NORMAL

public static final int PRIORITY_NORMAL
See Also:
Constant Field Values

PRIORITY_LOW

public static final int PRIORITY_LOW
See Also:
Constant Field Values

PRIORITY_VERY_LOW

public static final int PRIORITY_VERY_LOW
See Also:
Constant Field Values
Constructor Detail

XStream

public XStream()
Constructs a default XStream. The instance will use the XppDriver as default and tries to determine the best match for the ReflectionProvider on its own.

Throws:
XStream.InitializationException - in case of an initialization problem

XStream

public XStream(ReflectionProvider reflectionProvider)
Constructs an XStream with a special ReflectionProvider. The instance will use the XppDriver as default.

Throws:
XStream.InitializationException - in case of an initialization problem

XStream

public XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
Constructs an XStream with a special HierarchicalStreamDriver. The instance will tries to determine the best match for the ReflectionProvider on its own.

Throws:
XStream.InitializationException - in case of an initialization problem

XStream

public XStream(ReflectionProvider reflectionProvider,
               HierarchicalStreamDriver hierarchicalStreamDriver)
Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider.

Throws:
XStream.InitializationException - in case of an initialization problem

XStream

public XStream(ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               HierarchicalStreamDriver driver)
Deprecated. As of 1.2, use XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)


XStream

public XStream(ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               HierarchicalStreamDriver driver,
               java.lang.String classAttributeIdentifier)
Deprecated. As of 1.2, use XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver) and register classAttributeIdentifier as alias


XStream

public XStream(ReflectionProvider reflectionProvider,
               Mapper mapper,
               HierarchicalStreamDriver driver)
Deprecated. since 1.3, use #XStream(ReflectionProvider, HierarchicalStreamDriver, Mapper, ClassLoader) instead

Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared Mapper.

Throws:
XStream.InitializationException - in case of an initialization problem

XStream

public XStream(ReflectionProvider reflectionProvider,
               HierarchicalStreamDriver driver,
               java.lang.ClassLoader classLoader)
Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared ClassLoader to use.

Throws:
XStream.InitializationException - in case of an initialization problem
Since:
1.3

XStream

public XStream(ReflectionProvider reflectionProvider,
               HierarchicalStreamDriver driver,
               java.lang.ClassLoader classLoader,
               Mapper mapper)
Constructs an XStream with a special HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared Mapper and the ClassLoader in use.

Note, if the class loader should be changed later again, you should provide a ClassLoaderReference as ClassLoader that is also use in the Mapper chain.

Throws:
XStream.InitializationException - in case of an initialization problem
Since:
1.3

XStream

public XStream(ReflectionProvider reflectionProvider,
               HierarchicalStreamDriver driver,
               java.lang.ClassLoader classLoader,
               Mapper mapper,
               ConverterLookup converterLookup,
               ConverterRegistry converterRegistry)
Constructs an XStream with a special HierarchicalStreamDriver, ReflectionProvider, a prepared Mapper and the ClassLoader in use and an own ConverterRegistry.

Note, if the class loader should be changed later again, you should provide a ClassLoaderReference as ClassLoader that is also use in the Mapper chain.

Throws:
XStream.InitializationException - in case of an initialization problem
Since:
1.3
Method Detail

wrapMapper

protected MapperWrapper wrapMapper(MapperWrapper next)

useXStream11XmlFriendlyMapper

protected boolean useXStream11XmlFriendlyMapper()

setupAliases

protected void setupAliases()

setupDefaultImplementations

protected void setupDefaultImplementations()

createDefaultConverter

protected Converter createDefaultConverter()

setupConverters

protected void setupConverters()

setupImmutableTypes

protected void setupImmutableTypes()

setMarshallingStrategy

public void setMarshallingStrategy(MarshallingStrategy marshallingStrategy)

toXML

public java.lang.String toXML(java.lang.Object obj)
Serialize an object to a pretty-printed XML String.

Throws:
XStreamException - if the object cannot be serialized

toXML

public void toXML(java.lang.Object obj,
                  java.io.Writer out)
Serialize an object to the given Writer as pretty-printed XML. The Writer will be flushed afterwards and in case of an exception.

Throws:
XStreamException - if the object cannot be serialized

toXML

public void toXML(java.lang.Object obj,
                  java.io.OutputStream out)
Serialize an object to the given OutputStream as pretty-printed XML. The OutputStream will be flushed afterwards and in case of an exception.

Throws:
XStreamException - if the object cannot be serialized

marshal

public void marshal(java.lang.Object obj,
                    HierarchicalStreamWriter writer)
Serialize and object to a hierarchical data structure (such as XML).

Throws:
XStreamException - if the object cannot be serialized

marshal

public void marshal(java.lang.Object obj,
                    HierarchicalStreamWriter writer,
                    DataHolder dataHolder)
Serialize and object to a hierarchical data structure (such as XML).

Parameters:
dataHolder - Extra data you can use to pass to your converters. Use this as you want. If not present, XStream shall create one lazily as needed.
Throws:
XStreamException - if the object cannot be serialized

fromXML

public java.lang.Object fromXML(java.lang.String xml)
Deserialize an object from an XML String.

Throws:
XStreamException - if the object cannot be deserialized

fromXML

public java.lang.Object fromXML(java.io.Reader xml)
Deserialize an object from an XML Reader.

Throws:
XStreamException - if the object cannot be deserialized

fromXML

public java.lang.Object fromXML(java.io.InputStream input)
Deserialize an object from an XML InputStream.

Throws:
XStreamException - if the object cannot be deserialized

fromXML

public java.lang.Object fromXML(java.lang.String xml,
                                java.lang.Object root)
Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

Throws:
XStreamException - if the object cannot be deserialized

fromXML

public java.lang.Object fromXML(java.io.Reader xml,
                                java.lang.Object root)
Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

Throws:
XStreamException - if the object cannot be deserialized

fromXML

public java.lang.Object fromXML(java.io.InputStream xml,
                                java.lang.Object root)
Deserialize an object from an XML InputStream, populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

Throws:
XStreamException - if the object cannot be deserialized

unmarshal

public java.lang.Object unmarshal(HierarchicalStreamReader reader)
Deserialize an object from a hierarchical data structure (such as XML).

Throws:
XStreamException - if the object cannot be deserialized

unmarshal

public java.lang.Object unmarshal(HierarchicalStreamReader reader,
                                  java.lang.Object root)
Deserialize an object from a hierarchical data structure (such as XML), populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

Throws:
XStreamException - if the object cannot be deserialized

unmarshal

public java.lang.Object unmarshal(HierarchicalStreamReader reader,
                                  java.lang.Object root,
                                  DataHolder dataHolder)
Deserialize an object from a hierarchical data structure (such as XML).

Parameters:
root - If present, the passed in object will have its fields populated, as opposed to XStream creating a new instance. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!
dataHolder - Extra data you can use to pass to your converters. Use this as you want. If not present, XStream shall create one lazily as needed.
Throws:
XStreamException - if the object cannot be deserialized

alias

public void alias(java.lang.String name,
                  java.lang.Class type)
Alias a Class to a shorter name to be used in XML elements.

Parameters:
name - Short name
type - Type to be aliased
Throws:
XStream.InitializationException - if no ClassAliasingMapper is available

aliasType

public void aliasType(java.lang.String name,
                      java.lang.Class type)
Alias a type to a shorter name to be used in XML elements. Any class that is assignable to this type will be aliased to the same name.

Parameters:
name - Short name
type - Type to be aliased
Throws:
XStream.InitializationException - if no ClassAliasingMapper is available
Since:
1.2

alias

public void alias(java.lang.String name,
                  java.lang.Class type,
                  java.lang.Class defaultImplementation)
Alias a Class to a shorter name to be used in XML elements.

Parameters:
name - Short name
type - Type to be aliased
defaultImplementation - Default implementation of type to use if no other specified.
Throws:
XStream.InitializationException - if no DefaultImplementationsMapper or no ClassAliasingMapper is available

aliasPackage

public void aliasPackage(java.lang.String name,
                         java.lang.String pkgName)
Alias a package to a shorter name to be used in XML elements.

Parameters:
name - Short name
pkgName - package to be aliased
Throws:
XStream.InitializationException - if no DefaultImplementationsMapper or no PackageAliasingMapper is available
Since:
1.3.1

aliasField

public void aliasField(java.lang.String alias,
                       java.lang.Class definedIn,
                       java.lang.String fieldName)
Create an alias for a field name.

Parameters:
alias - the alias itself
definedIn - the type that declares the field
fieldName - the name of the field
Throws:
XStream.InitializationException - if no FieldAliasingMapper is available

aliasAttribute

public void aliasAttribute(java.lang.String alias,
                           java.lang.String attributeName)
Create an alias for an attribute

Parameters:
alias - the alias itself
attributeName - the name of the attribute
Throws:
XStream.InitializationException - if no AttributeAliasingMapper is available

aliasSystemAttribute

public void aliasSystemAttribute(java.lang.String alias,
                                 java.lang.String systemAttributeName)
Create an alias for a system attribute. XStream will not write a system attribute if its alias is set to null. However, this is not reversible, i.e. deserialization of the result is likely to fail afterwards and will not produce an object equal to the originally written one.

Parameters:
alias - the alias itself (may be null)
systemAttributeName - the name of the system attribute
Throws:
XStream.InitializationException - if no SystemAttributeAliasingMapper is available
Since:
1.3.1

aliasAttribute

public void aliasAttribute(java.lang.Class definedIn,
                           java.lang.String attributeName,
                           java.lang.String alias)
Create an alias for an attribute.

Parameters:
definedIn - the type where the attribute is defined
attributeName - the name of the attribute
alias - the alias itself
Throws:
XStream.InitializationException - if no AttributeAliasingMapper is available
Since:
1.2.2

useAttributeFor

public void useAttributeFor(java.lang.String fieldName,
                            java.lang.Class type)
Use an attribute for a field or a specific type.

Parameters:
fieldName - the name of the field
type - the Class of the type to be rendered as XML attribute
Throws:
XStream.InitializationException - if no AttributeMapper is available
Since:
1.2

useAttributeFor

public void useAttributeFor(java.lang.Class definedIn,
                            java.lang.String fieldName)
Use an attribute for a field declared in a specific type.

Parameters:
fieldName - the name of the field
definedIn - the Class containing such field
Throws:
XStream.InitializationException - if no AttributeMapper is available
Since:
1.2.2

useAttributeFor

public void useAttributeFor(java.lang.Class type)
Use an attribute for an arbitrary type.

Parameters:
type - the Class of the type to be rendered as XML attribute
Throws:
XStream.InitializationException - if no AttributeMapper is available
Since:
1.2

addDefaultImplementation

public void addDefaultImplementation(java.lang.Class defaultImplementation,
                                     java.lang.Class ofType)
Associate a default implementation of a class with an object. Whenever XStream encounters an instance of this type, it will use the default implementation instead. For example, java.util.ArrayList is the default implementation of java.util.List.

Parameters:
defaultImplementation -
ofType -
Throws:
XStream.InitializationException - if no DefaultImplementationsMapper is available

addImmutableType

public void addImmutableType(java.lang.Class type)
Add immutable types. The value of the instances of these types will always be written into the stream even if they appear multiple times.

Throws:
XStream.InitializationException - if no ImmutableTypesMapper is available

registerConverter

public void registerConverter(Converter converter)

registerConverter

public void registerConverter(Converter converter,
                              int priority)

registerConverter

public void registerConverter(SingleValueConverter converter)

registerConverter

public void registerConverter(SingleValueConverter converter,
                              int priority)

registerLocalConverter

public void registerLocalConverter(java.lang.Class definedIn,
                                   java.lang.String fieldName,
                                   Converter converter)
Register a local Converter for a field.

Parameters:
definedIn - the class type the field is defined in
fieldName - the field name
converter - the converter to use
Since:
1.3

registerLocalConverter

public void registerLocalConverter(java.lang.Class definedIn,
                                   java.lang.String fieldName,
                                   SingleValueConverter converter)
Register a local SingleValueConverter for a field.

Parameters:
definedIn - the class type the field is defined in
fieldName - the field name
converter - the converter to use
Since:
1.3

getClassMapper

public ClassMapper getClassMapper()
Deprecated. As of 1.2, use getMapper()

Throws:
java.lang.ClassCastException - if mapper is not really a deprecated ClassMapper instance

getMapper

public Mapper getMapper()
Retrieve the Mapper. This is by default a chain of MapperWrappers.

Returns:
the mapper
Since:
1.2

getReflectionProvider

public ReflectionProvider getReflectionProvider()
Retrieve the ReflectionProvider in use.

Returns:
the mapper
Since:
1.2.1

getConverterLookup

public ConverterLookup getConverterLookup()

getConverterRegistry

public ConverterRegistry getConverterRegistry()

getJvm

public com.thoughtworks.xstream.core.JVM getJvm()

setMode

public void setMode(int mode)
Change mode for dealing with duplicate references. Valid values are XPATH_ABSOLUTE_REFERENCES, XPATH_RELATIVE_REFERENCES, XStream.ID_REFERENCES and XStream.NO_REFERENCES.

Throws:
java.lang.IllegalArgumentException - if the mode is not one of the declared types
See Also:
XPATH_ABSOLUTE_REFERENCES, XPATH_RELATIVE_REFERENCES, ID_REFERENCES, NO_REFERENCES

addImplicitCollection

public void addImplicitCollection(java.lang.Class ownerType,
                                  java.lang.String fieldName)
Adds a default implicit collection which is used for any unmapped XML tag.

Parameters:
ownerType - class owning the implicit collection
fieldName - name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type.

addImplicitCollection

public void addImplicitCollection(java.lang.Class ownerType,
                                  java.lang.String fieldName,
                                  java.lang.Class itemType)
Adds implicit collection which is used for all items of the given itemType.

Parameters:
ownerType - class owning the implicit collection
fieldName - name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type.
itemType - type of the items to be part of this collection.
Throws:
XStream.InitializationException - if no ImplicitCollectionMapper is available

addImplicitCollection

public void addImplicitCollection(java.lang.Class ownerType,
                                  java.lang.String fieldName,
                                  java.lang.String itemFieldName,
                                  java.lang.Class itemType)
Adds implicit collection which is used for all items of the given element name defined by itemFieldName.

Parameters:
ownerType - class owning the implicit collection
fieldName - name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type.
itemFieldName - element name of the implicit collection
itemType - item type to be aliases be the itemFieldName
Throws:
XStream.InitializationException - if no ImplicitCollectionMapper is available

newDataHolder

public DataHolder newDataHolder()
Create a DataHolder that can be used to pass data to the converters. The DataHolder is provided with a call to marshal(Object, HierarchicalStreamWriter, DataHolder) or unmarshal(HierarchicalStreamReader, Object, DataHolder).

Returns:
a new DataHolder

createObjectOutputStream

public java.io.ObjectOutputStream createObjectOutputStream(java.io.Writer writer)
                                                    throws java.io.IOException
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

To change the name of the root element (from <object-stream>), use createObjectOutputStream(java.io.Writer, String).

Throws:
java.io.IOException
Since:
1.0.3
See Also:
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public java.io.ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer)
                                                    throws java.io.IOException
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

To change the name of the root element (from <object-stream>), use createObjectOutputStream(java.io.Writer, String).

Throws:
java.io.IOException
Since:
1.0.3
See Also:
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public java.io.ObjectOutputStream createObjectOutputStream(java.io.Writer writer,
                                                           java.lang.String rootNodeName)
                                                    throws java.io.IOException
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

Throws:
java.io.IOException
Since:
1.0.3
See Also:
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public java.io.ObjectOutputStream createObjectOutputStream(java.io.OutputStream out)
                                                    throws java.io.IOException
Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.

To change the name of the root element (from <object-stream>), use createObjectOutputStream(java.io.Writer, String).

Throws:
java.io.IOException
Since:
1.3
See Also:
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public java.io.ObjectOutputStream createObjectOutputStream(java.io.OutputStream out,
                                                           java.lang.String rootNodeName)
                                                    throws java.io.IOException
Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.

Throws:
java.io.IOException
Since:
1.3
See Also:
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public java.io.ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer,
                                                           java.lang.String rootNodeName)
                                                    throws java.io.IOException
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

Because an ObjectOutputStream can contain multiple items and XML only allows a single root node, the stream must be written inside an enclosing node.

It is necessary to call ObjectOutputStream.close() when done, otherwise the stream will be incomplete.

Example

  ObjectOutputStream out = xstream.createObjectOutputStream(aWriter, "things");
   out.writeInt(123);
   out.writeObject("Hello");
   out.writeObject(someObject)
   out.close();
 

Parameters:
writer - The writer to serialize the objects to.
rootNodeName - The name of the root node enclosing the stream of objects.
Throws:
java.io.IOException
Since:
1.0.3
See Also:
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectInputStream

public java.io.ObjectInputStream createObjectInputStream(java.io.Reader xmlReader)
                                                  throws java.io.IOException
Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.

Throws:
java.io.IOException
Since:
1.0.3
See Also:
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader), createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)

createObjectInputStream

public java.io.ObjectInputStream createObjectInputStream(java.io.InputStream in)
                                                  throws java.io.IOException
Creates an ObjectInputStream that deserializes a stream of objects from an InputStream using XStream.

Throws:
java.io.IOException
Since:
1.3
See Also:
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader), createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)

createObjectInputStream

public java.io.ObjectInputStream createObjectInputStream(HierarchicalStreamReader reader)
                                                  throws java.io.IOException
Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.

Example

 ObjectInputStream in = xstream.createObjectOutputStream(aReader);
 int a = out.readInt();
 Object b = out.readObject();
 Object c = out.readObject();
 

Throws:
java.io.IOException
Since:
1.0.3
See Also:
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)

setClassLoader

public void setClassLoader(java.lang.ClassLoader classLoader)
Change the ClassLoader XStream uses to load classes. Creating an XStream instance it will register for all kind of classes and types of the current JDK, but not for any 3rd party type. To ensure that all other types are loaded with your classloader, you should call this method as early as possible - or consider to provide the classloader directly in the constructor.

Since:
1.1.1

getClassLoader

public java.lang.ClassLoader getClassLoader()
Retrieve the ClassLoader XStream uses to load classes.

Since:
1.1.1

omitField

public void omitField(java.lang.Class definedIn,
                      java.lang.String fieldName)
Prevents a field from being serialized. To omit a field you must always provide the declaring type and not necessarily the type that is converted.

Throws:
XStream.InitializationException - if no FieldAliasingMapper is available
Since:
1.1.3

processAnnotations

public void processAnnotations(java.lang.Class[] types)
Process the annotations of the given types and configure the XStream.

Parameters:
types - the types with XStream annotations
Since:
1.3

processAnnotations

public void processAnnotations(java.lang.Class type)
Process the annotations of the given type and configure the XStream. A call of this method will automatically turn the auto-detection mode for annotations off.

Parameters:
type - the type with XStream annotations
Since:
1.3

autodetectAnnotations

public void autodetectAnnotations(boolean mode)
Set the auto-detection mode of the AnnotationMapper. Note that auto-detection implies that the XStream is configured while it is processing the XML steams. This is a potential concurrency problem. Also is it technically not possible to detect all class aliases at deserialization. You have been warned!

Parameters:
mode - true if annotations are auto-detected
Since:
1.3


Copyright © 2004-2011 XStream. All Rights Reserved.