com.thoughtworks.xstream
Class XStream

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

public class XStream
extends 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 occurences 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 default converter, ie the converter which will be used if no other registered converter is suitable, can be configured by either one of the constructors or can be changed using the changeDefaultConverter() method. If not set, XStream uses ReflectionConverter as the initial default converter.

Example

 xstream.changeDefaultConverter(new ACustomDefaultConverter());
 

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 XPath or IDs. The mode can be changed using setMode():

xstream.setMode(XStream.XPATH_REFERENCES);	(Default) Uses XPath 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 seperate 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.

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, Mauro Talevi

Field Summary

static int	ID_REFERENCES
static int	NO_REFERENCES
static int	XPATH_REFERENCES

Constructor Summary

XStream()

XStream(com.thoughtworks.xstream.converters.Converter defaultConverter)
Deprecated. As of XStream 1.1.1, a default Converter is unnecessary as you can register a Converter with an associated priority. Use an alternate constructor.

XStream(com.thoughtworks.xstream.io.HierarchicalStreamDriver hierarchicalStreamDriver)

XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)

XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider, ClassMapper classMapper, com.thoughtworks.xstream.io.HierarchicalStreamDriver driver)

XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider, ClassMapper classMapper, com.thoughtworks.xstream.io.HierarchicalStreamDriver driver, String classAttributeIdentifier)

XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider, ClassMapper classMapper, com.thoughtworks.xstream.io.HierarchicalStreamDriver driver, String classAttributeIdentifier, com.thoughtworks.xstream.converters.Converter defaultConverter)
Deprecated. As of XStream 1.1.1, a default Converter is unnecessary as you can register a Converter with an associated priority. Use an alternate constructor.

XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider, com.thoughtworks.xstream.io.HierarchicalStreamDriver hierarchicalStreamDriver)

Method Summary

void	addDefaultCollection(Class ownerType, String fieldName) Deprecated. Use addImplicitCollection() instead.
void	addDefaultImplementation(Class defaultImplementation, Class ofType) Associate a default implementation of a class with an object.
void	addImmutableType(Class type)
void	addImplicitCollection(Class ownerType, String fieldName) Adds a default implicit collection which is used for any unmapped xml tag.
void	addImplicitCollection(Class ownerType, String fieldName, Class itemType) Adds implicit collection which is used for all items of the given itemType.
void	addImplicitCollection(Class ownerType, String fieldName, String itemFieldName, Class itemType) Adds implicit collection which is used for all items of the given element name defined by itemFieldName.
void	alias(String name, Class type) Alias a Class to a shorter name to be used in XML elements.
void	alias(String name, Class type, Class defaultImplementation) Alias a Class to a shorter name to be used in XML elements.
protected ClassMapper	buildMapper(String classAttributeIdentifier)
void	changeDefaultConverter(com.thoughtworks.xstream.converters.Converter defaultConverter) Deprecated. As of 1.1.1 you should register a converter with the appropriate priority.
ObjectInputStream	createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader reader) Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
ObjectInputStream	createObjectInputStream(Reader xmlReader) Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
ObjectOutputStream	createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter writer) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
ObjectOutputStream	createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter writer, String rootNodeName) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
ObjectOutputStream	createObjectOutputStream(Writer writer) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
ObjectOutputStream	createObjectOutputStream(Writer writer, String rootNodeName) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
Object	fromXML(Reader xml) Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one.
Object	fromXML(Reader xml, Object root) Deserialize an object from an XML Reader.
Object	fromXML(String xml) Deserialize an object from an XML String.
Object	fromXML(String xml, Object root) Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one.
ClassLoader	getClassLoader() Change the ClassLoader XStream uses to load classes.
ClassMapper	getClassMapper()
com.thoughtworks.xstream.converters.ConverterLookup	getConverterLookup()
void	marshal(Object obj, com.thoughtworks.xstream.io.HierarchicalStreamWriter writer) Serialize and object to a hierarchical data structure (such as XML).
void	marshal(Object obj, com.thoughtworks.xstream.io.HierarchicalStreamWriter writer, com.thoughtworks.xstream.converters.DataHolder dataHolder) Serialize and object to a hierarchical data structure (such as XML).
com.thoughtworks.xstream.converters.DataHolder	newDataHolder()
void	registerConverter(com.thoughtworks.xstream.converters.Converter converter)
void	registerConverter(com.thoughtworks.xstream.converters.Converter converter, int priority)
void	setClassLoader(ClassLoader classLoader) Change the ClassLoader XStream uses to load classes.
void	setMarshallingStrategy(com.thoughtworks.xstream.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()
String	toXML(Object obj) Serialize an object to a pretty-printed XML String.
void	toXML(Object obj, Writer writer) Serialize an object to the given Writer as pretty-printed XML.
Object	unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader) Deserialize an object from a hierarchical data structure (such as XML).
Object	unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader, 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.
Object	unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader, Object root, com.thoughtworks.xstream.converters.DataHolder dataHolder) Deserialize an object from a hierarchical data structure (such as XML).
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_REFERENCES

public static final int XPATH_REFERENCES

See Also:

Constant Field Values

Constructor Detail

XStream

public XStream()

XStream

public XStream(com.thoughtworks.xstream.converters.Converter defaultConverter)

Deprecated. As of XStream 1.1.1, a default Converter is unnecessary as you can register a Converter with an associated priority. Use an alternate constructor.

XStream

public XStream(com.thoughtworks.xstream.io.HierarchicalStreamDriver hierarchicalStreamDriver)

XStream

public XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider)

XStream

public XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider,
               com.thoughtworks.xstream.io.HierarchicalStreamDriver hierarchicalStreamDriver)

XStream

public XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               com.thoughtworks.xstream.io.HierarchicalStreamDriver driver)

XStream

public XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               com.thoughtworks.xstream.io.HierarchicalStreamDriver driver,
               String classAttributeIdentifier)

XStream

public XStream(com.thoughtworks.xstream.converters.reflection.ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               com.thoughtworks.xstream.io.HierarchicalStreamDriver driver,
               String classAttributeIdentifier,
               com.thoughtworks.xstream.converters.Converter defaultConverter)

Deprecated. As of XStream 1.1.1, a default Converter is unnecessary as you can register a Converter with an associated priority. Use an alternate constructor.

Method Detail

buildMapper

protected ClassMapper buildMapper(String classAttributeIdentifier)

wrapMapper

protected MapperWrapper wrapMapper(MapperWrapper next)

setupAliases

protected void setupAliases()

setupDefaultImplementations

protected void setupDefaultImplementations()

setupConverters

protected void setupConverters()

setupImmutableTypes

protected void setupImmutableTypes()

setMarshallingStrategy

public void setMarshallingStrategy(com.thoughtworks.xstream.MarshallingStrategy marshallingStrategy)

toXML

public String toXML(Object obj)

Serialize an object to a pretty-printed XML String.

toXML

public void toXML(Object obj,
                  Writer writer)

Serialize an object to the given Writer as pretty-printed XML.

marshal

public void marshal(Object obj,
                    com.thoughtworks.xstream.io.HierarchicalStreamWriter writer)

Serialize and object to a hierarchical data structure (such as XML).

marshal

public void marshal(Object obj,
                    com.thoughtworks.xstream.io.HierarchicalStreamWriter writer,
                    com.thoughtworks.xstream.converters.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.

fromXML

public Object fromXML(String xml)

Deserialize an object from an XML String.

fromXML

public Object fromXML(Reader xml)

Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one.

fromXML

public Object fromXML(String xml,
                      Object root)

Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one.

fromXML

public Object fromXML(Reader xml,
                      Object root)

Deserialize an object from an XML Reader.

unmarshal

public Object unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader)

Deserialize an object from a hierarchical data structure (such as XML).

unmarshal

public Object unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader,
                        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.

unmarshal

public Object unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader,
                        Object root,
                        com.thoughtworks.xstream.converters.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.

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.

alias

public void alias(String name,
                  Class type)

Alias a Class to a shorter name to be used in XML elements.

Parameters:

name - Short name

type - Type to be aliased

alias

public void alias(String name,
                  Class type,
                  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.

addDefaultImplementation

public void addDefaultImplementation(Class defaultImplementation,
                                     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 -

addImmutableType

public void addImmutableType(Class type)

changeDefaultConverter

public void changeDefaultConverter(com.thoughtworks.xstream.converters.Converter defaultConverter)

Deprecated. As of 1.1.1 you should register a converter with the appropriate priority.

registerConverter

public void registerConverter(com.thoughtworks.xstream.converters.Converter converter)

registerConverter

public void registerConverter(com.thoughtworks.xstream.converters.Converter converter,
                              int priority)

getClassMapper

public ClassMapper getClassMapper()

getConverterLookup

public com.thoughtworks.xstream.converters.ConverterLookup getConverterLookup()

setMode

public void setMode(int mode)

Change mode for dealing with duplicate references. Valid valuse are XStream.XPATH_REFERENCES, XStream.ID_REFERENCES and XStream.NO_REFERENCES.

See Also:

XPATH_REFERENCES, ID_REFERENCES, NO_REFERENCES

addDefaultCollection

public void addDefaultCollection(Class ownerType,
                                 String fieldName)

Deprecated. Use addImplicitCollection() instead.

addImplicitCollection

public void addImplicitCollection(Class ownerType,
                                  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 filed must be an java.util.ArrayList.

addImplicitCollection

public void addImplicitCollection(Class ownerType,
                                  String fieldName,
                                  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 filed must be an java.util.ArrayList.

itemType - type of the items to be part of this collection.

addImplicitCollection

public void addImplicitCollection(Class ownerType,
                                  String fieldName,
                                  String itemFieldName,
                                  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 filed must be an java.util.ArrayList.

itemFieldName - element name of the implicit collection

itemType - item type to be aliases be the itemFieldName

newDataHolder

public com.thoughtworks.xstream.converters.DataHolder newDataHolder()

createObjectOutputStream

public ObjectOutputStream createObjectOutputStream(Writer writer)
                                            throws 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:

IOException

Since:

1.0.3

See Also:

createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public ObjectOutputStream createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter writer)
                                            throws 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:

IOException

Since:

1.0.3

See Also:

createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public ObjectOutputStream createObjectOutputStream(Writer writer,
                                                   String rootNodeName)
                                            throws IOException

Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

Throws:

IOException

Since:

1.0.3

See Also:

createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String), createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectOutputStream

public ObjectOutputStream createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter writer,
                                                   String rootNodeName)
                                            throws 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:

IOException

Since:

1.0.3

See Also:

createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)

createObjectInputStream

public ObjectInputStream createObjectInputStream(Reader xmlReader)
                                          throws IOException

Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.

Throws:

IOException

Since:

1.0.3

See Also:

createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader), createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)

createObjectInputStream

public ObjectInputStream createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader reader)
                                          throws 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:

IOException

Since:

1.0.3

See Also:

createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)

setClassLoader

public void setClassLoader(ClassLoader classLoader)

Change the ClassLoader XStream uses to load classes.

Since:

1.1.1

getClassLoader

public ClassLoader getClassLoader()

Change the ClassLoader XStream uses to load classes.

Since:

1.1.1