Package org.simpleframework.xml.stream

Class OutputDocument

  • All Implemented Interfaces:
    Node, OutputNode
    class OutputDocument
extends java.lang.Object
implements OutputNode
    The OutputDocument object is used to represent the root of an XML document. This does not actually represent anything that will be written to the generated document. It is used as a way to create the root document element. Once the root element has been created it can be committed by using this object.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.String comment
      This is the comment that is to be written for the node.
      private Mode mode
      This is the output mode of this output document object.
      private java.lang.String name
      This is the name of this output document node instance.
      private java.lang.String reference
      This represents the namespace reference used by this.
      private OutputStack stack
      This is the output stack used by the node writer object.
      private OutputNodeMap table
      Represents a dummy output node map for the attributes.
      private java.lang.String value
      Represents the value that has been set on this document.
      private NodeWriter writer
      Represents the writer that is used to create the element.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void commit()
      This will commit this element and any uncommitted elements elements that are decendents of this node.
      NodeMap<OutputNode> getAttributes()
      This returns a NodeMap which can be used to add nodes to this node.
      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.
      java.lang.String getName()
      To signify that this is the document element this method will return null.
      NamespaceMap getNamespaces()
      This returns the NamespaceMap for the document.
      OutputNode getParent()
      This is used to acquire the Node that is the parent of this node.
      java.lang.String getPrefix()
      The default for the OutputDocument is null as it does not require a namespace.
      java.lang.String getPrefix​(boolean inherit)
      The default for the OutputDocument is null as it does not require a namespace.
      java.lang.String getReference()
      This is used to acquire the reference that has been set on this output node.
      java.lang.String getValue()
      This returns the value that has been set for this document.
      boolean isCommitted()
      This is used to determine whether this 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 namespace reference for the document.
      void setValue​(java.lang.String value)
      This is used to set a text value to the element.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • table

        private OutputNodeMap table
        Represents a dummy output node map for the attributes.

      • writer

        private NodeWriter writer
        Represents the writer that is used to create the element.

      • stack

        private OutputStack stack
        This is the output stack used by the node writer object.

      • reference

        private java.lang.String reference
        This represents the namespace reference used by this.

      • comment

        private java.lang.String comment
        This is the comment that is to be written for the node.

      • value

        private java.lang.String value
        Represents the value that has been set on this document.

      • name

        private java.lang.String name
        This is the name of this output document node instance.

      • mode

        private Mode mode
        This is the output mode of this output document object.

    • Constructor Detail

      • OutputDocument

        public OutputDocument​(NodeWriter writer,
                      OutputStack stack)
        Constructor for the OutputDocument object. This is used to create an empty output node object that can be used to create a root element for the generated document.
        Parameters:
        writer - this is the node writer to write the node to
        stack - this is the stack that contains the open nodes

    • Method Detail

      • getPrefix

        public java.lang.String getPrefix()
        The default for the OutputDocument is null as it does not require a namespace. A null prefix is always used by the document as it represents a virtual node that does not exist and will not form any part of the resulting XML.
        Specified by:
        getPrefix in interface OutputNode
        Returns:
        this returns a null prefix for the output document

      • getPrefix

        public java.lang.String getPrefix​(boolean inherit)
        The default for the OutputDocument is null as it does not require a namespace. A null prefix is always used by the document as it represents a virtual node that does not exist and will not form any part of the resulting XML.
        Specified by:
        getPrefix in interface OutputNode
        Parameters:
        inherit - if there is no explicit prefix then inherit
        Returns:
        this returns a null prefix for the output document

      • getReference

        public java.lang.String getReference()
        This is used to acquire the reference that has been set on this output node. Typically this should be null as this node does not represent anything that actually exists. However if a namespace reference is set it can be acquired.
        Specified by:
        getReference in interface OutputNode
        Returns:
        this returns the namespace reference for this node

      • setReference

        public void setReference​(java.lang.String reference)
        This is used to set the namespace reference for the document. Setting a reference for the document node has no real effect as the document node is virtual and is not written to the resulting XML document that is generated.
        Specified by:
        setReference in interface OutputNode
        Parameters:
        reference - this is the namespace reference added

      • getNamespaces

        public NamespaceMap getNamespaces()
        This returns the NamespaceMap for the document. The namespace map for the document must be null as this will signify the end of the resolution process for a prefix if given a namespace reference.
        Specified by:
        getNamespaces in interface OutputNode
        Returns:
        this will return a null namespace map object

      • getParent

        public 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
        Specified by:
        getParent in interface OutputNode
        Returns:
        this will always return null for this output

      • getName

        public java.lang.String getName()
        To signify that this is the document element this method will return null. Any object with a handle on an output node that has been created can check the name to determine its type.
        Specified by:
        getName in interface Node
        Returns:
        this returns null for the name of the node

      • getValue

        public java.lang.String getValue()
                          throws java.lang.Exception
        This returns the value that has been set for this document. The value returned is essentially a dummy value as this node is never written to the resulting XML document.
        Specified by:
        getValue in interface Node
        Returns:
        the value that has been set with this document
        Throws:
        java.lang.Exception - if there is a problem getting the value

      • getComment

        public 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.
        Specified by:
        getComment in interface OutputNode
        Returns:
        this is the comment associated with this element

      • isRoot

        public 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 will return true although the document node is not strictly the root.
        Specified by:
        isRoot in interface OutputNode
        Returns:
        returns true although this is not really a root

      • getMode

        public 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.
        Specified by:
        getMode in interface OutputNode
        Returns:
        this returns the mode of this output node object

      • setMode

        public 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.
        Specified by:
        setMode in interface OutputNode
        Parameters:
        mode - this is the output mode to set the node to

      • setAttribute

        public 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.
        Specified by:
        setAttribute in interface OutputNode
        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

      • getAttributes

        public NodeMap<OutputNode> getAttributes()
        This returns a NodeMap which can be used to add nodes to this node. The node map returned by this is a dummy map, as this output node is never written to the XML document.
        Specified by:
        getAttributes in interface OutputNode
        Returns:
        returns the node map used to manipulate attributes

      • setName

        public 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.
        Specified by:
        setName in interface OutputNode
        Parameters:
        name - this is the name to change the node to

      • setValue

        public void setValue​(java.lang.String value)
        This is used to set a text value to the element. This effect of adding this to the document node will not change what is actually written to the generated XML document.
        Specified by:
        setValue in interface OutputNode
        Parameters:
        value - this is the text value to add to this element

      • setComment

        public 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.
        Specified by:
        setComment in interface OutputNode
        Parameters:
        comment - this is the comment to set on the node

      • setData

        public 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.
        Specified by:
        setData in interface OutputNode
        Parameters:
        data - if true the value is written as a CDATA block

      • getChild

        public 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.
        Specified by:
        getChild in interface OutputNode
        Parameters:
        name - this is the name of the child element to create
        Throws:
        java.lang.Exception

      • remove

        public 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.
        Specified by:
        remove in interface OutputNode
        Throws:
        java.lang.Exception - thrown if the node cannot be removed

      • commit

        public void commit()
            throws java.lang.Exception
        This will commit this element and any uncommitted elements elements that are decendents of this node. For instance if any child or grand child remains open under this element then those elements will be closed before this is closed.
        Specified by:
        commit in interface OutputNode
        Throws:
        java.lang.Exception - this is thrown if there is an I/O error or if a root element has not yet been created

      • isCommitted

        public boolean isCommitted()
        This is used to determine whether this node has been committed. This will return true if no root element has been created or if the root element for the document has already been commited.
        Specified by:
        isCommitted in interface OutputNode
        Returns:
        true if the node is committed or has not been created