KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > thoughtworks > xstream > converters > Converter


1 package com.thoughtworks.xstream.converters;
2
3 import com.thoughtworks.xstream.io.HierarchicalStreamReader;
4 import com.thoughtworks.xstream.io.HierarchicalStreamWriter;
5
6 /**
7  * Converter implementations are responsible marshalling Java objects
8  * to/from textual data.
9  * <p/>
10  * <p>If an exception occurs during processing, a {@link ConversionException}
11  * should be thrown.</p>
12  * <p/>
13  * <p>If working with the high level {@link com.thoughtworks.xstream.XStream} facade,
14  * you can register new converters using the XStream.registerConverter() method.</p>
15  * <p/>
16  * <p>If working with the lower level API, the
17  * {@link com.thoughtworks.xstream.converters.ConverterLookup} implementation is
18  * responsible for looking up the appropriate converter.</p>
19  * <p/>
20  * <p>{@link com.thoughtworks.xstream.converters.basic.AbstractBasicConverter}
21  * provides a starting point for objects that can store all information
22  * in a single String.</p>
23  * <p/>
24  * <p>{@link com.thoughtworks.xstream.converters.collections.AbstractCollectionConverter}
25  * provides a starting point for objects that hold a collection of other objects
26  * (such as Lists and Maps).</p>
27  *
28  * @author Joe Walnes
29  * @see com.thoughtworks.xstream.XStream
30  * @see com.thoughtworks.xstream.converters.ConverterLookup
31  * @see com.thoughtworks.xstream.converters.basic.AbstractBasicConverter
32  * @see com.thoughtworks.xstream.converters.collections.AbstractCollectionConverter
33  */
34 public interface Converter {
35
36     /**
37      * Called by XStream to determine whether to use this converter
38      * instance to marshall a particular type.
39      */
40     boolean canConvert(Class JavaDoc type);
41
42     /**
43      * Convert an object to textual data.
44      *
45      * @param source The object to be marshalled.
46      * @param writer A stream to write to.
47      * @param context A context that allows nested objects to be processed by XStream.
48      */
49     void marshal(Object JavaDoc source, HierarchicalStreamWriter writer, MarshallingContext context);
50
51     /**
52      * Convert textual data back into an object.
53      *
54      * @param reader The stream to read the text from.
55      * @param context
56      * @return The resulting object.
57      */
58     Object JavaDoc unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context);
59
60 }
61
Popular Tags