01: /*
02: * Copyright (C) 2004, 2005 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 07. March 2004 by Joe Walnes
11: */
12: package com.thoughtworks.xstream.io;
13:
14: /**
15: * @author Joe Walnes
16: */
17: public interface HierarchicalStreamWriter {
18:
19: void startNode(String name);
20:
21: void addAttribute(String name, String value);
22:
23: /**
24: * Write the value (text content) of the current node.
25: */
26: void setValue(String text);
27:
28: void endNode();
29:
30: /**
31: * Flush the writer, if necessary.
32: */
33: void flush();
34:
35: /**
36: * Close the writer, if necessary.
37: */
38: void close();
39:
40: /**
41: * Return the underlying HierarchicalStreamWriter implementation.
42: *
43: * <p>If a Converter needs to access methods of a specific HierarchicalStreamWriter implementation that are not
44: * defined in the HierarchicalStreamWriter interface, it should call this method before casting. This is because
45: * the writer passed to the Converter is often wrapped/decorated by another implementation to provide additional
46: * functionality (such as XPath tracking).</p>
47: *
48: * <p>For example:</p>
49: * <pre>MySpecificWriter mySpecificWriter = (MySpecificWriter)writer; <b>// INCORRECT!</b>
50: * mySpecificWriter.doSomethingSpecific();</pre>
51:
52: * <pre>MySpecificWriter mySpecificWriter = (MySpecificWriter)writer.underlyingWriter(); <b>// CORRECT!</b>
53: * mySpecificWriter.doSomethingSpecific();</pre>
54: *
55: * <p>Implementations of HierarchicalStreamWriter should return 'this', unless they are a decorator, in which case
56: * they should delegate to whatever they are wrapping.</p>
57: */
58: HierarchicalStreamWriter underlyingWriter();
59:
60: }
|