01: /*
02: * Copyright (C) 2003, 2004 Joe Walnes.
03: * Copyright (C) 2006, 2007 XStream Committers.
04: * All rights reserved.
05: *
06: * The software in this package is published under the terms of the BSD
07: * style license a copy of which has been included with this distribution in
08: * the LICENSE.txt file.
09: *
10: * Created on 26. September 2003 by Joe Walnes
11: */
12: package com.thoughtworks.xstream.converters;
13:
14: import com.thoughtworks.xstream.io.HierarchicalStreamReader;
15: import com.thoughtworks.xstream.io.HierarchicalStreamWriter;
16:
17: /**
18: * Converter implementations are responsible marshalling Java objects
19: * to/from textual data.
20: * <p/>
21: * <p>If an exception occurs during processing, a {@link ConversionException}
22: * should be thrown.</p>
23: * <p/>
24: * <p>If working with the high level {@link com.thoughtworks.xstream.XStream} facade,
25: * you can register new converters using the XStream.registerConverter() method.</p>
26: * <p/>
27: * <p>If working with the lower level API, the
28: * {@link com.thoughtworks.xstream.converters.ConverterLookup} implementation is
29: * responsible for looking up the appropriate converter.</p>
30: * <p/>
31: * <p>Converters for object that can store all information in a single value
32: * should implement {@link com.thoughtworks.xstream.converters.SingleValueConverter}.
33: * <p>{@link com.thoughtworks.xstream.converters.basic.AbstractSingleValueConverter}
34: * provides a starting point.</p>
35: * <p/>
36: * <p>{@link com.thoughtworks.xstream.converters.collections.AbstractCollectionConverter}
37: * provides a starting point for objects that hold a collection of other objects
38: * (such as Lists and Maps).</p>
39: *
40: * @author Joe Walnes
41: * @see com.thoughtworks.xstream.XStream
42: * @see com.thoughtworks.xstream.converters.ConverterLookup
43: * @see com.thoughtworks.xstream.converters.basic.AbstractSingleValueConverter
44: * @see com.thoughtworks.xstream.converters.collections.AbstractCollectionConverter
45: */
46: public interface Converter extends ConverterMatcher {
47:
48: /**
49: * Convert an object to textual data.
50: *
51: * @param source The object to be marshalled.
52: * @param writer A stream to write to.
53: * @param context A context that allows nested objects to be processed by XStream.
54: */
55: void marshal(Object source, HierarchicalStreamWriter writer,
56: MarshallingContext context);
57:
58: /**
59: * Convert textual data back into an object.
60: *
61: * @param reader The stream to read the text from.
62: * @param context
63: * @return The resulting object.
64: */
65: Object unmarshal(HierarchicalStreamReader reader,
66: UnmarshallingContext context);
67:
68: }
|