-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathjson-tutorial.html
260 lines (198 loc) · 12.1 KB
/
json-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
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
<!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 - JSON 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">JSON Tutorial</h1>
<p>Due to XStream's flexible architecture, handling of JSON mappings is as easy as handling of XML documents. All you
have to do is to initialize XStream object with an appropriate driver and you are ready to serialize your objects to
(and from) JSON.</p>
<p>XStream currently delivers two drivers for JSON: The
<a href="javadoc/com/thoughtworks/xstream/io/json/JsonHierarchicalStreamDriver.html">JsonHierarchicalStreamDriver</a>
and the <a href="javadoc/com/thoughtworks/xstream/io/json/JettisonMappedXmlDriver.html">JettisonMappedXmlDriver</a>.
The first one does not have an additional dependency, but can only be used to write XML, while the second one is based
on Jettison and can also deserialize JSON to Java objects again. However, since the JettisonMappedXmlDriver transforms
plain XML into JSON, you might get better JSON strings with the JsonHierarchicalStreamDriver, because this driver knows
often about the type of the written data and can act properly.</p>
<p class="highlight">One word of warning. JSON is made for an easy data transfer between systems and languages. It's
syntax offers much less possibilities to express certain data structures. It supports name/value pairs of primitive
data types, arrays and lists and allows to nest them - but that's it! No references, no possibility for meta data
(attributes), no properties with same names (as generated for implicit collections), etc. Therefore do not expect
wonders. XStream (and Jettison) try their best, but the procedure to convert any kind of object into JSON is a lossy
transformation and especially deserialization will not be possible for any construct. See also
<a href="faq.html#JSON_limitations">FAQ for JSON limitations</a>. Also note that any number value in JavaScript is a
64-bit double precision float value according IEEE 754 standard. In consequence it is not possible to represent all
values of a Java long type without loss of precision. See again <a href="faq.html#JSON_JavaScript_Long">FAQ for JSON
and JavaScript</a>.</p>
<p>Since JSON has no possibility to express references, you should always set the NO_REFERENCES mode writing JSON.</p>
<h1 id="jettison">Jettison driver</h1>
<p>Jettison driver uses <a href="https://github.com/jettison-json">Jettison</a> StAX parser to read and write data in JSON
format. It is available in XStream since version 1.2.2 and is implemented in
<code>com.thoughtworks.xstream.io.json.JettisonMappedXmlDriver</code> class. To successfully use this driver you need
to have the Jettison project and StAX API in your classpath (see reference for
<a href="download.html#optional-deps">optional dependencies</a>).</p>
<p>Alternatively you can download JARs manually.</p>
<p>Here are a few simple examples:</p>
<h2 id="jettison-write">Write to JSON with the Jettison-based implementation</h2>
<p>The following example:</p>
<div class="Source Java"><pre>package com.thoughtworks.xstream.json.test;
import com.thoughtworks.xstream.XStream;
import com.thoughtworks.xstream.io.json.JettisonMappedXmlDriver;
public class WriteTest {
public static void main(String[] args) {
Product product = new Product("Banana", "123", 23.00);
XStream xstream = new XStream(new JettisonMappedXmlDriver());
xstream.setMode(XStream.NO_REFERENCES);
xstream.alias("product", Product.class);
System.out.println(xstream.toXML(product));
}
}</pre></div>
<p>produces the following JSON document:</p>
<div class="Source Java"><pre>{"product":{"name":"Banana","id":123,"price":23.0}}</pre></div>
<p>As you can see, all standard XStream features (such as aliases) can be used with this driver.</p>
<p class="highlight">Note that Jettison will try to detect numerical values and omit the quotes. Since Jettison
cannot know about the original data type, it has to guess. Hence it will therefore also write the value of the id
field as numeric value in future.</p>
<h2 id="json-write">Write to JSON with the self-contained JSON driver</h2>
<p>The only difference to the example above is the line with the initialization:</p>
<div class="Source Java"><pre>XStream xstream = new XStream(new JsonHierarchicalStreamDriver());</pre></div>
<p>The output is as follows:</p>
<div class="Source Java"><pre>{"product": {
"name": "Banana",
"id": "123",
"price": 23.0
}}</pre></div>
<p>While the difference because of line feeds is immediately obvious, you have to note also the value of the
<em>id</em> element. This time the driver knew about the string value and therefore quotes were generated.</p>
<h2 id="json-dropping-root">Write to JSON with the self-contained JSON driver dropping the root</h2>
<p>Sometimes the root node in the generated JSON is superfluous, since its name is caused by the Java type
of the written object that has no meaning in JSON and increases only the nesting level of the structure. Therefore
it is possible to drop this root by initializing the internally used
<a href="javadoc/com/thoughtworks/xstream/io/json/JsonWriter.html">JsonWriter</a> in a different mode.
Again, the only difference to the example above is the line with the initialization:</p>
<div class="Source Java"><pre>XStream xstream = new XStream(new JsonHierarchicalStreamDriver() {
public HierarchicalStreamWriter createWriter(Writer writer) {
return new JsonWriter(writer, JsonWriter.DROP_ROOT_MODE);
}
});</pre></div>
<p>The output is as follows:</p>
<div class="Source Java"><pre>{
"name": "Banana",
"id": "123",
"price": 23.0
}</pre></div>
<p class="highlight">Note, that it is now possible to create invalid JSON if XStream should marshal a single object
with a single value to JSON (like String, int, URL, ...). JSON requires that the root is actually an object, but by
dropping the root all that is generated is a single value. You can force the JsonWriter to throw a ConversionException
in this case, see Javadoc of the JsonWriter.</p>
<h2 id="jettison-read">Read from JSON</h2>
<p>The following code:</p>
<div class="Source Java"><pre>package com.thoughtworks.xstream.json.test;
import com.thoughtworks.xstream.XStream;
import com.thoughtworks.xstream.io.json.JettisonMappedXmlDriver;
public class ReadTest {
public static void main(String[] args) {
String json = "{\"product\":{\"name\":\"Banana\",\"id\":123"
+ ",\"price\":23.0}}";
XStream xstream = new XStream(new JettisonMappedXmlDriver());
xstream.alias("product", Product.class);
Product product = (Product)xstream.fromXML(json);
System.out.println(product.getName());
}
}</pre></div>
<p>serializes JSON document created with preceding example back to Java object. It prints:</p>
<div class="Source Java"><pre>Banana</pre></div>
<p>as a result.</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><a href="tutorial.html">Two Minute Tutorial</a></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 class="currentLink">JSON Tutorial</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>