Class OutputDocument

java.lang.Object
org.simpleframework.xml.stream.OutputDocument
All Implemented Interfaces:
Node, OutputNode
class OutputDocument extends 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 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 String
    name
    This is the name of this output document node instance.
    private 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 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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    OutputDocument(NodeWriter writer, OutputStack stack)
    Constructor for the OutputDocument object.

  • Method Summary

    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(String name)
    This is used to create a child element within the element that this object represents.
    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.
    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.
    String
    getPrefix()
    The default for the OutputDocument is null as it does not require a namespace.
    String
    getPrefix(boolean inherit)
    The default for the OutputDocument is null as it does not require a namespace.
    String
    getReference()
    This is used to acquire the reference that has been set on this output node.
    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(String name, String value)
    This method is used for convenience to add an attribute node to the attribute NodeMap.
    void
    setComment(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(String name)
    This is used to change the name of an output node.
    void
    setReference(String reference)
    This is used to set the namespace reference for the document.
    void
    setValue(String value)
    This is used to set a text value to the element.

    Methods inherited from class Object

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

  • Field Details

    • 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 String reference
      This represents the namespace reference used by this.

    • comment

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

    • value

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

    • name

      private 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 Details

    • 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 Details

    • getPrefix

      public 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 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 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(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 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 String getValue() throws 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:
      Exception - if there is a problem getting the value

    • getComment

      public 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(String name, 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(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(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(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(String name) throws 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:
      Exception

    • remove

      public void remove() throws 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:
      Exception - thrown if the node cannot be removed

    • commit

      public void commit() throws 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:
      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