org.gicentre.utils.io

## Class DOMProcessor

- java.lang.Object
- - org.gicentre.utils.io.DOMProcessor

-     public class DOMProcessor
      extends java.lang.Object

  Handles DOM processing allowing the reading and writing of hierarchical structures as XML files. Uses the Document Object Model (DOM) to store the tree of nodes, therefore not suitable for very large structures. For reading very large structures represented as XML, use SAX processing instead.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DOMProcessor()` Creates a new empty DOM ready for processing.
    `DOMProcessor(org.w3c.dom.Document dom)` Wraps the given DOM in this processor allowing it to be written as an XML file, or appended with new nodes.
    `DOMProcessor(java.io.InputStream inStream)` Reads XML from the given input stream and constructs a DOM from it.
    `DOMProcessor(java.lang.String fileName)` Reads and the given XML file and constructs a DOM from it.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addAttribute(java.lang.String name, java.lang.String value, org.w3c.dom.Node node)` Adds the given attribute to the given node.
    `void` | `addComment(java.lang.String comment)` Adds the given comment to the root of the DOM.
    `void` | `addComment(java.lang.String comment, org.w3c.dom.Node node)` Adds the given comment to the given node.
    `org.w3c.dom.Node` | `addElement(java.lang.String name)` Adds a new element to the root of the DOM.
    `org.w3c.dom.Node` | `addElement(java.lang.String name, org.w3c.dom.Node existingElement)` Adds a new element to the given one within the DOM.
    `org.w3c.dom.Node` | `addElement(java.lang.String name, java.lang.String text, org.w3c.dom.Node existingElement)` Adds a new element to the given one within the DOM.
    `void` | `addText(java.lang.String text, org.w3c.dom.Node node)` Adds text as the child of the given node.
    `java.lang.String[]` | `getAttributes(java.lang.String attributeName)` Searches the entire DOM for a given attribute and returns the value associated with it.
    `java.lang.String[]` | `getAttributes(java.lang.String attributeName, org.w3c.dom.Node node)` Searches the given node and its children for a given attribute and returns the value associated with it.
    `org.w3c.dom.Node[]` | `getElements(java.lang.String name)` Returns a list of the DOM elements with the given name.
    `org.w3c.dom.Node[]` | `getElements(java.lang.String name, org.w3c.dom.Node node)` Returns a list of the DOM elements with the given name that are nested within the given node.
    `static java.lang.String` | `getNodeAttribute(java.lang.String attributeName, org.w3c.dom.Node node)` Searches the given node for a given attribute and returns the value associated with it.
    `static org.w3c.dom.Node` | `getNodeElement(java.lang.String name, org.w3c.dom.Node node)` Returns a DOM element with the given name that is the child of the given node.
    `static org.w3c.dom.Node[]` | `getNodeElements(java.lang.String name, org.w3c.dom.Node node)` Returns the DOM elements with the given name that are the children of the given node.
    `static java.lang.String` | `getNodeText(org.w3c.dom.Node node)` Searches for a given node and returns text associated with it.
    `java.lang.String[]` | `getText(org.w3c.dom.Node node)` Returns any text associated found in the given node or its children.
    `java.lang.String[]` | `getText(java.lang.String elementName)` Searches the entire DOM for a given element and returns text associated with it.
    `java.lang.String[]` | `getText(java.lang.String elementName, org.w3c.dom.Node node)` Searches for a given element and returns text associated with it.
    `boolean` | `isEmpty()` Reports whether we have an empty DOM.
    `boolean` | `readXML(java.io.InputStream inStream)` Reads the XML from the given input stream and converts it into a DOM.
    `boolean` | `readXML(java.lang.String fileName)` Reads the given XML file and converts it into a DOM.
    `void` | `renameElement(org.w3c.dom.Node existingElement, java.lang.String newName)` Renames the given element with the given new name.
    `boolean` | `writeXML()` Displays the DOM stored within this class as an XML file with default document settings on standard output.
    `boolean` | `writeXML(java.io.OutputStream outStream)` Converts the DOM stored within this class into an XML file with default document settings.
    `boolean` | `writeXML(java.io.OutputStream outStream, java.lang.String version, java.lang.String encoding, java.lang.Boolean standalone)` Converts the DOM stored within this class into an XML file with the given document settings.
    `boolean` | `writeXML(java.lang.String fileName)` Converts the DOM stored within this class into an XML file with default document settings.
    `boolean` | `writeXML(java.lang.String version, java.lang.String encoding, java.lang.Boolean standalone)` Displays the DOM stored within this class as an XML file with the given document settings on standard output.
    `boolean` | `writeXML(java.lang.String fileName, java.lang.String version, java.lang.String encoding, java.lang.Boolean standalone)` Converts the DOM stored within this class into an XML file with the given document settings.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DOMProcessor

          public DOMProcessor()

      Creates a new empty DOM ready for processing.

    - #### DOMProcessor

          public DOMProcessor(org.w3c.dom.Document dom)

      Wraps the given DOM in this processor allowing it to be written as an XML file, or appended with new nodes.
      Parameters:
        `dom` - Document Object Model to use in processor.

    - #### DOMProcessor

          public DOMProcessor(java.lang.String fileName)

      Reads and the given XML file and constructs a DOM from it.
      Parameters:
        `fileName` - Name of XML file to read.

    - #### DOMProcessor

          public DOMProcessor(java.io.InputStream inStream)

      Reads XML from the given input stream and constructs a DOM from it.
      Parameters:
        `inStream` - Stream from which to read XML.

  - ### Method Detail

    - #### isEmpty

          public boolean isEmpty()

      Reports whether we have an empty DOM.
      Returns:
        True if DOM is empty.

    - #### addElement

          public org.w3c.dom.Node addElement(java.lang.String name)

      Adds a new element to the root of the DOM.
      Parameters:
        `name` - Name of the new element
      Returns:
        New element in the DOM.

    - #### addElement

          public org.w3c.dom.Node addElement(java.lang.String name,
                                             org.w3c.dom.Node existingElement)

      Adds a new element to the given one within the DOM.
      Parameters:
        `name` - Name of the new element
        `existingElement` - Element onto which the new element should be attached.
      Returns:
        New element in the DOM.

    - #### addElement

          public org.w3c.dom.Node addElement(java.lang.String name,
                                             java.lang.String text,
                                             org.w3c.dom.Node existingElement)

      Adds a new element to the given one within the DOM.
      Parameters:
        `name` - Name of the new element
        `text` - Text to attach to element or null if none required.
        `existingElement` - Element onto which the new element should be attached.
      Returns:
        New element in the DOM.

    - #### renameElement

          public void renameElement(org.w3c.dom.Node existingElement,
                                    java.lang.String newName)

      Renames the given element with the given new name.
      Parameters:
        `existingElement` - Element to rename.
        `newName` - New name to give element.

    - #### addAttribute

          public static void addAttribute(java.lang.String name,
                                          java.lang.String value,
                                          org.w3c.dom.Node node)

      Adds the given attribute to the given node.
      Parameters:
        `name` - Attribute name.
        `value` - Attribute value.
        `node` - Element to attach attribute.

    - #### addComment

          public void addComment(java.lang.String comment)

      Adds the given comment to the root of the DOM. Note that this method should only be called once a root node has been created in the DOM.
      Parameters:
        `comment` - Comment text.

    - #### addComment

          public void addComment(java.lang.String comment,
                                 org.w3c.dom.Node node)

      Adds the given comment to the given node.
      Parameters:
        `comment` - Comment text.
        `node` - Element to attach comment.

    - #### addText

          public void addText(java.lang.String text,
                              org.w3c.dom.Node node)

      Adds text as the child of the given node.
      Parameters:
        `text` - Text to add to node.
        `node` - Element to attach text.

    - #### getText

          public java.lang.String[] getText(java.lang.String elementName)

      Searches the entire DOM for a given element and returns text associated with it. If more than one element with the given name exists, multiple text values are returned.
      Parameters:
        `elementName` - Element to search for.
      Returns:
        Array of strings associated with all occurrences of the given element. Array will be 0 length if none found.

    - #### getText

          public java.lang.String[] getText(org.w3c.dom.Node node)

      Returns any text associated found in the given node or its children. This is equivalent to calling `getText(null,node)`. If more than one element containing text exists, multiple text values are returned.
      Parameters:
        `node` - Node from which to start search.
      Returns:
        Array of strings associated with all occurrences of text in the node or its children. Array will be 0 length if none found.

    - #### getText

          public java.lang.String[] getText(java.lang.String elementName,
                                            org.w3c.dom.Node node)

      Searches for a given element and returns text associated with it. If more than one element with the given name exists, multiple text values are returned.
      Parameters:
        `elementName` - Element to search for. If elementName is null, search will be for all text contained within the given node.
        `node` - Node from which to start search.
      Returns:
        Array of strings associated with all occurrences of the given element. Array will be 0 length if none found.

    - #### getNodeText

          public static java.lang.String getNodeText(org.w3c.dom.Node node)

      Searches for a given node and returns text associated with it. This version does not recurse to the node's children.
      Parameters:
        `node` - Node to search.
      Returns:
        Text associated with the node, or null if none found.

    - #### getAttributes

          public java.lang.String[] getAttributes(java.lang.String attributeName)

      Searches the entire DOM for a given attribute and returns the value associated with it. If there is more than one occurrence of the attribute, multiple text values are returned.
      Parameters:
        `attributeName` - Attribute to search for.
      Returns:
        Array of strings associated with all occurrences of the given attribute. Array will be 0 length if none found.

    - #### getAttributes

          public java.lang.String[] getAttributes(java.lang.String attributeName,
                                                  org.w3c.dom.Node node)

      Searches the given node and its children for a given attribute and returns the value associated with it. If there is more than one occurrence of the attribute, multiple text values are returned.
      Parameters:
        `attributeName` - Attribute to search for.
        `node` - Node from which to start search.
      Returns:
        Array of strings associated with all occurrences of the given attribute. Array will be 0 length if none found.

    - #### getNodeAttribute

          public static java.lang.String getNodeAttribute(java.lang.String attributeName,
                                                          org.w3c.dom.Node node)

      Searches the given node for a given attribute and returns the value associated with it. This version does not recurse to children of the given node.
      Parameters:
        `attributeName` - Attribute to search for.
        `node` - Node from which to start search.
      Returns:
        Value associated with the attribute, or null if not found.

    - #### getElements

          public org.w3c.dom.Node[] getElements(java.lang.String name)

      Returns a list of the DOM elements with the given name. This can be used to provide the base of sub-trees for searches within nested elements.
      Parameters:
        `name` - Element name to search for.
      Returns:
        Array of elements with the given name. Array will be 0 length if none found.

    - #### getElements

          public org.w3c.dom.Node[] getElements(java.lang.String name,
                                                org.w3c.dom.Node node)

      Returns a list of the DOM elements with the given name that are nested within the given node. This can be used to provide the base of sub-trees for searches within nested elements. The order of matched elements is depth-first. For breadth-first searches, use `getNodeElements` and recursively search for children of returned nodes.
      Parameters:
        `name` - Element name to search for.
        `node` - Node from which to start search.
      Returns:
        Array of elements with the given name. Array will be 0 length if none found.

    - #### getNodeElement

          public static org.w3c.dom.Node getNodeElement(java.lang.String name,
                                                        org.w3c.dom.Node node)

      Returns a DOM element with the given name that is the child of the given node. This is a non-recursive method that only looks for immediate children. Note that unlike `getNodeElements()` this method only returns the first matched child of the given node.
      Parameters:
        `name` - Element name to search for.
        `node` - Node from which to examine children.
      Returns:
        Child node or null if none found.

    - #### getNodeElements

          public static org.w3c.dom.Node[] getNodeElements(java.lang.String name,
                                                           org.w3c.dom.Node node)

      Returns the DOM elements with the given name that are the children of the given node. This is a non-recursive method that only looks for immediate children. Array will be 0 length if none found.
      Parameters:
        `name` - Element name to search for.
        `node` - Node from which to examine children.
      Returns:
        Child nodes or empty Node array if none found.

    - #### readXML

          public boolean readXML(java.lang.String fileName)

      Reads the given XML file and converts it into a DOM.
      Parameters:
        `fileName` - Name of XML file to convert.
      Returns:
        True if converted successfully.

    - #### readXML

          public boolean readXML(java.io.InputStream inStream)

      Reads the XML from the given input stream and converts it into a DOM.
      Parameters:
        `inStream` - Input stream containing XML to convert.
      Returns:
        True if converted successfully.

    - #### writeXML

          public boolean writeXML()

      Displays the DOM stored within this class as an XML file with default document settings on standard output.
      Returns:
        Always true.

    - #### writeXML

          public boolean writeXML(java.lang.String version,
                                  java.lang.String encoding,
                                  java.lang.Boolean standalone)

      Displays the DOM stored within this class as an XML file with the given document settings on standard output.
      Parameters:
        `version` - XML version, or null if default ('1.0') is to be used.
        `encoding` - XML encoding, or null if encoding is not to be specified.
        `standalone` - XML stand-alone status of XML file or null if not to be specified.
      Returns:
        Always true.

    - #### writeXML

          public boolean writeXML(java.lang.String fileName)

      Converts the DOM stored within this class into an XML file with default document settings.
      Parameters:
        `fileName` - Name of file to contain the XML.
      Returns:
        true if successful XML generation.

    - #### writeXML

          public boolean writeXML(java.io.OutputStream outStream)

      Converts the DOM stored within this class into an XML file with default document settings.
      Parameters:
        `outStream` - Output stream representing file to contain the XML.
      Returns:
        true if successful XML generation.

    - #### writeXML

          public boolean writeXML(java.lang.String fileName,
                                  java.lang.String version,
                                  java.lang.String encoding,
                                  java.lang.Boolean standalone)

      Converts the DOM stored within this class into an XML file with the given document settings.
      Parameters:
        `fileName` - Name of file to contain the XML.
        `version` - XML version, or null if default ('1.0') is to be used.
        `encoding` - XML encoding, or null if encoding is not to be specified.
        `standalone` - XML stand-alone status of XML file or null if not to be specified.
      Returns:
        true if successful XML generation.

    - #### writeXML

          public boolean writeXML(java.io.OutputStream outStream,
                                  java.lang.String version,
                                  java.lang.String encoding,
                                  java.lang.Boolean standalone)

      Converts the DOM stored within this class into an XML file with the given document settings.
      Parameters:
        `outStream` - Output stream representing file to contain the XML.
        `version` - XML version, or null if default ('1.0') is to be used.
        `encoding` - XML encoding, or null if encoding is not to be specified.
        `standalone` - XML stand-alone status of XML file or null if not to be specified.
      Returns:
        true if successful XML generation.