XStream provides alternative implementations of java.io.ObjectInputStream and java.io.ObjectOutputStream, allowing streams of objects to be serialized or deserialized from XML.

This is useful when processing large sets of objects, as only one needs to be in memory at a time.

Using the Object Streams

The interface to the object streaming capabilities of XStream is through the standard java.io.ObjectOutputStream and java.io.ObjectInputStream objects.

Example

To serialize a stream of objects to XML:

ObjectOutputStream out = xstream.createObjectOutputStream(someWriter);

out.writeObject(new Person("Joe", "Walnes"));
out.writeObject(new Person("Someone", "Else"));
out.writeObject("hello");
out.writeInt(12345);

out.close();

The resulting XML:

<object-stream>
  <com.blah.Person>
    <firstname>Joe</firstname>
    <lastname>Walnes</lastname>
  </com.blah.Person>
  <com.blah.Person>
    <firstname>Someone</firstname>
    <lastname>Else</lastname>
  </com.blah.Person>
  <string>hello</string>
  <int>123</int>
</object-stream>

To deserialze the stream of objects from the XML:

ObjectInputStream in = xstream.createObjectInputStream(someReader);

Person a = (Person)in.readObject();
Person b = (Person)in.readObject();
String c = (String)in.readObject();
int    d = in.readInt();

Considerations

Root node

Because an XML document can only have a single root node, all the serialized elements must be wrapped in an additional root node. This root node defaults to <object-stream>, as shown in the example above.

This can be changed by using the overloaded method: xstream.createObjectOutputStream(Writer writer, String rootNodeName);

Close the ObjectOutputStream

Remember to call ObjectOutputStream.close(), otherwise the stream will contain incomplete XML.

Detecting the end of the ObjectInputStream

When there are no more objects left to read in the stream, ObjectInputStream.readObject() (or primitive equivalent) will throw java.io.EOFException.