Codebase list libxstream-java / aaea765 xstream-distribution / src / content / objectstream.html
aaea765

Tree @aaea765 (Download .tar.gz)

objectstream.html @aaea765 — raw · history · blame 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
<html>
<!--
 Copyright (C) 2005, 2006 Joe Walnes.
 Copyright (C) 2006, 2007, 2008 XStream committers.
 All rights reserved.
 
 The software in this package is published under the terms of the BSD
 style license a copy of which has been included with this distribution in
 the LICENSE.txt file.
 
 Created on 29. January 2005 by Joe Walnes
 -->
    <head>
        <title>Object Streams Tutorial</title>
        <style type="text/css">.highlight {}</style>
    </head>
    <body>

        <p>XStream provides alternative implementations of <code>java.io.ObjectInputStream</code> and
        <code>java.io.ObjectOutputStream</code>,
        allowing streams of objects to be serialized or deserialized from XML.</p>
        <p>This is useful when processing large sets of objects, as only one needs to be in memory
        at a time.</p>
        <p>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.</p>

        <!-- ************ -->

        <h1 id="using">Using the Object Streams</h1>

        <p>The interface to the object streaming capabilities of XStream is through the standard
        <code>java.io.ObjectOutputStream</code> and <code>java.io.ObjectInputStream</code> objects.</p>

        <h2>Example</h2>

        <p>To serialize a stream of objects to XML:</p>

<div class="Source Java"><pre>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();</pre></div>

        <p>The resulting XML:</p>

<div class="Source XML"><pre>&lt;object-stream&gt;
  &lt;com.blah.Person&gt;
    &lt;firstname&gt;Joe&lt;/firstname&gt;
    &lt;lastname&gt;Walnes&lt;/lastname&gt;
  &lt;/com.blah.Person&gt;
  &lt;com.blah.Person&gt;
    &lt;firstname&gt;Someone&lt;/firstname&gt;
    &lt;lastname&gt;Else&lt;/lastname&gt;
  &lt;/com.blah.Person&gt;
  &lt;string&gt;hello&lt;/string&gt;
  &lt;int&gt;123&lt;/int&gt;
&lt;/object-stream&gt;</pre></div>

        <p>To deserialze the stream of objects from the XML:</p>

<div class="Source Java"><pre>ObjectInputStream in = xstream.createObjectInputStream(someReader);

Person a = (Person)in.readObject();
Person b = (Person)in.readObject();
String c = (String)in.readObject();
int    d = in.readInt();</pre></div>

        <!-- ************ -->

        <h1 id="considerations">Considerations</h1>

        <h2>Root node</h2>

        <p>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 <code>&lt;object-stream&gt;</code>, as shown in the example above.</p>

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

        <h2>Close the ObjectOutputStream</h2>

        <p>Remember to call <code>ObjectOutputStream.close()</code>, otherwise the stream will contain incomplete XML.</p>

        <h2>Detecting the end of the ObjectInputStream</h2>

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

        <h2>References</h2>

        <p>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!</p>
        
    </body>
</html>