/activeobjects-dbex/src/main/java/com/atlassian/dbexporter/node/NodeCreator.java

  1package com.atlassian.dbexporter.node;
  2
  3import java.io.IOException;
  4import java.io.Reader;
  5import java.math.BigDecimal;
  6import java.math.BigInteger;
  7import 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 */
 21public 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
 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
 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>&lt;node xsi:nil="true"/&gt;</code> in XML, while an empty
 66     * string produces <code>&lt;node&gt;&lt;/node&gt;</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
 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
 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
 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
106     * @param value
107     */
108    NodeCreator addAttribute(String key, String value);
109}