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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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.
    • 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