# 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
- About Versioning

# Evaluating XStream

- Two Minute Tutorial
- Object references
- Tweaking the Output
- License
- Download
- References
- Statistics

# Using XStream

- Architecture Overview
- Converters
- Frequently Asked Questions
- Users' Mailing List
- JavaDoc Core
- JavaDoc Benchmark
- Reporting Issues

# Tutorials

- Two Minute Tutorial
- Alias Tutorial
- Annotations Tutorial
- Converter Tutorial
- Object Streams Tutorial
- Persistence API Tutorial
- JSON Tutorial

# Developing XStream

- How to Contribute
- Developers' Mailing List
- Development Team
- Source Repository
- Continuous Integration