# OutputNode
Date: 2013-02-18

## org.simpleframework.xml.stream
Interface OutputNode

All Superinterfaces:
  Node

    public interface OutputNode

extends Node

The `OutputNode` object is used to represent a cursor which can be used to write XML elements and attributes. Each of the output node objects represents a element, and can be used to add attributes to that element as well as child elements.

Author:
  Niall Gallagher

Method Summary
`void` `commit()` The `commit` method is used flush and commit any child nodes that have been created by this node.
`NodeMap<OutputNode>` `getAttributes()` This returns a `NodeMap` which can be used to add nodes to the element before that element has been committed.
`OutputNode` `getChild(java.lang.String name)` This is used to create a child element within the element that this object represents.
`java.lang.String` `getComment()` This is used to get the text comment for the element.
`Mode` `getMode()` The `Mode` is used to indicate the output mode of this node.
`NamespaceMap` `getNamespaces()` This returns the `NamespaceMap` for this node.
`OutputNode` `getParent()` This is used to acquire the `Node` that is the parent of this node.
`java.lang.String` `getPrefix()` This is used to acquire the prefix for this output node.
`java.lang.String` `getPrefix(boolean inherit)` This is used to acquire the prefix for this output node.
`java.lang.String` `getReference()` This is used to acquire the namespace URI reference associated with this node.
`boolean` `isCommitted()` This is used to determine whether the node has been committed.
`boolean` `isRoot()` This method is used to determine if this node is the root node for the XML document.
`void` `remove()` This is used to remove any uncommitted changes.
`OutputNode` `setAttribute(java.lang.String name, java.lang.String value)` This method is used for convenience to add an attribute node to the attribute `NodeMap`.
`void` `setComment(java.lang.String comment)` This is used to set a text comment to the element.
`void` `setData(boolean data)` This is used to set the output mode of this node to either be CDATA or escaped.
`void` `setMode(Mode mode)` This is used to set the output mode of this node to either be CDATA, escaped, or inherited.
`void` `setName(java.lang.String name)` This is used to change the name of an output node.
`void` `setReference(java.lang.String reference)` This is used to set the reference for the node.
`void` `setValue(java.lang.String value)` This is used to set a text value to the element.

Methods inherited from interface org.simpleframework.xml.stream.Node
`getName, getValue`

Method Detail

### isRoot

    boolean isRoot()

  This method is used to determine if this node is the root node for the XML document. The root node is the first node in the document and has no sibling nodes. This is false if the node has a parent node or a sibling node.

  Returns:
    true if this is the root node within the document

### getAttributes

    NodeMap<OutputNode> getAttributes()

  This returns a `NodeMap` which can be used to add nodes to the element before that element has been committed. Nodes can be removed or added to the map and will appear as attributes on the written element when it is committed.

  Returns:
    returns the node map used to manipulate attributes

### getMode

    Mode getMode()

  The `Mode` is used to indicate the output mode of this node. Three modes are possible, each determines how a value, if specified, is written to the resulting XML document. This is determined by the `setData` method which will set the output to be CDATA or escaped, if neither is specified the mode is inherited.

  Returns:
    this returns the mode of this output node object

### setMode

    void setMode(Mode mode)

  This is used to set the output mode of this node to either be CDATA, escaped, or inherited. If the mode is set to data then any value specified will be written in a CDATA block, if this is set to escaped values are escaped. If however this method is set to inherited then the mode is inherited from the parent node.

  Parameters:
    `mode` - this is the output mode to set the node to

### setData

    void setData(boolean data)

  This is used to set the output mode of this node to either be CDATA or escaped. If this is set to true the any value specified will be written in a CDATA block, if this is set to false the values is escaped. If however this method is never invoked then the mode is inherited from the parent.

  Parameters:
    `data` - if true the value is written as a CDATA block

### getPrefix

    java.lang.String getPrefix()

  This is used to acquire the prefix for this output node. If the output node is an element then this will search its parent nodes until the prefix that is currently in scope is found. If however this node is an attribute then the hierarchy of nodes is not searched as attributes to not inherit namespaces.

  Returns:
    this returns the prefix associated with this node

### getPrefix

    java.lang.String getPrefix(boolean inherit)

  This is used to acquire the prefix for this output node. If the output node is an element then this will search its parent nodes until the prefix that is currently in scope is found. If however this node is an attribute then the hierarchy of nodes is not searched as attributes to not inherit namespaces.

  Parameters:
    `inherit` - if there is no explicit prefix then inherit
  Returns:
    this returns the prefix associated with this node

### getReference

    java.lang.String getReference()

  This is used to acquire the namespace URI reference associated with this node. Although it is recommended that the namespace reference is a URI it does not have to be, it can be any unique identifier that can be used to distinguish the qualified names.

  Returns:
    this returns the namespace URI reference for this

### setReference

    void setReference(java.lang.String reference)

  This is used to set the reference for the node. Setting the reference implies that the node is a qualified node within the XML document. Both elements and attributes can be qualified. Depending on the prefix set on this node or, failing that, any parent node for the reference, the element will appear in the XML document with that string prefixed to the node name.

  Parameters:
    `reference` - this is used to set the reference for the node

### getNamespaces

    NamespaceMap getNamespaces()

  This returns the `NamespaceMap` for this node. Only an element can have namespaces, so if this node represents an attribute the elements namespaces will be provided when this is requested. By adding a namespace it becomes in scope for the current element all all child elements of that element.

  Returns:
    this returns the namespaces associated with the node

### getComment

    java.lang.String getComment()

  This is used to get the text comment for the element. This can be null if no comment has been set. If no comment is set on the node then no comment will be written to the resulting XML.

  Returns:
    this is the comment associated with this element

### setComment

    void setComment(java.lang.String comment)

  This is used to set a text comment to the element. This will be written just before the actual element is written. Only a single comment can be set for each output node written.

  Parameters:
    `comment` - this is the comment to set on the node

### setValue

    void setValue(java.lang.String value)

  This is used to set a text value to the element. This should be added to the element if the element contains no child elements. If the value cannot be added an exception is thrown.

  Parameters:
    `value` - this is the text value to add to this element
  Throws:
    `java.lang.Exception` - thrown if the text value cannot be added

### setName

    void setName(java.lang.String name)

  This is used to change the name of an output node. This will only affect the name of the node if the node has not yet been committed. If the node is committed then this will not be reflected in the resulting XML generated.

  Parameters:
    `name` - this is the name to change the node to

### setAttribute

    OutputNode setAttribute(java.lang.String name,
                            java.lang.String value)

  This method is used for convenience to add an attribute node to the attribute `NodeMap`. The attribute added can be removed from the element by using the node map.

  Parameters:
    `name` - this is the name of the attribute to be added
    `value` - this is the value of the node to be added
  Returns:
    this returns the node that has just been added

### getParent

    OutputNode getParent()

  This is used to acquire the `Node` that is the parent of this node. This will return the node that is the direct parent of this node and allows for siblings to make use of nodes with their parents if required.

  Specified by:
    `getParent` in interface `Node`
  Returns:
    this returns the parent node for this node

### getChild

    OutputNode getChild(java.lang.String name)
                        throws java.lang.Exception

  This is used to create a child element within the element that this object represents. When a new child is created with this method then the previous child is committed to the document. The created `OutputNode` object can be used to add attributes to the child element as well as other elements.

  Parameters:
    `name` - this is the name of the child element to create
  Throws:
    `java.lang.Exception`

### remove

    void remove()
                throws java.lang.Exception

  This is used to remove any uncommitted changes. Removal of an output node can only be done if it has no siblings and has not yet been committed. If the node is committed then this will throw an exception to indicate that it cannot be removed.

  Throws:
    `java.lang.Exception` - thrown if the node cannot be removed

### commit

    void commit()
                throws java.lang.Exception

  The `commit` method is used flush and commit any child nodes that have been created by this node. This allows the output to be completed when building of the XML document has been completed. If output fails an exception is thrown.

  Throws:
    `java.lang.Exception` - thrown if the node cannot be committed

### isCommitted

    boolean isCommitted()

  This is used to determine whether the node has been committed. If the node has been committed, then this will return true. When committed the node can no longer produce chile nodes.

  Returns:
    true if this node has already been committed