-
Notifications
You must be signed in to change notification settings - Fork 9
/
architecture.html
270 lines (214 loc) · 13.9 KB
/
architecture.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
261
262
263
264
265
266
267
268
269
270
<!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 - Architecture Overview</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">Architecture Overview</h1>
<p>The architecture of XStream consists of the six main components:</p>
<ul>
<li><b>Converters</b></li>
<li><b>Mappers</b></li>
<li><b>Drivers (Writer and Reader)</b></li>
<li><b>Context</b></li>
<li><b>Type Permissions</b></li>
<li><b>Facade</b></li>
</ul>
<!-- ************ -->
<h1 id="LifeCycle">Life Cycle</h1>
<p>An XStream instance envisages two phases in its life cycle: Setup and Execution. A lot of default configuration is
already applied when an XStream instance is instantiated, i.e. the instance is directly in setup phase. Now is
the time to apply further configuration. This phase is not thread-safe.</p>
<p>Once an instance is properly configured in can be used in an execution phase, where
<a href="graphs.html">Java object graphs</a> are marshalled and unmarshalled. The execution phase is
thread-safe, i.e. is is possible to use an XStream instance concurrently for execution. However, XStream
builds caches during execution based on the configuration. Therefore, an instance should never be reconfigured
during or after execution phase. The result of any further (un-)marshalling might not be what is expected.</p>
<!-- ************ -->
<h1 id="Converters">Converters</h1>
<p>Whenever XStream encounters an object that needs to be converted to/from XML, it delegates to a suitable
<a href="javadoc/com/thoughtworks/xstream/converters/Converter.html">Converter</a> implementation associated
with the class of that Object.</p>
<p>XStream comes <a href="converters.html">bundled with many converters</a> for common types, including primitives,
String, Collections, arrays, null, Date, etc.</p>
<p>XStream also has a <i>default Converter</i>, that is used when no other Converters match a type. This uses
reflection to automatically generate the XML for all the fields in an object.</p>
<p>If an object is composed of other objects, the Converter may delegate to other Converters.</p>
<p class="highlight">To customize the XML for particular object type a new Converter should be implemented.</p>
<!-- ************ -->
<h1 id="Mappers">Mappers</h1>
<p><a href="javadoc/com/thoughtworks/xstream/mapper/Mapper.html">Mapper</a> implementations are the key
components to map between names used in XML and names of Java elements and vice versa. Mappers are organized
in a chain, e.g. every time a mapper cannot map a special name it delegates the call to its logical parent.
Mappers keep the configuration in XStream and a converter should always use the Mapper (chain) of XStream to
map names it has to deal with.</p>
<p>XStream comes bundled with many mappers to map names of ordinary Java types and elements, of arrays, enums,
proxies, outer classes, to handle alias definitions, implicit collections, and ignored elements and even the
<a href="security.html#framework">Security Framework</a> is based on a Mapper implementation.</p>
<p class="highlight">Overwrite XStream's <em>wrapMapper</em> function to add custom mapper implementation.</p>
<!-- ************ -->
<h1 id="Drivers">Drivers (Writer and Reader)</h1>
<p>XStream is abstracted from the underlying XML data using the
<a href="javadoc/com/thoughtworks/xstream/io/HierarchicalStreamWriter.html">HierarchicalStreamWriter</a>
and <a href="javadoc/com/thoughtworks/xstream/io/HierarchicalStreamReader.html">HierarchicalStreamReader</a>
interfaces for serializing and deserializing respectively.</p>
<p>This abstraction allows XStream to read XML from direct streams using an XML parser or directly manipulate
existing structures (such as DOM). This prevents the overhead of having to reparse if XStream is working from
XML that has been partially processed by other libraries (for instance a SOAP library). It also avoids tying XStream
to a particular library.</p>
<p>XStream comes bundled with
<a href="javadoc/com/thoughtworks/xstream/io/xml/package-summary.html">reader and writer implementations</a> for
most major XML libraries.</p>
<p class="highlight">Writer and Readers can be implemented allowing XStream to serialize to most XML APIs.
Writers and Readers can also be created around tree based non XML structures.</p>
<!--
note: one reader/writer per context
note: why not sax
-->
<!-- ************ -->
<h1 id="Context">Context</h1>
<p>When XStream serializes or deserializes some objects, it creates a
<a href="javadoc/com/thoughtworks/xstream/converters/MarshallingContext.html">MarshallingContext</a> or
<a href="javadoc/com/thoughtworks/xstream/converters/UnmarshallingContext">UnmarshallingContext</a>,
which handle the traversing of the data and delegation to the necessary Converters.</p>
<p class="highlight">The MarshallingContext/UnmarshallingContext is made available to converters allowing them
to tell XStream to process objects contained within other objects.</p>
<p>XStream provides three pairs of context implementations that traverse the object graph with slightly
different behaviors. The default can be changed using
<a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream.setMode()</a>, passing in one of
the following parameters:</p>
<ul>
<li>
<b>XStream.XPATH_RELATIVE_REFERENCES</b><br/>
<i>(Default)</i> Uses relative XPath references to signify duplicate references. This produces XML with
the least clutter.
</li>
<li>
<b>XStream.XPATH_ABSOLUTE_REFERENCES</b><br/>
Uses absolute XPath references to signify duplicate references. This might produce for some situations
better readable XML. <i>Note, that XStream will read XML with relative paths as well as with absolute
paths independent of the XPATH mode.</i>
</li>
<li>
<b>XStream.ID_REFERENCES</b><br/>
Uses ID references to signify duplicate references. In some scenarios, such as when using hand-written
XML, this is easier to work with.
</li>
<li>
<b>XStream.NO_REFERENCES</b><br/>
This disables object graph support and treats the object structure like a tree. Duplicate references are
treated as two separate objects and circular references cause an exception. This is slightly faster and
uses less memory than the other two modes.
</li>
</ul>
<p class="highlight">A new context is created for each object graph that is serialized. Both the
<a href="javadoc/com/thoughtworks/xstream/converters/MarshallingContext.html">MarshallingContext</a> and
<a href="javadoc/com/thoughtworks/xstream/converters/UnmarshallingContext.html">UnmarshallingContext</a>
implement <a href="javadoc/com/thoughtworks/xstream/converters/DataHolder.html">DataHolder</a>,
a hash table passed around whilst processing the object graph that can be used as the user sees fit (in a similar
way that the HttpServletRequest attributes are used in a web-application).</p>
<!-- ************ -->
<h1 id="TypePermissions">Type Permissions</h1>
<p>XStream's <a href="security.html#framework">Security Framework</a> consists of a Mapper implementation and
a lot of <a href="javadoc/com/thoughtworks/xstream/security/TypePermission.html">type permissions</a>. These
implementations are used to deny or allow the deserialization of java types based on their name or type
hierarchy.</p>
<!-- ************ -->
<h1 id="Facade">XStream facade</h1>
<p>The main <a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream</a> class is typically used as the
entry point. This assembles the necessary components of XStream (as described above; Context, Converter,
Writer/Reader and ClassMapper) and provides a simple to use API for common operations.</p>
<p class="highlight">Remember, the XStream class is just a facade - it can always be bypassed for more advanced
operations.</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 class="currentLink">Architecture Overview</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><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>