1 package com.atlassian.dbexporter.node;
2
3 import java.io.IOException;
4 import java.io.Reader;
5 import java.math.BigDecimal;
6 import java.math.BigInteger;
7 import java.util.Date;
8
9 /**
10 * Represents a node in streaming XML documents. This is a small abstraction
11 * layer over StAX that allows other streaming data formats to be created (JSON,
12 * ASN.1, ?) and make it easier to deal with StAX, of which the API can be a bit
13 * tedious. This interface also provides type conversion instead of just strings.
14 * This interface only provides write access to a streaming node graph.
15 *
16 * @author Erik van Zijst
17 * @see NodeParser counterpart of this interface that provides read access to
18 * streaming node graphs.
19 * @see NodeStreamWriter
20 */
21 public interface NodeCreator {
22
23 /**
24 * Creates a new child node under the current node.
25 *
26 * @param name the name of the new child node.
27 * @return a reference to the new node. Continue with this reference.
28 */
29 NodeCreator addNode(String name);
30
31 /**
32 * Closes the current node and returns a reference to the parent node.
33 *
34 * @return a reference to the parent node. Continue with this reference.
35 */
36 NodeCreator closeEntity();
37
38 /**
39 * Similar to {@link NodeCreator#setContentAsString(String)}, but sets the
40 * content to the specified {@link java.util.Date} instance.
41 *
42 * @param date the value to set
43 * @return a reference to the current node.
44 */
45 NodeCreator setContentAsDate(Date date);
46
47 /**
48 * Similar to {@link NodeCreator#setContentAsString(String)}, but sets the
49 * content to the specified {@link java.math.BigInteger} instance.
50 *
51 * @param bigInteger the value to set
52 * @return a reference to the current node.
53 */
54 NodeCreator setContentAsBigInteger(BigInteger bigInteger);
55
56 NodeCreator setContentAsBigDecimal(BigDecimal bigDecimal);
57
58 /**
59 * Sets the content of the current node to be the specified string. This
60 * method does not automatically close the node, but returns a reference to
61 * the current node. The caller is responsible for closing the node using
62 * {@link NodeCreator#closeEntity()}.
63 * <P>
64 * Use <code>null</code> to explicitly encode the null value (results in
65 * <code><node xsi:nil="true"/></code> in XML, while an empty
66 * string produces <code><node></node></code>).
67 *
68 * @param string the content for the current node.
69 * @return a reference to the current node.
70 */
71 NodeCreator setContentAsString(String string);
72
73 /**
74 * Similar to {@link NodeCreator#setContentAsString(String)}, but sets the
75 * content to the specified {@link Boolean} instance.
76 *
77 * @param bool the value to set
78 * @return a reference to the current node.
79 */
80 NodeCreator setContentAsBoolean(Boolean bool);
81
82 /**
83 * Similar to {@link NodeCreator#setContentAsString(String)}, but sets the
84 * content to the specified {@link byte[]} instance.
85 *
86 * @param bytes the value to set
87 * @return a reference to the current node.
88 */
89 NodeCreator setContentAsBinary(byte[] bytes);
90
91 /**
92 * Similar to {@link NodeCreator#setContentAsString(String)}, but passes the
93 * content to the {@link NodeCreator} as a {@link java.io.Reader} instance. Use this
94 * to encode large chunks of content in a memory-efficient way.
95 *
96 * @param data the content to set
97 * @return a reference to the current node.
98 * @throws java.io.IOException
99 */
100 NodeCreator setContent(Reader data) throws IOException;
101
102 /**
103 * Adds an attribute to the current node.
104 *
105 * @param key the attribute key
106 * @param value the attribute value
107 */
108 NodeCreator addAttribute(String key, String value);
109 }