Object Streams Tutorial

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.

Obviously you should use also a stream-based XML parser reading the XML. A DOM-based XML parser will process the complete XML and build the object model before XStream is able to to handle the first element.

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.

References

Normally XStream will not know about references between the different objects that are written individually in the ObjectStream. Nevertheless there is an example in the acceptance tests (MultipleObjectsInOneStreamTest) where such a functionality is realized with the help of a custom MarshallingStrategy. Note, that this implementation is not for general use, since it will ignore some parameters at second invocation, but they do not matter in the demonstrated use case. Additionally those references prevent the objects from being garbage collected, which is a bit counter-productive for the use case of ObjectStreams as described above. So you have to know what you do!

Software

• About XStream
• News
• Change History
• Security Aspects
• About Versioning

Evaluating XStream

• Two Minute Tutorial
• License
• Download
• References
• Benchmarks
• Code Statistics

Using XStream

• Architecture Overview
• Object references
• Tweaking the Output
• Converters
• Frequently Asked Questions
• Mailing Lists
• Reporting Issues

Javadoc

• XStream Core
• Hibernate Extensions
• JMH Module

Tutorials

• Two Minute Tutorial
• Alias Tutorial
• Annotations Tutorial
• Converter Tutorial
• Object Streams Tutorial
• Persistence API Tutorial
• JSON Tutorial
• StudyTrails

Developing XStream

• How to Contribute
• Development Team
• Source Repository
• Continuous Integration