com.thoughtworks.xstream
Class XStream

java.lang.Object
  extended bycom.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 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(Converter defaultConverter)
           
XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
           
XStream(ReflectionProvider reflectionProvider)
           
XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver)
           
XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, java.lang.String classAttributeIdentifier)
           
XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, java.lang.String classAttributeIdentifier, Converter defaultConverter)
           
XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver hierarchicalStreamDriver)
           
 
Method Summary
 void addDefaultCollection(java.lang.Class ownerType, java.lang.String fieldName)
          Deprecated. Use addImplicitCollection() instead.
 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 elementName, java.lang.Class type)
          Alias a Class to a shorter name to be used in XML elements.
 void alias(java.lang.String elementName, java.lang.Class type, java.lang.Class defaultImplementation)
          Alias a Class to a shorter name to be used in XML elements.
 void changeDefaultConverter(Converter defaultConverter)
           
 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.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.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.Reader xml)
          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.io.Reader xml, java.lang.Object root)
          Deserialize an object from an XML Reader.
 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.
 ClassMapper getClassMapper()
           
 ConverterLookup getConverterLookup()
           
 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()
           
 void registerConverter(Converter converter)
           
 void setMarshallingStrategy(MarshallingStrategy marshallingStrategy)
           
 void setMode(int mode)
          Change mode for dealing with duplicate references.
 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.Writer writer)
          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).
 
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(Converter defaultConverter)

XStream

public XStream(HierarchicalStreamDriver hierarchicalStreamDriver)

XStream

public XStream(ReflectionProvider reflectionProvider)

XStream

public XStream(ReflectionProvider reflectionProvider,
               HierarchicalStreamDriver hierarchicalStreamDriver)

XStream

public XStream(ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               HierarchicalStreamDriver driver)

XStream

public XStream(ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               HierarchicalStreamDriver driver,
               java.lang.String classAttributeIdentifier)

XStream

public XStream(ReflectionProvider reflectionProvider,
               ClassMapper classMapper,
               HierarchicalStreamDriver driver,
               java.lang.String classAttributeIdentifier,
               Converter defaultConverter)
Method Detail

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.


toXML

public void toXML(java.lang.Object obj,
                  java.io.Writer writer)
Serialize an object to the given Writer as pretty-printed XML.


marshal

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


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.

fromXML

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


fromXML

public java.lang.Object fromXML(java.io.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 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.


fromXML

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


unmarshal

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


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.


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.
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(java.lang.String elementName,
                  java.lang.Class type)
Alias a Class to a shorter name to be used in XML elements.

Parameters:
elementName - Short name
type - Type to be aliased

alias

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

Parameters:
elementName - Short name
type - Type to be aliased
defaultImplementation - Default implementation of type to use if no other specified.

changeDefaultConverter

public void changeDefaultConverter(Converter defaultConverter)

registerConverter

public void registerConverter(Converter converter)

getClassMapper

public ClassMapper getClassMapper()

getConverterLookup

public 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(java.lang.Class ownerType,
                                 java.lang.String fieldName)
Deprecated. Use addImplicitCollection() instead.


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 filed must be an java.util.ArrayList.

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 filed must be an java.util.ArrayList.
itemType - type of the items to be part of this collection.

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 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 DataHolder newDataHolder()

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(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(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)


Joe Walnes, http://xstream.codehaus.org/