Java Doc for XStream.java in  » XML » xstream-1.3 » com » thoughtworks » xstream » Java Source Code / Java DocumentationJava Source Code and Java Documentation

 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 com.thoughtworks.xstream.converters.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 com.thoughtworks.xstream.converters.Converter interface.

 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 com.thoughtworks.xstream.converters.reflection.ReflectionConverter as the initial default converter.

 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 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.

Implicit collections

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

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.

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.

Example

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

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

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

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

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