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

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.

Author:
Joe Walnes

Field Summary
static int ID_REFERENCES
           
static int NO_REFERENCES
           
static int XPATH_REFERENCES
           
 
Constructor Summary
XStream()
           
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, HierarchicalStreamDriver hierarchicalStreamDriver)
           
 
Method Summary
 void addDefaultCollection(java.lang.Class type, java.lang.String fieldName)
           
 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.
 java.lang.Object fromXML(java.io.Reader xml)
          Deserialize an object from an XML Reader.
 java.lang.Object fromXML(java.lang.String xml)
          Deserialize an object from an XML String.
 ClassMapper getClassMapper()
           
 ConverterLookup getConverterLookup()
           
 void marshal(java.lang.Object obj, HierarchicalStreamWriter writer)
          Serialize and object to a hierarchical data structure (such as XML).
 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.
 
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(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)
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).


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.


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.


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.

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 type,
                                 java.lang.String fieldName)


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