PageRenderTime 28ms CodeModel.GetById 12ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 0ms

/Prototipo/Servlet/lib/xstream-distribution-1.4.1-bin/xstream-1.4.1/docs/manual-tweaking-output.html

http://prototipomemoria.googlecode.com/
HTML | 323 lines | 222 code | 76 blank | 25 comment | 0 complexity | 3fd1be8eccb0ff886bd44a57d4df0dd6 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 - Tweaking the Output</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">Tweaking the Output</h1>
 39
 40                
 41
 42        <p>Out of the box, XStream is able to serialize most objects without the need for custom mappings to be setup.
 43        The XML produced is clean, however sometimes it's desirable to make tweaks to it. The most common use for this is
 44        when using XStream to read configuration files and some more human-friendly XML is needed.</p>
 45
 46        <!-- ************ -->
 47
 48        <h1 id="Configuration">Modification by configuration</h1>
 49        
 50        <p>A big part of the standard output of XStream can be configured. It is possible to set aliases for class types
 51        and field names that are mapped to XML tag or attribute names. Objects that can be represented as simple string
 52        value can be written as attributes. It is possible to omit fields or to flatten the structure for collections.</p>
 53
 54        <!-- .................. -->
 55        
 56        <h2 id="Configuration_Aliases">Aliases</h2>
 57
 58        <p>Aliases offer a simple way to use different tag or attribute names in the XML.  The simplest and most commonly
 59        used tweak in XStream is to alias a fully qualified class to a shorter name.  Another use case is a different field name
 60        for a class member.  Aliases can be set for following elements:</p>
 61
 62		<ul>
 63			<li>Class types mapped to XML tags</li>
 64			<li>Package names mapped to XML tags</li>
 65			<li>Field names mapped to XML tags</li>
 66			<li>Internal attributes names of XStream</li>
 67		</ul>        
 68
 69		<p>The bold elements in the following example are affected:</p>
 70
 71<div class="Source XML"><pre>&lt;<b>cat</b>&gt;
 72  &lt;<b>age</b>&gt;4&lt;/<b>age</b>&gt;
 73  &lt;<b>name</b>&gt;Garfield&lt;/<b>name</b>&gt;
 74  &lt;<b>owner</b> <b>type</b>="<b>StandardPerson</b>"&gt;
 75    &lt;<b>name</b>&gt;Jon Arbuckle&lt;/<b>name</b>&gt;
 76  &lt;/<b>owner</b>&gt;
 77&lt;/<b>cat</b>&gt;</pre></div>
 78
 79        <p>Have a look at the <a href="alias-tutorial.html">Alias Tutorial</a> for examples.</p>
 80
 81        <!-- .................. -->
 82
 83        <h2 id="Configuration_Attributes">Attributes</h2>
 84
 85        <p>XML is quite clumsy to read for fields in separate tags that can represent their content in a short single
 86        string value.  In such a case attributes can help to shorten the XML and increase readability:</p>
 87
 88<div class="Source XML"><pre>&lt;cat <b>age="4" name="Garfield"</b>&gt;
 89  &lt;owner class="StandardPerson" <b>name="Jon Arbuckle"</b>/&gt;
 90&lt;/cat&gt;</pre></div>
 91
 92        <p>Attributes are also presented in the <a href="alias-tutorial.html">Alias Tutorial</a>.</p>
 93          
 94        <!-- .................. -->
 95
 96        <h2 id="Configuration_OmitField">Omitted Fields</h2>
 97		
 98		<p>For a proper deserialization XStream has to write the complete object graph into XML that is referenced by a
 99		single object.  Therefore XStream has to find a representation that contains all aspects to recreate the 
100		objects.</p>
101		
102		<p>However, some parts might be superfluous e.g. if a member field is lazy initialized and its content
103		can be easily recreated.  In such a case a field can be omitted using
104		<a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream.omitField(Class, String)</a>.</p>
105          
106        <!-- .................. -->
107
108        <h2 id="Configuration_ImplicitCollection">Implicit Collections, Arrays and Maps</h2>
109		
110		<p>Another use case are collections, arrays and maps.  If a class has a field that is a one of those types, by
111		default all of its elements are embedded in an element that represents the container object itself.  By
112		configuring the XStream with the
113		<a href="javadoc/com/thoughtworks/xstream/XStream.html#addImplicitCollection">XStream.addImplicitCollection()</a>,
114		<a href="javadoc/com/thoughtworks/xstream/XStream.html#addImplicitArray">XStream.addImplicitArray()</a>, and
115		<a href="javadoc/com/thoughtworks/xstream/XStream.html#addImplicitMap">XStream.addImplicitMap()</a> methods it
116		is possible to keep the elements directly as child of the class and the surrounding tag for the container object
117		is omitted.  It is even possible to declare more than one implicit collection, array or map for a class, but
118		the elements must then be distinguishable to populate the different containers correctly at deserialization.</p>
119		
120		<p>In the following example the Java type representing the farm may have two containers, one for cats and one
121		for dogs:</p>
122		
123<div class="Source XML"><pre>&lt;farm&gt;
124  &lt;<b>cat</b>&gt;Garfield&lt;/<b>cat</b>&gt;
125  &lt;<b>cat</b>&gt;Arlene&lt;/<b>cat</b>&gt;
126  &lt;<b>cat</b>&gt;Nermal&lt;/<b>cat</b>&gt;
127  &lt;<b>dog</b>&gt;Odie&lt;/<b>dog</b>&gt;
128&lt;/farm&gt;</pre></div>
129
130		<p>The container might be a Collection, Array, or even a Map.  In the latter case a member field of the value
131		must have been defined, that is used as key in the deserialized map.</p>
132          
133        <!-- .................. -->
134
135        <h2 id="Configuration_FieldOrder">Field order</h2>
136        
137        <p>XStream is delivered with a lot of <a href="converters.html">converters</a> for standard types.
138        Nevertheless most objects are processed by converters based on reflection.  They will write the fields of a
139        class in the sequence they are defined.  It is possible to implement an algorithm for a different sequence or
140        use an implementation that allows to define the sequence for each type separately using a
141        <a href="javadoc/com/thoughtworks/xstream/converters/reflection/FieldKeySorter.html">FieldKeySorter</a>.
142        Similar functionality exists for Java Beans with the
143        <a href="javadoc/com/thoughtworks/xstream/converters/javabean/PropertySorter.html">PropertySorter</a>.</p>
144		
145        <!-- ************ -->
146        
147        <h1 id="Enhancing">Enhancing XStream</h1>
148        
149        <p>Sometimes customization is simply not enough to tweak the output. Depending on the use case it is fortunate to
150        use specialized converters for own types, mapper implementations that control naming of things more globally or
151        use specialized writers to influence the complete output.</p>
152
153        <!-- .................. -->
154
155        <h2 id="Specialized_Converters">Specialized Converters</h2>
156
157        <p>Not all converters that are part of the XStream package are automatically registered.  Some will only make
158        sense for special types, others have parameters to tweak the behaviour.  Most useful in the table of 
159        <a href="converters.html">converters</a> are the JavaBeanConverter, ToStringConverter, and
160        ToAttributesValueConverter.  Not to mention the separate Hibernate package of XStream.</p>
161
162        <!-- .................. -->
163
164        <h2 id="Enhancing_Converters">Custom Converters</h2>
165
166        <p>Sometimes the object to serialize contains fields or elements, that have no friendly representation for 
167        human beings e.g. if a long value represents in reality a time stamp.  In such cases XStream supports custom
168        converters for arbitrary types.  Have a look at the <a href="converter-tutorial.html">Converter Tutorial</a>
169        for advanced possibilities.  Note, that a custom converter is not different to one that is delivered by
170        XStream.  It's simply your code.</p>
171
172        <!-- .................. -->
173
174        <h2 id="Enhancing_Mappers">Custom Mappers</h2>
175
176        <p>In case of global adjustments it can be helpful to implement an own mapper.  A mapper is used to name things
177        and map between the name in the Java world to the name used in the XML representation.  The alias mechanism
178        described above is implemented as such a mapper that can be configured.  A typical use case is dropping all
179        prefixes for field names like underscores in the resulting XML or omitting the package part of class names.</p>
180        
181        <p class="highlight">However, keep in mind that the algorithm must work in both directions to support deserialization.</p>
182
183        <!-- .................. -->
184
185        <h2 id="Enhancing_Writer">Custom Writer</h2>
186
187        <p>A custom writer can be used to affect the output completely. XStream itself delivers solutions for different
188        use cases like the <a href="javadoc/com/thoughtworks/xstream/io/xml/CompactWriter.html">CompactWriter</a>
189        that does not insert any white spaces between the XML tags or the 
190        <a href="javadoc/com/thoughtworks/xstream/io/json/JsonHierarchicalStreamWriter.html">JSON writer</a> that
191        produces a complete different output format.</p>
192        
193        <p>Another use case for such a writer is to drop unwanted XML elements that XStream omits on its own. 
194        Especially if the written XML is not used for deserialization it can be useful to ignore internal attributes by
195        a custom writer</p>
196		
197        <!-- ************ -->
198        
199        <h1 id="OwnCode">Tweaking the own implementation</h1>
200        
201        <p>As shown, XStream can be configured and enhanced in multiple way, but sometimes it is easier to tweak the
202        implementation of the serialized classes:</p>
203        
204        <ul>
205        	<li>Declaring a field transparent will omit it automatically from the processing</li>
206        	<li>Implementing a readResolve method that can be used to initialize additional fields</li>
207        	<li>Usage of annotations</li>
208        </ul>
209		
210        <!-- ************ -->
211        
212        <h1 id="Processing">Preprocessing or postprocessing</h1>
213
214        <h2>XML Transformations</h2>
215
216		<p>Never forget, you're dealing with XML! It is easy to transform XML with an XSLT. XStream is delivered with a SAXSource
217		implementation, that allows an XStream instance to be the source of a XML transformer.</p>
218
219        <h3>Example</h3>
220		<p>Look at the following stylesheet:</p>
221
222<div class="Source XML"><pre>
223&lt;xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
224  &lt;xsl:output method="xml" omit-xml-declaration="yes" indent="no"/&gt;
225  &lt;xsl:template match="/cat"&gt;
226    &lt;xsl:copy&gt;
227      &lt;xsl:apply-templates select="mName"/&gt;
228    &lt;/xsl:copy&gt;
229  &lt;/xsl:template&gt;
230&lt;/xsl:stylesheet&gt;</pre></div>
231
232		<p>It is used here to remove the age of the cat on the fly (assuming XSLT is a string with the stylesheet above):</p>
233		
234<div class="Source Java"><pre>
235XStream xstream = new XStream();
236xstream.alias("cat", Cat.class);
237
238TraxSource <b>traxSource</b> = new TraxSource(new Cat(4, "Garfield"), <b>xstream</b>);
239Writer buffer = new StringWriter();
240Transformer transformer = TransformerFactory.newInstance().newTransformer(
241    new StreamSource(new StringReader(XSLT)));
242transformer.transform(<b>traxSource</b>, new StreamResult(buffer));</pre></div>
243
244        <p>The result in the buffer:</p>
245
246<div class="Source XML"><pre>&lt;cat&gt;
247  &lt;mName&gt;Garfield&lt;/mName&gt;
248&lt;/cat&gt;</pre></div>
249
250    
251
252                <br/>
253
254            </div>
255        </div>
256
257        <div class="SidePanel" id="left">
258                <div class="MenuGroup">
259                    <h1>Software</h1>
260                    <ul>
261                                <li><a href="index.html">About XStream</a></li>
262                                <li><a href="news.html">News</a></li>
263                                <li><a href="changes.html">Change History</a></li>
264                                <li><a href="versioning.html">About Versioning</a></li>
265                    </ul>
266                </div>
267                <div class="MenuGroup">
268                    <h1>Evaluating XStream</h1>
269                    <ul>
270                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
271                                <li><a href="graphs.html">Object references</a></li>
272                                <li class="currentLink">Tweaking the Output</li>
273                                <li><a href="license.html">License</a></li>
274                                <li><a href="download.html">Download</a></li>
275                                <li><a href="references.html">References</a></li>
276                                <li><a href="parser-benchmarks.html">Parser Benchmarks</a></li>
277                                <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li>
278                    </ul>
279                </div>
280                <div class="MenuGroup">
281                    <h1>Using XStream</h1>
282                    <ul>
283                                <li><a href="architecture.html">Architecture Overview</a></li>
284                                <li><a href="converters.html">Converters</a></li>
285                                <li><a href="faq.html">Frequently Asked Questions</a></li>
286                                <li><a href="list-user.html">Users' Mailing List</a></li>
287                                <li><a href="issues.html">Reporting Issues</a></li>
288                    </ul>
289                </div>
290                <div class="MenuGroup">
291                    <h1>Javadoc</h1>
292                    <ul>
293                                <li><a href="javadoc/index.html">XStream Core</a></li>
294                                <li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li>
295                                <li><a href="benchmark-javadoc/index.html">Benchmark Module</a></li>
296                    </ul>
297                </div>
298                <div class="MenuGroup">
299                    <h1>Tutorials</h1>
300                    <ul>
301                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
302                                <li><a href="alias-tutorial.html">Alias Tutorial</a></li>
303                                <li><a href="annotations-tutorial.html">Annotations Tutorial</a></li>
304                                <li><a href="converter-tutorial.html">Converter Tutorial</a></li>
305                                <li><a href="objectstream.html">Object Streams Tutorial</a></li>
306                                <li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li>
307                                <li><a href="json-tutorial.html">JSON Tutorial</a></li>
308                    </ul>
309                </div>
310                <div class="MenuGroup">
311                    <h1>Developing XStream</h1>
312                    <ul>
313                                <li><a href="how-to-contribute.html">How to Contribute</a></li>
314                                <li><a href="list-dev.html">Developers' Mailing List</a></li>
315                                <li><a href="team.html">Development Team</a></li>
316                                <li><a href="repository.html">Source Repository</a></li>
317                                <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li>
318                    </ul>
319                </div>
320        </div>
321
322  </body>
323</html>