/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
- <!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 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 four main components:</p>
- <ul>
- <li><b>Converters</b></li>
- <!-- TODO: Mappers -->
- <li><b>Drivers (Writer and Reader)</b></li>
- <li><b>Context</b></li>
- <li><b>Facade</b></li>
- </ul>
- <!-- ************ -->
- <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="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="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="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="graphs.html">Object references</a></li>
- <li><a href="manual-tweaking-output.html">Tweaking the Output</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="parser-benchmarks.html">Parser Benchmarks</a></li>
- <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li>
- </ul>
- </div>
- <div class="MenuGroup">
- <h1>Using XStream</h1>
- <ul>
- <li class="currentLink">Architecture Overview</li>
- <li><a href="converters.html">Converters</a></li>
- <li><a href="faq.html">Frequently Asked Questions</a></li>
- <li><a href="list-user.html">Users' Mailing List</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="benchmark-javadoc/index.html">Benchmark 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>
- </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="list-dev.html">Developers' Mailing List</a></li>
- <li><a href="team.html">Development Team</a></li>
- <li><a href="repository.html">Source Repository</a></li>
- <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li>
- </ul>
- </div>
- </div>
- </body>
- </html>