-
Notifications
You must be signed in to change notification settings - Fork 9
/
tutorial.html
223 lines (174 loc) · 10.3 KB
/
tutorial.html
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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
Copyright (C) 2005, 2006 Joe Walnes.
Copyright (C) 2006, 2007, 2008, 2021 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>XStream - Two Minute Tutorial</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
<!-- Google analytics -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-110973-2";
urchinTracker();
</script>
</head>
<body>
<div id="banner">
<a href="index.html"><img id="logo" src="logo.gif" alt="XStream"/></a>
</div>
<div id="center" class="Content2Column"> <!-- Content3Column for index -->
<div id="content">
<h1 class="FirstChild">Two Minute Tutorial</h1>
<p>This is a very quick introduction to XStream.
Skim read it to get an idea of how simple it is to convert objects to XML and back again.
I'm sure you'll have questions afterwards.</p>
<h1 id="create-classes">Create classes to be serialized</h1>
<p>Here's a couple of simple classes. XStream can convert instances of these to XML and back again.</p>
<div class="Source Java"><pre>public class Person {
private String firstname;
private String lastname;
private PhoneNumber phone;
private PhoneNumber fax;
// ... constructors and methods
}
public class PhoneNumber {
private int code;
private String number;
// ... constructors and methods
}</pre></div>
<p><b>Note:</b> Notice that the fields are private. XStream doesn't care about the
visibility of the fields. No getters or setters are needed. Also, XStream
does not limit you to having a default constructor.</p>
<h1 id="init">Initializing XStream</h1>
<p>To use XStream, simply instantiate the <code>XStream</code> class:</p>
<div class="Source Java"><pre>XStream xstream = new XStream();</pre></div>
<p>You require <code>xstream-[version].jar</code>, <code>xpp3-[version].jar</code> and
<code>xmlpull-[version].jar</code> in the classpath. <a href="http://www.extreme.indiana.edu/xgws/xsoap/xpp/">Xpp3</a>
is a very fast XML pull-parser implementation. If you do not want to include these dependencies, you can use a standard
JAXP DOM parser or since Java 6 the integrated StAX parser instead:</p>
<div class="Source Java"><pre>XStream xstream = new XStream(new DomDriver()); // does not require XPP3 library</pre></div>
<div class="Source Java"><pre>XStream xstream = new XStream(new StaxDriver()); // does not require XPP3 library starting with Java 6</pre></div>
<p><b>Note:</b> This class is a simple facade designed for common operations. For more flexibility you
may choose to create your own facade that behaves differently.</p>
<p>Now, to make the XML outputted by XStream more concise, you can create aliases for your custom class names
to XML element names. This is the <b>only</b> type of mapping required to use XStream and even this is optional.</p>
<div class="Source Java"><pre>xstream.alias("person", Person.class);
xstream.alias("phonenumber", PhoneNumber.class);</pre></div>
<p class="highlight"><b>Note:</b> This is an optional step. Without it XStream would work fine, but the XML element names would
contain the fully qualified name of each class (including package) which would bulk up the XML a bit. See the
<a href="alias-tutorial.html">Alias Tutorial</a> a more complete introduction.</p>
<h1 id="to-xml">Serializing an object to XML</h1>
<p>Let's create an instance of Person and populate its fields:</p>
<div class="Source Java"><pre>Person joe = new Person("Joe", "Walnes");
joe.setPhone(new PhoneNumber(123, "1234-456"));
joe.setFax(new PhoneNumber(123, "9999-999"));</pre></div>
<p>Now, to convert it to XML, all you have to do is make a simple call to XStream:</p>
<div class="Source Java"><pre>String xml = xstream.toXML(joe);</pre></div>
<p>The resulting XML looks like this:</p>
<div class="Source XML"><pre><person>
<firstname>Joe</firstname>
<lastname>Walnes</lastname>
<phone>
<code>123</code>
<number>1234-456</number>
</phone>
<fax>
<code>123</code>
<number>9999-999</number>
</fax>
</person></pre></div>
<p>It's that simple. Look at how clean the XML is.</p>
<h1 id="from-xml">Deserializing an object back from XML</h1>
<p>To reconstruct an object, purely from the XML:</p>
<div class="Source Java"><pre>Person newJoe = (Person)xstream.fromXML(xml);</pre></div>
<p>And that's how simple XStream is!</p>
<p class="highlight">Note, it is an annoying task to tweak an XStream instance until it can read a given XML format.
You will have a much easier job, if you tweak XStream, until it writes the required XML format. NOrmallyt it will
then also be able to read it.</p>
<h1 id="summary">Summary</h1>
<p>To recap:</p>
<ul>
<li>Create element name to class name aliases for any custom classes using <code style="white-space: nowrap">xstream.alias(String elementName, Class cls);</code></li>
<li>Convert an object to XML using <code style="white-space: nowrap">xstream.toXML(Object obj);</code></li>
<li>Convert XML back to an object using <code style="white-space: nowrap">xstream.fromXML(String xml);</code></li>
</ul>
<p>maybe you like to read the <a href="alias-tutorial.html">alias tutorial</a> to see more possibilities how you can rename things using XStream.
Or look into the condensed overview how to configure XStream to <a href="manual-tweaking-output.html">tweak the output</a>.</p>
<br/>
</div>
</div>
<div class="SidePanel" id="left">
<div class="MenuGroup">
<h1>Software</h1>
<ul>
<li><a href="index.html">About XStream</a></li>
<li><a href="news.html">News</a></li>
<li><a href="changes.html">Change History</a></li>
<li><a href="security.html">Security Aspects</a></li>
<li><a href="versioning.html">About Versioning</a></li>
</ul>
</div>
<div class="MenuGroup">
<h1>Evaluating XStream</h1>
<ul>
<li><a href="tutorial.html">Two Minute Tutorial</a></li>
<li><a href="license.html">License</a></li>
<li><a href="download.html">Download</a></li>
<li><a href="references.html">References</a></li>
<li><a href="benchmarks.html">Benchmarks</a></li>
<li><a href="https://www.openhub.net/p/xstream">Code Statistics</a></li>
</ul>
</div>
<div class="MenuGroup">
<h1>Using XStream</h1>
<ul>
<li><a href="architecture.html">Architecture Overview</a></li>
<li><a href="graphs.html">Object references</a></li>
<li><a href="manual-tweaking-output.html">Tweaking the Output</a></li>
<li><a href="converters.html">Converters</a></li>
<li><a href="faq.html">Frequently Asked Questions</a></li>
<li><a href="mailing-lists.html">Mailing Lists</a></li>
<li><a href="issues.html">Reporting Issues</a></li>
</ul>
</div>
<div class="MenuGroup">
<h1>Javadoc</h1>
<ul>
<li><a href="javadoc/index.html">XStream Core</a></li>
<li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li>
<li><a href="jmh-javadoc/index.html">JMH Module</a></li>
</ul>
</div>
<div class="MenuGroup">
<h1>Tutorials</h1>
<ul>
<li class="currentLink">Two Minute Tutorial</li>
<li><a href="alias-tutorial.html">Alias Tutorial</a></li>
<li><a href="annotations-tutorial.html">Annotations Tutorial</a></li>
<li><a href="converter-tutorial.html">Converter Tutorial</a></li>
<li><a href="objectstream.html">Object Streams Tutorial</a></li>
<li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li>
<li><a href="json-tutorial.html">JSON Tutorial</a></li>
<li><a href="http://www.studytrails.com/java/xml/xstream/xstream-introduction.jsp">StudyTrails</a></li>
</ul>
</div>
<div class="MenuGroup">
<h1>Developing XStream</h1>
<ul>
<li><a href="how-to-contribute.html">How to Contribute</a></li>
<li><a href="team.html">Development Team</a></li>
<li><a href="repository.html">Source Repository</a></li>
<li><a href="https://travis-ci.org/x-stream/xstream/branches">Continuous Integration</a></li>
</ul>
</div>
</div>
</body>
</html>