/Prototipo/Servlet/lib/xstream-distribution-1.4.1-bin/xstream-1.4.1/docs/graphs.html
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<list> 97 <cd> 98 <id>maria rita</id> 99 </cd> 100 <cd> 101 <id>basement_jaxx_singles</id> 102 </cd> 103 <cd reference="../cd[2]"/> 104 <list reference=".."/> 105</list> 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<list> 132 <cd> 133 <id>maria rita</id> 134 </cd> 135 <cd> 136 <id>basement_jaxx_singles</id> 137 </cd> 138 <cd reference="/list/cd[2]"/> 139 <list reference="/list"/> 140</list> 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<list> 160 <cd> 161 <id>maria rita</id> 162 </cd> 163 <cd> 164 <id>basement_jaxx_singles</id> 165 </cd> 166 <cd reference="/list[1]/cd[2]"/> 167 <list reference="/list[1]"/> 168</list> 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<list id="1"> 194 <cd id="2"> 195 <id>maria rita</id> 196 </cd> 197 <cd id="3"> 198 <id>basement_jaxx_singles</id> 199 </cd> 200 <cd reference="3"/> 201 <list reference="1"/> 202</list> 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<list> 236 <cd> 237 <id>maria rita</id> 238 </cd> 239 <cd> 240 <id>basement_jaxx_singles</id> 241 </cd> 242 <cd> 243 <id>basement_jaxx_singles</id> 244 </cd> 245</list> 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>