PageRenderTime 23ms CodeModel.GetById 9ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 0ms

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

http://prototipomemoria.googlecode.com/
HTML | 439 lines | 376 code | 51 blank | 12 comment | 0 complexity | 1ab46f1d2256cee7c6e1bbaf0ee7484b 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 - Alias Tutorial</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">Alias Tutorial</h1>
 39
 40                
 41<h2 id="problem">The problem</h2>
 42<p>Suppose that our client has defined a base XML file that we should make XStream read/write:</p>
 43<div class="Source Java"><pre>&lt;blog author=&quot;Guilherme Silveira&quot;&gt;
 44  &lt;entry&gt;
 45    &lt;title&gt;first&lt;/title&gt;
 46    &lt;description&gt;My first blog entry.&lt;/description&gt;
 47  &lt;/entry&gt;
 48  &lt;entry&gt;
 49    &lt;title&gt;tutorial&lt;/title&gt;
 50    &lt;description&gt;
 51        Today we have developed a nice alias tutorial. Tell your friends! NOW!
 52    &lt;/description&gt;
 53  &lt;/entry&gt;
 54&lt;/blog&gt;</pre>
 55
 56<p>Based on the XML file above we shall create some model classes and configure XStream to write/read from this format.</p></div>
 57<div class="section">
 58<h2 id="model">The model</h2>
 59<p>First things first, the classes which shall represent our xml files are shown next, beginning with a simple Blog:</p>
 60<div class="Source Java"><pre>package com.thoughtworks.xstream;
 61
 62public class Blog {
 63        private Author writer;
 64        private List entries = new ArrayList();
 65
 66        public Blog(Author writer) {
 67                this.writer = writer;
 68        }
 69
 70        public void add(Entry entry) {
 71                entries.add(entry);
 72        }
 73
 74        public List getContent() {
 75                return entries;
 76        }
 77}</pre></div>
 78<p>A basic author with name:</p>
 79<div class="Source Java"><pre>package com.thoughtworks.xstream;
 80
 81public class Author {
 82        private String name;
 83        public Author(String name) {
 84                this.name = name;
 85        }
 86        public String getName() {
 87                return name;
 88        }
 89}</pre></div>
 90<p>A blog entry contains a title and description:</p>
 91<div class="Source Java"><pre>package com.thoughtworks.xstream;
 92
 93public class Entry {
 94        private String title, description;
 95        public Entry(String title, String description) {
 96                this.title = title;
 97                this.description = description;
 98        }
 99}</pre></div>
100<p>Although we did not create many getters/setters its up to you to create those you wish or those which make sense.</p></div>
101<div class="section">
102<h2 id="test">A simple test</h2>
103<p>We can easily instantiate a new blog and use it with xstream:</p>
104<div class="Source Java"><pre>public static void main(String[] args) {
105
106        Blog teamBlog = new Blog(new Author(&quot;Guilherme Silveira&quot;));
107        teamBlog.add(new Entry(&quot;first&quot;,&quot;My first blog entry.&quot;));
108        teamBlog.add(new Entry(&quot;tutorial&quot;,
109                &quot;Today we have developed a nice alias tutorial. Tell your friends! NOW!&quot;));
110
111        XStream xstream = new XStream();
112        System.out.println(xstream.toXML(teamBlog));
113
114}</pre></div>
115<p>And the resulting XML is not so nice as we would want it to be:</p>
116<div class="Source Java"><pre>&lt;com.thoughtworks.xstream.Blog&gt;
117  &lt;writer&gt;
118    &lt;name&gt;Guilherme Silveira&lt;/name&gt;
119  &lt;/writer&gt;
120  &lt;entries&gt;
121    &lt;com.thoughtworks.xstream.Entry&gt;
122      &lt;title&gt;first&lt;/title&gt;
123      &lt;description&gt;My first blog entry.&lt;/description&gt;
124    &lt;/com.thoughtworks.xstream.Entry&gt;
125    &lt;com.thoughtworks.xstream.Entry&gt;
126      &lt;title&gt;tutorial&lt;/title&gt;
127      &lt;description&gt;
128        Today we have developed a nice alias tutorial. Tell your friends! NOW!
129      &lt;/description&gt;
130    &lt;/com.thoughtworks.xstream.Entry&gt;
131  &lt;/entries&gt;
132&lt;/com.thoughtworks.xstream.Blog&gt;</pre></div></div>
133<div class="section">
134<h2 id="class_aliasing">Class aliasing</h2>
135<p>The first thing we shall change is how XStream refers to the <b>com.thoughtworks.xstream.Blog</b> class.
136We shall name it simply <i>blog</i>: let's create an alias called <i>blog</i> to the desired class:</p>
137<div class="Source Java"><pre>xstream.alias(&quot;blog&quot;, Blog.class);</pre></div>
138<p>Using the same idea, we can alias the 'Entry' class to 'entry':</p>
139<div class="Source Java"><pre>xstream.alias(&quot;entry&quot;, Entry.class);</pre></div>
140<p>The result now becomes:</p>
141<div class="Source Java"><pre>&lt;blog&gt;
142  &lt;writer&gt;
143    &lt;name&gt;Guilherme Silveira&lt;/name&gt;
144  &lt;/writer&gt;
145  &lt;entries&gt;
146    &lt;entry&gt;
147      &lt;title&gt;first&lt;/title&gt;
148      &lt;description&gt;My first blog entry.&lt;/description&gt;
149    &lt;/entry&gt;
150    &lt;entry&gt;
151      &lt;title&gt;tutorial&lt;/title&gt;
152      &lt;description&gt;
153        Today we have developed a nice alias tutorial. Tell your friends! NOW!
154      &lt;/description&gt;
155    &lt;/entry&gt;
156  &lt;/entries&gt;
157&lt;/blog&gt;</pre></div></div>
158<div class="section">
159<h2 id="field_aliasing">Field aliasing</h2>
160<p>Next we will change the name of the writer tag, but this time we have to use a field alias:</p>
161<div class="Source Java"><pre>xstream.aliasField(&quot;author&quot;, Blog.class, &quot;writer&quot;);</pre></div>
162<p>The result now becomes:</p>
163<div class="Source Java"><pre>&lt;blog&gt;
164  &lt;author&gt;
165    &lt;name&gt;Guilherme Silveira&lt;/name&gt;
166  &lt;/author&gt;
167  &lt;entries&gt;
168    &lt;entry&gt;
169      &lt;title&gt;first&lt;/title&gt;
170      &lt;description&gt;My first blog entry.&lt;/description&gt;
171    &lt;/entry&gt;
172    &lt;entry&gt;
173      &lt;title&gt;tutorial&lt;/title&gt;
174      &lt;description&gt;
175        Today we have developed a nice alias tutorial. Tell your friends! NOW!
176      &lt;/description&gt;
177    &lt;/entry&gt;
178  &lt;/entries&gt;
179&lt;/blog&gt;</pre></div></div>
180<div class="section">
181<h2 id="implicit">Implicit Collections</h2>
182<p>Now let's implement what was called an <b>implicit collection</b>: whenever you have a collection which doesn't need
183to display it's root tag, you can map it as an implicit collection.</p>
184<p>In our example, we do not want to display the <b>entries</b> tag, but simply show the <b>entry</b> tags one after
185another.</p>
186<p>A simple call to the <b>addImplicitCollection</b> method shall configure XStream and let it know that we do not want to
187write the <b>entries</b> tag as described above:</p>
188<div class="Source Java"><pre>package com.thoughtworks.xstream;
189
190import java.util.ArrayList;
191import java.util.List;
192
193public class Test {
194
195        public static void main(String[] args) {
196
197                Blog teamBlog = new Blog(new Author(&quot;Guilherme Silveira&quot;));
198                teamBlog.add(new Entry(&quot;first&quot;,&quot;My first blog entry.&quot;));
199                teamBlog.add(new Entry(&quot;tutorial&quot;,
200                        &quot;Today we have developed a nice alias tutorial. Tell your friends! NOW!&quot;));
201
202                XStream xstream = new XStream();
203                xstream.alias(&quot;blog&quot;, Blog.class);
204                xstream.alias(&quot;entry&quot;, Entry.class);
205
206                xstream.addImplicitCollection(Blog.class, &quot;entries&quot;);
207
208                System.out.println(xstream.toXML(teamBlog));
209
210        }
211}</pre></div>
212<p>Pay attention to the <b>addImplicitCollection</b> method call: it describes which class and which member variable
213shall assume the behaviour we described.</p>
214<p>The result is almost what we wanted:</p>
215<div class="Source Java"><pre>&lt;blog&gt;
216  &lt;author&gt;
217    &lt;name&gt;Guilherme Silveira&lt;/name&gt;
218  &lt;/author&gt;
219  &lt;entry&gt;
220    &lt;title&gt;first&lt;/title&gt;
221    &lt;description&gt;My first blog entry.&lt;/description&gt;
222  &lt;/entry&gt;
223  &lt;entry&gt;
224    &lt;title&gt;tutorial&lt;/title&gt;
225    &lt;description&gt;
226        Today we have developed a nice alias tutorial. Tell your friends! NOW!
227    &lt;/description&gt;
228  &lt;/entry&gt;
229&lt;/blog&gt;</pre></div></div>
230<p>Just as a side note: An array or a map can also be declared as implicit.</p>
231<div class="section">
232<h2 id="attributes">Attribute aliasing</h2>
233<p>The next step is to set the <b>writer</b> member variable as an XML attribute. In order to do this, we shall tell
234XStream to alias the <b>writer</b> field of the <b>Blog</b> class as an "author" attribute:</p>
235<div class="Source Java"><pre>                xstream.useAttributeFor(Blog.class, &quot;writer&quot;);
236                xstream.aliasField(&quot;author&quot;, Blog.class, &quot;writer&quot;);</pre></div>
237<p>And now it leaves us with one problem: how does XStream converts an Author in a String so it can be written as a
238XML tag attribute?</p>
239<p>Attributes cannot be written for types that are handled by Converter implementations, we have to use a
240<b>SingleValueConverter</b> and implement our own converter for the Author:</p>
241<div class="Source Java"><pre>class AuthorConverter implements SingleValueConverter {
242}</pre></div>
243<p>The first method to implement tells XStream which types it can deal with:</p>
244<div class="Source Java"><pre>        public boolean canConvert(Class type) {
245                return type.equals(Author.class);
246        }</pre></div>
247<p>The second one is used to extract a String from an Author:</p>
248<div class="Source Java"><pre>        public String toString(Object obj) {
249                return ((Author) obj).getName();
250        }</pre></div>
251<p>And the third one does the opposite job: takes a String and returns an Author:</p>
252<div class="Source Java"><pre>        public Object fromString(String name) {
253                return new Author(name);
254        }</pre></div>
255<p>Finally, the entire single value converter, responsible for converting Strings to Objects (Authors in this case) is:</p>
256<div class="Source Java"><pre>class AuthorConverter implements SingleValueConverter {
257
258        public String toString(Object obj) {
259                return ((Author) obj).getName();
260        }
261
262        public Object fromString(String name) {
263                return new Author(name);
264        }
265
266        public boolean canConvert(Class type) {
267                return type.equals(Author.class);
268        }
269
270}</pre></div>
271<p>And let's register this converter:</p>
272<div class="Source Java"><pre>public class Test {
273
274        public static void main(String[] args) {
275
276                Blog teamBlog = new Blog(new Author(&quot;Guilherme Silveira&quot;));
277                teamBlog.add(new Entry(&quot;first&quot;,&quot;My first blog entry.&quot;));
278                teamBlog.add(new Entry(&quot;tutorial&quot;,
279                        &quot;Today we have developed a nice alias tutorial. Tell your friends! NOW!&quot;));
280
281                XStream xstream = new XStream();
282                xstream.alias(&quot;blog&quot;, Blog.class);
283                xstream.alias(&quot;entry&quot;, Entry.class);
284
285                xstream.addImplicitCollection(Blog.class, &quot;entries&quot;);
286
287                xstream.useAttributeFor(Blog.class, &quot;author&quot;);
288                xstream.registerConverter(new AuthorConverter());
289
290                System.out.println(xstream.toXML(teamBlog));
291
292        }
293}</pre></div>
294<p>The result?</p>
295<div class="Source Java"><pre>&lt;blog author=&quot;Guilherme Silveira&quot;&gt;
296  &lt;entry&gt;
297    &lt;title&gt;first&lt;/title&gt;
298    &lt;description&gt;My first blog entry.&lt;/description&gt;
299  &lt;/entry&gt;
300  &lt;entry&gt;
301    &lt;title&gt;tutorial&lt;/title&gt;
302    &lt;description&gt;
303        Today we have developed a nice alias tutorial. Tell your friends! NOW!
304    &lt;/description&gt;
305  &lt;/entry&gt;
306&lt;/blog&gt;</pre></div>
307</div>
308
309<p class=highlight>You have to be aware, that attribute values normally have to be normalized by the XML parser as
310required by the <a href="http://www.w3.org/TR/REC-xml/#AVNormalize">W3C spec</a>. Leading and trailing whitespaces
311are normally removed as well as sequential ones! Therefore a deserialized string might differ from the value visible in
312the XML representation.</p>
313
314<div class="section">
315<h2 id="packages">Package aliasing</h2>
316
317<p>In the example above we have so far always used class aliases for the Blog and Entry type. Sometimes it is necessary to
318map existing class types to others simply by changing the package name. Let us go back to the first attempt of our tutorial,
319but this time we alias the package name instead of the individual classes:</p>
320<div class="Source Java"><pre>public static void main(String[] args) {
321
322        Blog teamBlog = new Blog(new Author(&quot;Guilherme Silveira&quot;));
323        teamBlog.add(new Entry(&quot;first&quot;,&quot;My first blog entry.&quot;));
324        teamBlog.add(new Entry(&quot;tutorial&quot;,
325                &quot;Today we have developed a nice alias tutorial. Tell your friends! NOW!&quot;));
326
327        XStream xstream = new XStream();
328        xstream.aliasPackage("my.company", "org.thoughtworks");
329        System.out.println(xstream.toXML(teamBlog));
330
331}</pre></div>
332<p>And the resulting XML contains now the classes with the aliased package names:</p>
333<div class="Source Java"><pre>&lt;my.company.xstream.Blog&gt;
334  &lt;author&gt;
335    &lt;name&gt;Guilherme Silveira&lt;/name&gt;
336  &lt;/author&gt;
337  &lt;entries&gt;
338    &lt;my.company.xstream.Entry&gt;
339      &lt;title&gt;first&lt;/title&gt;
340      &lt;description&gt;My first blog entry.&lt;/description&gt;
341    &lt;/my.company.xstream.Entry&gt;
342    &lt;my.company.xstream.Entry&gt;
343      &lt;title&gt;tutorial&lt;/title&gt;
344      &lt;description&gt;
345        Today we have developed a nice alias tutorial. Tell your friends! NOW!
346      &lt;/description&gt;
347    &lt;/my.company.xstream.Entry&gt;
348  &lt;/entries&gt;
349&lt;/my.company.xstream.Blog&gt;</pre></div>
350<p>Please recognize that the package name alias works also for sub packages in this example.</p>
351</div>
352
353<div class="section">
354<h2 id="summary">Summing up</h2>
355<p>To recap:</p>
356<ul>
357<li>You can use class aliases to change tag names</li>
358<li>You can use field aliases to change tag names</li>
359<li>You can use package aliases to change tag names</li>
360<li>Fields can be written as attributes if the field type is handled by a SingleValueConverter</li>
361</ul>
362<p>Don't forget to read the <a href="converter-tutorial.html">converter tutorial</a> to see other type of converters that you can create using XStream.
363Or look into the condensed overview how to configure XStream to <a href="manual-tweaking-output.html">tweak the output</a>.</p>
364</div>
365
366  
367
368                <br/>
369
370            </div>
371        </div>
372
373        <div class="SidePanel" id="left">
374                <div class="MenuGroup">
375                    <h1>Software</h1>
376                    <ul>
377                                <li><a href="index.html">About XStream</a></li>
378                                <li><a href="news.html">News</a></li>
379                                <li><a href="changes.html">Change History</a></li>
380                                <li><a href="versioning.html">About Versioning</a></li>
381                    </ul>
382                </div>
383                <div class="MenuGroup">
384                    <h1>Evaluating XStream</h1>
385                    <ul>
386                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
387                                <li><a href="graphs.html">Object references</a></li>
388                                <li><a href="manual-tweaking-output.html">Tweaking the Output</a></li>
389                                <li><a href="license.html">License</a></li>
390                                <li><a href="download.html">Download</a></li>
391                                <li><a href="references.html">References</a></li>
392                                <li><a href="parser-benchmarks.html">Parser Benchmarks</a></li>
393                                <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li>
394                    </ul>
395                </div>
396                <div class="MenuGroup">
397                    <h1>Using XStream</h1>
398                    <ul>
399                                <li><a href="architecture.html">Architecture Overview</a></li>
400                                <li><a href="converters.html">Converters</a></li>
401                                <li><a href="faq.html">Frequently Asked Questions</a></li>
402                                <li><a href="list-user.html">Users' Mailing List</a></li>
403                                <li><a href="issues.html">Reporting Issues</a></li>
404                    </ul>
405                </div>
406                <div class="MenuGroup">
407                    <h1>Javadoc</h1>
408                    <ul>
409                                <li><a href="javadoc/index.html">XStream Core</a></li>
410                                <li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li>
411                                <li><a href="benchmark-javadoc/index.html">Benchmark Module</a></li>
412                    </ul>
413                </div>
414                <div class="MenuGroup">
415                    <h1>Tutorials</h1>
416                    <ul>
417                                <li><a href="tutorial.html">Two Minute Tutorial</a></li>
418                                <li class="currentLink">Alias Tutorial</li>
419                                <li><a href="annotations-tutorial.html">Annotations Tutorial</a></li>
420                                <li><a href="converter-tutorial.html">Converter Tutorial</a></li>
421                                <li><a href="objectstream.html">Object Streams Tutorial</a></li>
422                                <li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li>
423                                <li><a href="json-tutorial.html">JSON Tutorial</a></li>
424                    </ul>
425                </div>
426                <div class="MenuGroup">
427                    <h1>Developing XStream</h1>
428                    <ul>
429                                <li><a href="how-to-contribute.html">How to Contribute</a></li>
430                                <li><a href="list-dev.html">Developers' Mailing List</a></li>
431                                <li><a href="team.html">Development Team</a></li>
432                                <li><a href="repository.html">Source Repository</a></li>
433                                <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li>
434                    </ul>
435                </div>
436        </div>
437
438  </body>
439</html>