/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. 

  2. <html xmlns="http://www.w3.org/1999/xhtml">
    3. 

  3. <!--
    4. 

  4.  Copyright (C) 2005, 2006 Joe Walnes.
    5. 

  5.  Copyright (C) 2006, 2007, 2008 XStream committers.
    6. 

  6.  All rights reserved.
    7. 

  7.  
    8. 

  8.  The software in this package is published under the terms of the BSD
    9. 

  9.  style license a copy of which has been included with this distribution in
    10. 

  10.  the LICENSE.txt file.
    11. 

  11.  
    12. 

  12.  Created on 29. January 2005 by Joe Walnes
    13. 

  13.  -->
    14. 

  14.     <head>
    15. 

  15.         <title>XStream - Object references</title>
    16. 

  16.         <link rel="stylesheet" type="text/css" href="style.css"/>
    17. 

  17.         
    18. 

  18.     
    19. 

  19.   
    20. 

  20. 

  21.         <!-- Google analytics -->
    22. 

  22.         <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
    23. 

  23.         </script>
    24. 

  24.         <script type="text/javascript">
    25. 

  25.           _uacct = "UA-110973-2";
    26. 

  26.           urchinTracker();
    27. 

  27.         </script>
    28. 

  28. 

  29.     </head>
    30. 

  30.     <body>
    31. 

  31. 

  32.         <div id="banner">
    33. 

  33.             <a href="index.html"><img id="logo" src="logo.gif" alt="XStream"/></a>
    34. 

  34.         </div>
    35. 

  35. 

  36.         <div id="center" class="Content2Column">  <!-- Content3Column for index -->
    37. 

  37.             <div id="content">
    38. 

  38.                 <h1 class="FirstChild">Object references</h1>
    39. 

  39. 

  40.                 
    41. 

  41. 

  42.     <!-- ...................................................... -->
    43. 

  43.     <h2 id="references">How does XStream deals with duplicate and circular references?</h2>
    44. 

  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. 

  45.     
    46. 

  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. 

  47.     <p>We start with a simple compact-disc class, with id and a bonus cd fields:</p>
    48. 

  48.     
    49. 

  49. <div class="Source Java"><pre>package com.thoughtworks.xstream;
    50. 

  50. public class Cd {
    51. 

  51. 	private String id;
    52. 

  52. 

  53. 	private Cd bonusCd;
    54. 

  54. 

  55. 	Cd(String id, Cd bonusCd) {
    56. 

  56. 		this.id = id;
    57. 

  57. 		this.bonusCd = bonusCd;
    58. 

  58. 	}
    59. 

  59. 

  60. 	Cd(String id) {
    61. 

  61. 		this.id = id;
    62. 

  62. 	}
    63. 

  63. 

  64. 	public String getId() {
    65. 

  65. 		return id;
    66. 

  66. 	}
    67. 

  67. 

  68. 	public Cd getBonusCd() {
    69. 

  69. 		return bonusCd;
    70. 

  70. 	}
    71. 

  71. }</pre></div>
    72. 

  72. 

  73. 	<p>And let's create an order with the same cd twice and the order itself, so we can simulate
    74. 

  74.  two references to the same object and a back-reference.</p>
    75. 

  75.  
    76. 

  76. <div class="Source Java"><pre>Cd bj = new Cd("basement_jaxx_singles");
    77. 

  77. 		
    78. 

  78. List order = new ArrayList();
    79. 

  79. // adds the same cd twice (two references to the same object)
    80. 

  80. order.add(bj);
    81. 

  81. order.add(bj);
    82. 

  82. 

  83. // adds itself (cycle)
    84. 

  84. order.add(order);
    85. 

  85. 

  86. XStream xstream = new XStream();
    87. 

  87. xstream.alias("cd", Cd.class);
    88. 

  88. System.out.println(xstream.toXML(order));
    89. 

  89. </pre></div>
    90. 

  90. 

  91. 	<p>If we execute the above code, XStream's uses its <b>default mode</b> called XPATH_RELATIVE_REFERENCES
    92. 

  92. 	based on the W3C XPath specification. Cross and back references are treated in a way that it's (almost) human
    93. 

  93. readable:</p>
    94. 

  94. 

  95. <div class="Source Java"><pre>
    96. 

  96. &lt;list&gt;
    97. 

  97.   &lt;cd&gt;
    98. 

  98.     &lt;id&gt;maria rita&lt;/id&gt;
    99. 

  99.   &lt;/cd&gt;
    100. 

  100.   &lt;cd&gt;
    101. 

  101.     &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
    102. 

  102.   &lt;/cd&gt;
    103. 

  103.   &lt;cd reference="../cd[2]"/&gt;
    104. 

  104.   &lt;list reference=".."/&gt;
    105. 

  105. &lt;/list&gt;
    106. 

  106. </pre></div>
    107. 

  107. 

  108. 	<p>The second reference to the Basement Jaxx cd was serialized as "../cd[2]" while the order inside
    109. 

  109. itself used the ".." path. The XPath Relative mode allows any type of graphs to be used as both cross and
    110. 

  110. back-references are supported.</p>
    111. 

  111. 

  112. 	<p>In order to make use of the XPath Relative mode one can implicitly call:</p>
    113. 

  113. 	
    114. 

  114. <div class="Source Java"><pre>
    115. 

  115. xstream.setMode(XStream.XPATH_RELATIVE_REFERENCES);
    116. 

  116. </pre></div>
    117. 

  117. 

  118.     <!-- ...................................................... -->
    119. 

  119.     <h2 id="rel-abs">Relative x Absolute</h2>
    120. 

  120.     
    121. 

  121.     <p>There is an absolute mode which is easy to use and understand. It works
    122. 

  122. using the same XPath specification and also supports all types of graphs.</p>
    123. 

  123. 

  124. <div class="Source Java"><pre>
    125. 

  125. xstream.setMode(XStream.XPATH_ABSOLUTE_REFERENCES);
    126. 

  126. </pre></div>
    127. 

  127. 

  128. 	<p>The changes in the resulting xml is a little more 'clutter':</p>
    129. 

  129. 

  130. <div class="Source Java"><pre>
    131. 

  131. &lt;list&gt;
    132. 

  132.   &lt;cd&gt;
    133. 

  133.     &lt;id&gt;maria rita&lt;/id&gt;
    134. 

  134.   &lt;/cd&gt;
    135. 

  135.   &lt;cd&gt;
    136. 

  136.     &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
    137. 

  137.   &lt;/cd&gt;
    138. 

  138.   &lt;cd reference="/list/cd[2]"/&gt;
    139. 

  139.   &lt;list reference="/list"/&gt;
    140. 

  140. &lt;/list&gt;
    141. 

  141. </pre></div>
    142. 

  142. 

  143. 

  144.     <!-- ...................................................... -->
    145. 

  145.     <h2 id="single-node">Single Node Selectors</h2>
    146. 

  146. 

  147. 	<p>In some cases where the XML is used later on or is generated by someone else, the
    148. 

  148. 	XPath selectors can be forced to select always a single node instead of a node list where
    149. 

  149. 	the first element is taken. Therefore two more modes exist:</p>
    150. 

  150. 

  151. <div class="Source Java"><pre>
    152. 

  152. xstream.setMode(XStream.SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES);
    153. 

  153. xstream.setMode(XStream.SINGLE_NODE_XPATH_RELATIVE_REFERENCES);
    154. 

  154. </pre></div>
    155. 

  155. 

  156. 	<p>The changes in the resulting xml is even more 'clutter':</p>
    157. 

  157. 

  158. <div class="Source Java"><pre>
    159. 

  159. &lt;list&gt;
    160. 

  160.   &lt;cd&gt;
    161. 

  161.     &lt;id&gt;maria rita&lt;/id&gt;
    162. 

  162.   &lt;/cd&gt;
    163. 

  163.   &lt;cd&gt;
    164. 

  164.     &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
    165. 

  165.   &lt;/cd&gt;
    166. 

  166.   &lt;cd reference="/list[1]/cd[2]"/&gt;
    167. 

  167.   &lt;list reference="/list[1]"/&gt;
    168. 

  168. &lt;/list&gt;
    169. 

  169. </pre></div>
    170. 

  170. 

  171. 	<p>For XStream is the notation with the single node selectors absolutely equivalent to the
    172. 

  172. 	one without. These two notations are completely transparent at deserialization time.</p>
    173. 

  173. 

  174.     <!-- ...................................................... -->
    175. 

  175.     <h2 id="ids">Id mode</h2>
    176. 

  176.     
    177. 

  177. 	<p>Both modes displayed until now are not so easy to write by hand. XStream has another
    178. 

  178. 	mode which makes it is easier to read/write by a human being:</p>
    179. 

  179. 

  180. <div class="Source Java"><pre>
    181. 

  181. xstream.setMode(XStream.ID_REFERENCES);
    182. 

  182. </pre></div>
    183. 

  183. 

  184. 	<p>The result is a XML which generates an "id" attribute for each new object marshaled, 
    185. 

  185. 	and whenever it finds back or cross-references, it uses a "reference" attribute to so
    186. 

  186. 	it doesn't copy the entire object.</p>
    187. 

    188. 

  188. 	<p>In our example, the list has id 1, the Maria Rita cd 2, and the Basement Jaxx 3. Therefore
    189. 

  189. 	the cross-reference to our cd should contain a reference attribute to object number 2 and
    190. 

  190. 	the back-reference to our order a reference to object 1. The result is:</p>
    191. 

  191. 

  192. <div class="Source Java"><pre>
    193. 

  193. &lt;list id="1"&gt;
    194. 

  194.   &lt;cd id="2"&gt;
    195. 

  195.     &lt;id&gt;maria rita&lt;/id&gt;
    196. 

  196.   &lt;/cd&gt;
    197. 

  197.   &lt;cd id="3"&gt;
    198. 

  198.     &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
    199. 

  199.   &lt;/cd&gt;
    200. 

  200.   &lt;cd reference="3"/&gt;
    201. 

  201.   &lt;list reference="1"/&gt;
    202. 

  202. &lt;/list&gt;
    203. 

  203. </pre></div>
    204. 

  204. 

  205.     <!-- ...................................................... -->
    206. 

  206.     <h2>No references</h2>
    207. 

  207.     
    208. 

  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. 

  209. 	tree. The most famous example is when using XStream to generate XML for B2B services.</p>
    210. 

  210. 

  211. 	<p>In such scenarios it's impossible to represent a graph cycle (remember: no tree contains such structure), therefore
    212. 

  212. 	we have to remove the last <b>add</b> call from our example:</p>
    213. 

  213. 	
    214. 

  214. <div class="Source Java"><pre>Cd bj = new Cd("basement_jaxx_singles");
    215. 

  215. 		
    216. 

  216. List order = new ArrayList();
    217. 

  217. // adds the same cd twice (two references to the same object)
    218. 

  218. order.add(bj);
    219. 

  219. order.add(bj);
    220. 

  220. 

  221. XStream xstream = new XStream();
    222. 

  222. xstream.alias("cd", Cd.class);
    223. 

  223. System.out.println(xstream.toXML(order));
    224. 

  224. </pre></div>
    225. 

  225. 

  226. 	<p>Now if we add the NO_REFERENCES option, every reference shall be completed serialized.</p>
    227. 

  227. 

  228. <div class="Source Java"><pre>
    229. 

  229. xstream.setMode(XStream.NO_REFERENCES);
    230. 

  230. </pre></div>
    231. 

  231. 

  232. 	<p>The result are three references:</p>
    233. 

  233. 

  234. <div class="Source Java"><pre>
    235. 

  235. &lt;list&gt;
    236. 

  236.   &lt;cd&gt;
    237. 

  237.     &lt;id&gt;maria rita&lt;/id&gt;
    238. 

  238.   &lt;/cd&gt;
    239. 

  239.   &lt;cd&gt;
    240. 

  240.     &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
    241. 

  241.   &lt;/cd&gt;
    242. 

  242.   &lt;cd&gt;
    243. 

  243.     &lt;id&gt;basement_jaxx_singles&lt;/id&gt;
    244. 

  244.   &lt;/cd&gt;
    245. 

  245. &lt;/list&gt;
    246. 

  246. </pre></div>
    247. 

  247. 

  248. 	<p>After reading from the above XML, you will get three <b>different</b> Cd instances.</p>
    249. 

  249. 	
    250. 

  250. 	<p>Remember: it's impossible to support back-references (cycles) with NO_REFERENCES mode activated therefore
    251. 

  251. 	a CircularReferenceException is thrown if you ever try to do so.</p>
    252. 

  252. 	
    253. 

  253.   
    254. 

  254. 

  255.                 <br/>
    256. 

  256. 

  257.             </div>
    258. 

  258.         </div>
    259. 

  259. 

  260.         <div class="SidePanel" id="left">
    261. 

  261.                 <div class="MenuGroup">
    262. 

  262.                     <h1>Software</h1>
    263. 

  263.                     <ul>
    264. 

  264.                                 <li><a href="index.html">About XStream</a></li>
    265. 

  265.                                 <li><a href="news.html">News</a></li>
    266. 

  266.                                 <li><a href="changes.html">Change History</a></li>
    267. 

  267.                                 <li><a href="versioning.html">About Versioning</a></li>
    268. 

  268.                     </ul>
    269. 

  269.                 </div>
    270. 

  270.                 <div class="MenuGroup">
    271. 

  271.                     <h1>Evaluating XStream</h1>
    272. 

  272.                     <ul>
    273. 

  273.                                 <li><a href="tutorial.html">Two Minute Tutorial</a></li>
    274. 

  274.                                 <li class="currentLink">Object references</li>
    275. 

  275.                                 <li><a href="manual-tweaking-output.html">Tweaking the Output</a></li>
    276. 

  276.                                 <li><a href="license.html">License</a></li>
    277. 

  277.                                 <li><a href="download.html">Download</a></li>
    278. 

  278.                                 <li><a href="references.html">References</a></li>
    279. 

  279.                                 <li><a href="parser-benchmarks.html">Parser Benchmarks</a></li>
    280. 

  280.                                 <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li>
    281. 

  281.                     </ul>
    282. 

  282.                 </div>
    283. 

  283.                 <div class="MenuGroup">
    284. 

  284.                     <h1>Using XStream</h1>
    285. 

  285.                     <ul>
    286. 

  286.                                 <li><a href="architecture.html">Architecture Overview</a></li>
    287. 

  287.                                 <li><a href="converters.html">Converters</a></li>
    288. 

  288.                                 <li><a href="faq.html">Frequently Asked Questions</a></li>
    289. 

  289.                                 <li><a href="list-user.html">Users' Mailing List</a></li>
    290. 

  290.                                 <li><a href="issues.html">Reporting Issues</a></li>
    291. 

  291.                     </ul>
    292. 

  292.                 </div>
    293. 

  293.                 <div class="MenuGroup">
    294. 

  294.                     <h1>Javadoc</h1>
    295. 

  295.                     <ul>
    296. 

  296.                                 <li><a href="javadoc/index.html">XStream Core</a></li>
    297. 

  297.                                 <li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li>
    298. 

  298.                                 <li><a href="benchmark-javadoc/index.html">Benchmark Module</a></li>
    299. 

  299.                     </ul>
    300. 

  300.                 </div>
    301. 

  301.                 <div class="MenuGroup">
    302. 

  302.                     <h1>Tutorials</h1>
    303. 

  303.                     <ul>
    304. 

  304.                                 <li><a href="tutorial.html">Two Minute Tutorial</a></li>
    305. 

  305.                                 <li><a href="alias-tutorial.html">Alias Tutorial</a></li>
    306. 

  306.                                 <li><a href="annotations-tutorial.html">Annotations Tutorial</a></li>
    307. 

  307.                                 <li><a href="converter-tutorial.html">Converter Tutorial</a></li>
    308. 

  308.                                 <li><a href="objectstream.html">Object Streams Tutorial</a></li>
    309. 

  309.                                 <li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li>
    310. 

  310.                                 <li><a href="json-tutorial.html">JSON Tutorial</a></li>
    311. 

  311.                     </ul>
    312. 

  312.                 </div>
    313. 

  313.                 <div class="MenuGroup">
    314. 

  314.                     <h1>Developing XStream</h1>
    315. 

  315.                     <ul>
    316. 

  316.                                 <li><a href="how-to-contribute.html">How to Contribute</a></li>
    317. 

  317.                                 <li><a href="list-dev.html">Developers' Mailing List</a></li>
    318. 

  318.                                 <li><a href="team.html">Development Team</a></li>
    319. 

  319.                                 <li><a href="repository.html">Source Repository</a></li>
    320. 

  320.                                 <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li>
    321. 

  321.                     </ul>
    322. 

  322.                 </div>
    323. 

  323.         </div>
    324. 

  324. 

  325.   </body>
    326. 

  326. </html>
    327.