PageRenderTime 35ms CodeModel.GetById 13ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

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

http://prototipomemoria.googlecode.com/
HTML | 232 lines | 166 code | 45 blank | 21 comment | 0 complexity | f38d57dea0a2f98f3579793f5359a5b6 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 - Architecture Overview</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">Architecture Overview</h1>
 39
 40                
 41
 42        <p>The architecture of XStream consists of the four main components:</p>
 43
 44        <ul>
 45            <li><b>Converters</b></li>
 46            <!--  TODO: Mappers -->
 47            <li><b>Drivers (Writer and Reader)</b></li>
 48            <li><b>Context</b></li>
 49            <li><b>Facade</b></li>
 50        </ul>
 51
 52        <!-- ************ -->
 53
 54        <h1 id="Converters">Converters</h1>
 55
 56        <p>Whenever XStream encounters an object that needs to be converted to/from XML, it delegates to a suitable
 57        <a href="javadoc/com/thoughtworks/xstream/converters/Converter.html">Converter</a> implementation associated
 58        with the class of that Object.</p>
 59
 60        <p>XStream comes <a href="converters.html">bundled with many converters</a> for common types, including primitives,
 61        String, Collections, arrays, null, Date, etc.</p>
 62
 63        <p>XStream also has a <i>default Converter</i>, that is used when no other Converters match a type. This uses
 64        reflection to automatically generate the XML for all the fields in an object.</p>
 65
 66        <p>If an object is composed of other objects, the Converter may delegate to other Converters.</p>
 67
 68        <p class="highlight">To customize the XML for particular object type a new Converter should be implemented.</p>
 69
 70
 71        <!-- ************ -->
 72
 73        <h1 id="Drivers">Drivers (Writer and Reader)</h1>
 74
 75        <p>XStream is abstracted from the underlying XML data using the
 76        <a href="javadoc/com/thoughtworks/xstream/io/HierarchicalStreamWriter.html">HierarchicalStreamWriter</a>
 77        and <a href="javadoc/com/thoughtworks/xstream/io/HierarchicalStreamReader.html">HierarchicalStreamReader</a>
 78        interfaces for serializing and deserializing respectively.</p>
 79
 80        <p>This abstraction allows XStream to read XML from direct streams using an XML parser or directly manipulate
 81        existing structures (such as DOM). This prevents the overhead of having to reparse if XStream is working from
 82        XML that has been partially processed by other libraries (for instance a SOAP library). It also avoids tying XStream
 83        to a particular library.</p>
 84
 85        <p>XStream comes bundled with
 86        <a href="javadoc/com/thoughtworks/xstream/io/xml/package-summary.html">reader and writer implementations</a> for
 87        most major XML libraries.</p>
 88
 89        <p class="highlight">Writer and Readers can be implemented allowing XStream to serialize to most XML APIs.
 90        Writers and Readers can also be created around tree based non XML structures.</p>
 91
 92        <!--
 93            note: one reader/writer per context
 94            note: why not sax
 95        -->
 96
 97        <!-- ************ -->
 98
 99        <h1 id="Context">Context</h1>
100
101        <p>When XStream serializes or deserializes some objects, it creates a
102        <a href="javadoc/com/thoughtworks/xstream/converters/MarshallingContext.html">MarshallingContext</a> or
103        <a href="javadoc/com/thoughtworks/xstream/converters/UnmarshallingContext">UnmarshallingContext</a>,
104        which handle the traversing of the data and delegation to the necessary Converters.</p>
105
106        <p class="highlight">The MarshallingContext/UnmarshallingContext is made available to converters allowing them
107        to tell XStream to process objects contained within other objects.</p>
108
109        <p>XStream provides three pairs of context implementations that traverse the object graph with slightly
110        different behaviors. The default can be changed using
111        <a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream.setMode()</a>, passing in one of
112        the following parameters:</p>
113
114        <ul>
115            <li>
116                <b>XStream.XPATH_RELATIVE_REFERENCES</b><br/>
117                <i>(Default)</i> Uses relative XPath references to signify duplicate references. This produces XML with 
118                the least clutter.
119            </li>
120            <li>
121                <b>XStream.XPATH_ABSOLUTE_REFERENCES</b><br/>
122                Uses absolute XPath references to signify duplicate references. This might produce for some situations
123                better readable XML. <i>Note, that XStream will read XML with relative paths as well as with absolute
124                paths independent of the XPATH mode.</i>
125            </li>
126            <li>
127                <b>XStream.ID_REFERENCES</b><br/>
128                Uses ID references to signify duplicate references. In some scenarios, such as when using hand-written
129                XML, this is easier to work with.
130            </li>
131            <li>
132                <b>XStream.NO_REFERENCES</b><br/>
133                This disables object graph support and treats the object structure like a tree. Duplicate references are
134                treated as two separate objects and circular references cause an exception. This is slightly faster and
135                uses less memory than the other two modes.
136            </li>
137        </ul>
138
139        <p class="highlight">A new context is created for each object graph that is serialized. Both the
140        <a href="javadoc/com/thoughtworks/xstream/converters/MarshallingContext.html">MarshallingContext</a> and
141        <a href="javadoc/com/thoughtworks/xstream/converters/UnmarshallingContext.html">UnmarshallingContext</a>
142        implement <a href="javadoc/com/thoughtworks/xstream/converters/DataHolder.html">DataHolder</a>,
143        a hash table passed around whilst processing the object graph that can be used as the user sees fit (in a similar
144        way that the HttpServletRequest attributes are used in a web-application).</p>
145
146
147        <!-- ************ -->
148
149        <h1 id="Facade">XStream facade</h1>
150
151        <p>The main <a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream</a> class is typically used as the
152        entry point. This assembles the necessary components of XStream (as described above; Context, Converter,
153        Writer/Reader and ClassMapper) and provides a simple to use API for common operations.</p>
154
155        <p class="highlight">Remember, the XStream class is just a facade - it can always be bypassed for more advanced
156        operations.</p>
157
158
159    
160
161                <br/>
162
163            </div>
164        </div>
165
166        <div class="SidePanel" id="left">
167                <div class="MenuGroup">
168                    <h1>Software</h1>
169                    <ul>
170                                <li><a href="index.html">About XStream</a></li>
171                                <li><a href="news.html">News</a></li>
172                                <li><a href="changes.html">Change History</a></li>
173                                <li><a href="versioning.html">About Versioning</a></li>
174                    </ul>
175                </div>
176                <div class="MenuGroup">
177                    <h1>Evaluating XStream</h1>
178                    <ul>
179                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
180                                <li><a href="graphs.html">Object references</a></li>
181                                <li><a href="manual-tweaking-output.html">Tweaking the Output</a></li>
182                                <li><a href="license.html">License</a></li>
183                                <li><a href="download.html">Download</a></li>
184                                <li><a href="references.html">References</a></li>
185                                <li><a href="parser-benchmarks.html">Parser Benchmarks</a></li>
186                                <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li>
187                    </ul>
188                </div>
189                <div class="MenuGroup">
190                    <h1>Using XStream</h1>
191                    <ul>
192                                <li class="currentLink">Architecture Overview</li>
193                                <li><a href="converters.html">Converters</a></li>
194                                <li><a href="faq.html">Frequently Asked Questions</a></li>
195                                <li><a href="list-user.html">Users' Mailing List</a></li>
196                                <li><a href="issues.html">Reporting Issues</a></li>
197                    </ul>
198                </div>
199                <div class="MenuGroup">
200                    <h1>Javadoc</h1>
201                    <ul>
202                                <li><a href="javadoc/index.html">XStream Core</a></li>
203                                <li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li>
204                                <li><a href="benchmark-javadoc/index.html">Benchmark Module</a></li>
205                    </ul>
206                </div>
207                <div class="MenuGroup">
208                    <h1>Tutorials</h1>
209                    <ul>
210                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
211                                <li><a href="alias-tutorial.html">Alias Tutorial</a></li>
212                                <li><a href="annotations-tutorial.html">Annotations Tutorial</a></li>
213                                <li><a href="converter-tutorial.html">Converter Tutorial</a></li>
214                                <li><a href="objectstream.html">Object Streams Tutorial</a></li>
215                                <li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li>
216                                <li><a href="json-tutorial.html">JSON Tutorial</a></li>
217                    </ul>
218                </div>
219                <div class="MenuGroup">
220                    <h1>Developing XStream</h1>
221                    <ul>
222                                <li><a href="how-to-contribute.html">How to Contribute</a></li>
223                                <li><a href="list-dev.html">Developers' Mailing List</a></li>
224                                <li><a href="team.html">Development Team</a></li>
225                                <li><a href="repository.html">Source Repository</a></li>
226                                <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li>
227                    </ul>
228                </div>
229        </div>
230
231  </body>
232</html>