PageRenderTime 25ms CodeModel.GetById 12ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/Prototipo/Servlet/lib/xstream-distribution-1.4.1-bin/xstream-1.4.1/docs/graphs.html

http://prototipomemoria.googlecode.com/
HTML | 326 lines | 246 code | 63 blank | 17 comment | 0 complexity | 032f8f73fea4cd1b93eb2877091b3c8e MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  2<html xmlns="http://www.w3.org/1999/xhtml">
  3<!--
  4 Copyright (C) 2005, 2006 Joe Walnes.
  5 Copyright (C) 2006, 2007, 2008 XStream committers.
  6 All rights reserved.
  7 
  8 The software in this package is published under the terms of the BSD
  9 style license a copy of which has been included with this distribution in
 10 the LICENSE.txt file.
 11 
 12 Created on 29. January 2005 by Joe Walnes
 13 -->
 14    <head>
 15        <title>XStream - Object references</title>
 16        <link rel="stylesheet" type="text/css" href="style.css"/>
 17        
 18    
 19  
 20
 21        <!-- Google analytics -->
 22        <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
 23        </script>
 24        <script type="text/javascript">
 25          _uacct = "UA-110973-2";
 26          urchinTracker();
 27        </script>
 28
 29    </head>
 30    <body>
 31
 32        <div id="banner">
 33            <a href="index.html"><img id="logo" src="logo.gif" alt="XStream"/></a>
 34        </div>
 35
 36        <div id="center" class="Content2Column">  <!-- Content3Column for index -->
 37            <div id="content">
 38                <h1 class="FirstChild">Object references</h1>
 39
 40                
 41
 42    <!-- ...................................................... -->
 43    <h2 id="references">How does XStream deals with duplicate and circular references?</h2>
 44    <p>It depends on XStream's mode, the default is uses XPath to allow serialized objects to be treated as graphs instead of simple trees (typical XML usage).</p>
 45    
 46    <p>Sometimes it's not desirable to work this way, let's take a look in a simple example in order to switch between XStream's modes and see what its capable of.</p>
 47    <p>We start with a simple compact-disc class, with id and a bonus cd fields:</p>
 48    
 49<div class="Source Java"><pre>package com.thoughtworks.xstream;
 50public class Cd {
 51	private String id;
 52
 53	private Cd bonusCd;
 54
 55	Cd(String id, Cd bonusCd) {
 56		this.id = id;
 57		this.bonusCd = bonusCd;
 58	}
 59
 60	Cd(String id) {
 61		this.id = id;
 62	}
 63
 64	public String getId() {
 65		return id;
 66	}
 67
 68	public Cd getBonusCd() {
 69		return bonusCd;
 70	}
 71}</pre></div>
 72
 73	<p>And let's create an order with the same cd twice and the order itself, so we can simulate
 74 two references to the same object and a back-reference.</p>
 75 
 76<div class="Source Java"><pre>Cd bj = new Cd("basement_jaxx_singles");
 77		
 78List order = new ArrayList();
 79// adds the same cd twice (two references to the same object)
 80order.add(bj);
 81order.add(bj);
 82
 83// adds itself (cycle)
 84order.add(order);
 85
 86XStream xstream = new XStream();
 87xstream.alias("cd", Cd.class);
 88System.out.println(xstream.toXML(order));
 89</pre></div>
 90
 91	<p>If we execute the above code, XStream's uses its <b>default mode</b> called XPATH_RELATIVE_REFERENCES
 92	based on the W3C XPath specification. Cross and back references are treated in a way that it's (almost) human
 93readable:</p>
 94
 95<div class="Source Java"><pre>
 96&lt;list&gt;
 97  &lt;cd&gt;
 98    &lt;id&gt;maria rita&lt;/id&gt;
 99  &lt;/cd&gt;
100  &lt;cd&gt;
101    &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
102  &lt;/cd&gt;
103  &lt;cd reference="../cd[2]"/&gt;
104  &lt;list reference=".."/&gt;
105&lt;/list&gt;
106</pre></div>
107
108	<p>The second reference to the Basement Jaxx cd was serialized as "../cd[2]" while the order inside
109itself used the ".." path. The XPath Relative mode allows any type of graphs to be used as both cross and
110back-references are supported.</p>
111
112	<p>In order to make use of the XPath Relative mode one can implicitly call:</p>
113	
114<div class="Source Java"><pre>
115xstream.setMode(XStream.XPATH_RELATIVE_REFERENCES);
116</pre></div>
117
118    <!-- ...................................................... -->
119    <h2 id="rel-abs">Relative x Absolute</h2>
120    
121    <p>There is an absolute mode which is easy to use and understand. It works
122using the same XPath specification and also supports all types of graphs.</p>
123
124<div class="Source Java"><pre>
125xstream.setMode(XStream.XPATH_ABSOLUTE_REFERENCES);
126</pre></div>
127
128	<p>The changes in the resulting xml is a little more 'clutter':</p>
129
130<div class="Source Java"><pre>
131&lt;list&gt;
132  &lt;cd&gt;
133    &lt;id&gt;maria rita&lt;/id&gt;
134  &lt;/cd&gt;
135  &lt;cd&gt;
136    &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
137  &lt;/cd&gt;
138  &lt;cd reference="/list/cd[2]"/&gt;
139  &lt;list reference="/list"/&gt;
140&lt;/list&gt;
141</pre></div>
142
143
144    <!-- ...................................................... -->
145    <h2 id="single-node">Single Node Selectors</h2>
146
147	<p>In some cases where the XML is used later on or is generated by someone else, the
148	XPath selectors can be forced to select always a single node instead of a node list where
149	the first element is taken. Therefore two more modes exist:</p>
150
151<div class="Source Java"><pre>
152xstream.setMode(XStream.SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES);
153xstream.setMode(XStream.SINGLE_NODE_XPATH_RELATIVE_REFERENCES);
154</pre></div>
155
156	<p>The changes in the resulting xml is even more 'clutter':</p>
157
158<div class="Source Java"><pre>
159&lt;list&gt;
160  &lt;cd&gt;
161    &lt;id&gt;maria rita&lt;/id&gt;
162  &lt;/cd&gt;
163  &lt;cd&gt;
164    &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
165  &lt;/cd&gt;
166  &lt;cd reference="/list[1]/cd[2]"/&gt;
167  &lt;list reference="/list[1]"/&gt;
168&lt;/list&gt;
169</pre></div>
170
171	<p>For XStream is the notation with the single node selectors absolutely equivalent to the
172	one without. These two notations are completely transparent at deserialization time.</p>
173
174    <!-- ...................................................... -->
175    <h2 id="ids">Id mode</h2>
176    
177	<p>Both modes displayed until now are not so easy to write by hand. XStream has another
178	mode which makes it is easier to read/write by a human being:</p>
179
180<div class="Source Java"><pre>
181xstream.setMode(XStream.ID_REFERENCES);
182</pre></div>
183
184	<p>The result is a XML which generates an "id" attribute for each new object marshaled, 
185	and whenever it finds back or cross-references, it uses a "reference" attribute to so
186	it doesn't copy the entire object.</p>
187
188	<p>In our example, the list has id 1, the Maria Rita cd 2, and the Basement Jaxx 3. Therefore
189	the cross-reference to our cd should contain a reference attribute to object number 2 and
190	the back-reference to our order a reference to object 1. The result is:</p>
191
192<div class="Source Java"><pre>
193&lt;list id="1"&gt;
194  &lt;cd id="2"&gt;
195    &lt;id&gt;maria rita&lt;/id&gt;
196  &lt;/cd&gt;
197  &lt;cd id="3"&gt;
198    &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
199  &lt;/cd&gt;
200  &lt;cd reference="3"/&gt;
201  &lt;list reference="1"/&gt;
202&lt;/list&gt;
203</pre></div>
204
205    <!-- ...................................................... -->
206    <h2>No references</h2>
207    
208	<p>For some uses of XStream we do not desire any kind of back or cross references like a graph, but a simple
209	tree. The most famous example is when using XStream to generate XML for B2B services.</p>
210
211	<p>In such scenarios it's impossible to represent a graph cycle (remember: no tree contains such structure), therefore
212	we have to remove the last <b>add</b> call from our example:</p>
213	
214<div class="Source Java"><pre>Cd bj = new Cd("basement_jaxx_singles");
215		
216List order = new ArrayList();
217// adds the same cd twice (two references to the same object)
218order.add(bj);
219order.add(bj);
220
221XStream xstream = new XStream();
222xstream.alias("cd", Cd.class);
223System.out.println(xstream.toXML(order));
224</pre></div>
225
226	<p>Now if we add the NO_REFERENCES option, every reference shall be completed serialized.</p>
227
228<div class="Source Java"><pre>
229xstream.setMode(XStream.NO_REFERENCES);
230</pre></div>
231
232	<p>The result are three references:</p>
233
234<div class="Source Java"><pre>
235&lt;list&gt;
236  &lt;cd&gt;
237    &lt;id&gt;maria rita&lt;/id&gt;
238  &lt;/cd&gt;
239  &lt;cd&gt;
240    &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
241  &lt;/cd&gt;
242  &lt;cd&gt;
243    &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
244  &lt;/cd&gt;
245&lt;/list&gt;
246</pre></div>
247
248	<p>After reading from the above XML, you will get three <b>different</b> Cd instances.</p>
249	
250	<p>Remember: it's impossible to support back-references (cycles) with NO_REFERENCES mode activated therefore
251	a CircularReferenceException is thrown if you ever try to do so.</p>
252	
253  
254
255                <br/>
256
257            </div>
258        </div>
259
260        <div class="SidePanel" id="left">
261                <div class="MenuGroup">
262                    <h1>Software</h1>
263                    <ul>
264                                <li><a href="index.html">About XStream</a></li>
265                                <li><a href="news.html">News</a></li>
266                                <li><a href="changes.html">Change History</a></li>
267                                <li><a href="versioning.html">About Versioning</a></li>
268                    </ul>
269                </div>
270                <div class="MenuGroup">
271                    <h1>Evaluating XStream</h1>
272                    <ul>
273                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
274                                <li class="currentLink">Object references</li>
275                                <li><a href="manual-tweaking-output.html">Tweaking the Output</a></li>
276                                <li><a href="license.html">License</a></li>
277                                <li><a href="download.html">Download</a></li>
278                                <li><a href="references.html">References</a></li>
279                                <li><a href="parser-benchmarks.html">Parser Benchmarks</a></li>
280                                <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li>
281                    </ul>
282                </div>
283                <div class="MenuGroup">
284                    <h1>Using XStream</h1>
285                    <ul>
286                                <li><a href="architecture.html">Architecture Overview</a></li>
287                                <li><a href="converters.html">Converters</a></li>
288                                <li><a href="faq.html">Frequently Asked Questions</a></li>
289                                <li><a href="list-user.html">Users' Mailing List</a></li>
290                                <li><a href="issues.html">Reporting Issues</a></li>
291                    </ul>
292                </div>
293                <div class="MenuGroup">
294                    <h1>Javadoc</h1>
295                    <ul>
296                                <li><a href="javadoc/index.html">XStream Core</a></li>
297                                <li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li>
298                                <li><a href="benchmark-javadoc/index.html">Benchmark Module</a></li>
299                    </ul>
300                </div>
301                <div class="MenuGroup">
302                    <h1>Tutorials</h1>
303                    <ul>
304                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
305                                <li><a href="alias-tutorial.html">Alias Tutorial</a></li>
306                                <li><a href="annotations-tutorial.html">Annotations Tutorial</a></li>
307                                <li><a href="converter-tutorial.html">Converter Tutorial</a></li>
308                                <li><a href="objectstream.html">Object Streams Tutorial</a></li>
309                                <li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li>
310                                <li><a href="json-tutorial.html">JSON Tutorial</a></li>
311                    </ul>
312                </div>
313                <div class="MenuGroup">
314                    <h1>Developing XStream</h1>
315                    <ul>
316                                <li><a href="how-to-contribute.html">How to Contribute</a></li>
317                                <li><a href="list-dev.html">Developers' Mailing List</a></li>
318                                <li><a href="team.html">Development Team</a></li>
319                                <li><a href="repository.html">Source Repository</a></li>
320                                <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li>
321                    </ul>
322                </div>
323        </div>
324
325  </body>
326</html>