edu.northwestern.at.utils.xml

## Class DOMUtils

- java.lang.Object
- - edu.northwestern.at.utils.xml.DOMUtils

-     public class DOMUtils
      extends java.lang.Object

  XML DOM utilities.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addDescendants(org.w3c.dom.Node node, java.util.List<org.w3c.dom.Node> descendants)` Adds descendant elements of a node to a list.
    `static java.util.Map<java.lang.String,java.lang.String>` | `attributesToSortedMap(org.xml.sax.Attributes attributes)` Convert attributes list to sorted map.
    `static org.w3c.dom.Element` | `findChild(org.w3c.dom.Node parent, java.lang.String namePat)` Find child node name matching regular expression.
    `static java.util.List<org.w3c.dom.Node>` | `findChildren(org.w3c.dom.Node node, java.lang.String name)` Gets the child elements of a node by name pattern.
    `static java.lang.String` | `getAllText(org.w3c.dom.Node node)` Gets all the text for a node.
    `static org.w3c.dom.Element` | `getChild(org.w3c.dom.Node node, java.lang.String name)` Gets a child element of a node by name.
    `static org.w3c.dom.Element` | `getChild(org.w3c.dom.Node node, java.lang.String name, java.lang.String attrName, java.lang.String attrValue)` Gets a child element of a node by name and attribute value.
    `static java.util.List<org.w3c.dom.Node>` | `getChildren(org.w3c.dom.Node node, java.lang.String name)` Gets the child elements of a node by name.
    `static java.util.List<org.w3c.dom.Element>` | `getChildren(org.w3c.dom.Node node, java.lang.String name, java.lang.String attrName, java.lang.String attrValue)` Gets the child elements of a node by name and attribute value.
    `static org.w3c.dom.Element` | `getDescendant(org.w3c.dom.Node node, java.lang.String path)` Gets a descendant element of a node.
    `static java.util.List<org.w3c.dom.Node>` | `getDescendants(org.w3c.dom.Node node)` Gets descendant elements of a node.
    `static java.util.List<org.w3c.dom.Node>` | `getDescendants(org.w3c.dom.Node node, java.lang.String path)` Gets descendant elements of a node.
    `static org.w3c.dom.Element` | `getLastChild(org.w3c.dom.Node node, java.lang.String name)` Gets the last child element of a node by name.
    `static org.w3c.dom.NodeList` | `getNodesByTagName(org.w3c.dom.Document document, java.lang.String[] tagNames)` Get list of nodes by one or more tag names.
    `static java.lang.String` | `getText(org.w3c.dom.Node node)` Gets text for a node.
    `static org.w3c.dom.Document` | `newDocument()` Creates a new empty DOM document.
    `static boolean` | `nodeHasDescendant(org.w3c.dom.Node node, java.lang.String[] names1, java.lang.String[] names2)` Checks to see if a node has a descendant node of some name, other than those in children of some other name.
    `static org.w3c.dom.Document` | `parse(java.io.File file)` Parses an XML file.
    `static org.w3c.dom.Document` | `parse(java.lang.String path)` Parses an XML file.
    `static org.w3c.dom.Document` | `parse(java.net.URL url)` Parses XML document from URL.
    `static org.w3c.dom.Document` | `parseText(java.lang.String text)` Parses XML document from a string.
    `static org.w3c.dom.DocumentFragment` | `parseXML(org.w3c.dom.Document doc, java.lang.String fragment)` Parse a string containing XML and return a DocumentFragment.
    `static void` | `save(org.w3c.dom.Document document, java.lang.String path)` Saves a DOM document to an XML file in utf-8.
    `static void` | `save(org.w3c.dom.Document document, java.lang.String dtdName, java.lang.String path)` Saves a DOM document to an XML file in utf-8.
    `static java.lang.String` | `saveToString(org.w3c.dom.Document document)` Saves a DOM document to a String.
    `static java.lang.String` | `saveToString(org.w3c.dom.Document document, java.lang.String dtdName)` Saves a DOM document to a String with a specified DTD name.
    `static void` | `setText(org.w3c.dom.Node node, java.lang.String text)` Sets text for a node.
    `static void` | `validateDocument(org.w3c.dom.Document document, javax.xml.validation.Schema schema)` Validate a DOM document against a schema.

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

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

- - ### Method Detail

    - #### parse

          public static org.w3c.dom.Document parse(java.io.File file)
                                            throws java.io.IOException,
                                                   javax.xml.parsers.ParserConfigurationException,
                                                   org.xml.sax.SAXException

      Parses an XML file.
      Parameters:
        `file` - File.
      Returns:
        DOM document.
      Throws:
        `java.lang.Exception`
        `java.io.IOException`
        `javax.xml.parsers.ParserConfigurationException`
        `org.xml.sax.SAXException`

    - #### parse

          public static org.w3c.dom.Document parse(java.lang.String path)
                                            throws java.io.IOException,
                                                   javax.xml.parsers.ParserConfigurationException,
                                                   org.xml.sax.SAXException

      Parses an XML file.
      Parameters:
        `path` - File path.
      Returns:
        DOM document.
      Throws:
        `java.lang.Exception`
        `java.io.IOException`
        `javax.xml.parsers.ParserConfigurationException`
        `org.xml.sax.SAXException`

    - #### parse

          public static org.w3c.dom.Document parse(java.net.URL url)
                                            throws java.io.IOException,
                                                   javax.xml.parsers.ParserConfigurationException,
                                                   org.xml.sax.SAXException

      Parses XML document from URL.
      Parameters:
        `url` - URL.
      Returns:
        DOM document.
      Throws:
        `java.lang.Exception`
        `java.io.IOException`
        `javax.xml.parsers.ParserConfigurationException`
        `org.xml.sax.SAXException`

    - #### parseText

          public static org.w3c.dom.Document parseText(java.lang.String text)
                                                throws java.io.IOException,
                                                       javax.xml.parsers.ParserConfigurationException,
                                                       org.xml.sax.SAXException

      Parses XML document from a string.
      Parameters:
        `text` - Document text string.
      Returns:
        DOM document.
      Throws:
        `java.lang.Exception`
        `java.io.IOException`
        `javax.xml.parsers.ParserConfigurationException`
        `org.xml.sax.SAXException`

    - #### getChild

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

      Gets a child element of a node by name.
      Parameters:
        `node` - Node.
        `name` - Name.
      Returns:
        First child element with given tag name, or null if none found.

    - #### findChild

          public static org.w3c.dom.Element findChild(org.w3c.dom.Node parent,
                                      java.lang.String namePat)

      Find child node name matching regular expression.
      Parameters:
        `parent` - Node whose child we want.
        `namePat` - Regular expression for child name.
      Returns:
        The first child whose name matches the specified namePat, or null if none matches.

    - #### getLastChild

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

      Gets the last child element of a node by name.
      Parameters:
        `node` - Node.
        `name` - Name.
      Returns:
        Last child element with given tag name, or null if none found.

    - #### getChild

          public static org.w3c.dom.Element getChild(org.w3c.dom.Node node,
                                     java.lang.String name,
                                     java.lang.String attrName,
                                     java.lang.String attrValue)

      Gets a child element of a node by name and attribute value.
      Parameters:
        `node` - Node.
        `name` - Name.
        `attrName` - Attribute name.
        `attrValue` - Attribute value.
      Returns:
        First child element with given tag name and given attribute value, or null if none found.

    - #### getText

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

      Gets text for a node.
      Parameters:
        `node` - Node.
      Returns:
        Value of first child text node, or the empty string if none found, with leading and trailing white space trimmed.

    - #### setText

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

      Sets text for a node.

      Sets the value of the first child text node, if any. Creates new child text node if none found.

      Parameters:
        `node` - Node.
        `text` - New text for the node.

    - #### getAllText

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

      Gets all the text for a node.
      Parameters:
        `node` - Node.
      Returns:
        Values of each child text node concatenated together in order, with leading and trailing white space trimmed.

    - #### getChildren

          public static java.util.List<org.w3c.dom.Node> getChildren(org.w3c.dom.Node node,
                                                     java.lang.String name)

      Gets the child elements of a node by name.
      Parameters:
        `node` - Node.
        `name` - Name.
      Returns:
        All of the child elements of the node with the given tag name, in order.

    - #### findChildren

          public static java.util.List<org.w3c.dom.Node> findChildren(org.w3c.dom.Node node,
                                                      java.lang.String name)

      Gets the child elements of a node by name pattern.
      Parameters:
        `node` - Node.
        `name` - Name as a regular expression.
      Returns:
        All of the child elements of the node with the given matching tag name, in order.

    - #### getChildren

          public static java.util.List<org.w3c.dom.Element> getChildren(org.w3c.dom.Node node,
                                                        java.lang.String name,
                                                        java.lang.String attrName,
                                                        java.lang.String attrValue)

      Gets the child elements of a node by name and attribute value.
      Parameters:
        `node` - Node.
        `name` - Name.
        `attrName` - Attribute name.
        `attrValue` - Attribute value.
      Returns:
        All of the child elements of the node with the given tag name which have the given attribute value, in order.

    - #### getDescendant

          public static org.w3c.dom.Element getDescendant(org.w3c.dom.Node node,
                                          java.lang.String path)

      Gets a descendant element of a node.
      Parameters:
        `node` - Node.
        `path` - Path to descendant, using tag names of child elements separated by "/".
      Returns:
        Descendant element, or null if none found.

    - #### getDescendants

          public static java.util.List<org.w3c.dom.Node> getDescendants(org.w3c.dom.Node node,
                                                        java.lang.String path)

      Gets descendant elements of a node.
      Parameters:
        `node` - Node.
        `path` - Path to descendants, using tag names of child elements separated by "/".
      Returns:
        A list of descendant elements.

    - #### addDescendants

          public static void addDescendants(org.w3c.dom.Node node,
                            java.util.List<org.w3c.dom.Node> descendants)

      Adds descendant elements of a node to a list.
      Parameters:
        `node` - Node.
        `descendants` - List of descendants.

    - #### getDescendants

          public static java.util.List<org.w3c.dom.Node> getDescendants(org.w3c.dom.Node node)

      Gets descendant elements of a node.
      Parameters:
        `node` - Node.
      Returns:
        List of descendant elemen nodes in no particular order. List may be empty.

    - #### newDocument

          public static org.w3c.dom.Document newDocument()
                                                  throws javax.xml.parsers.ParserConfigurationException

      Creates a new empty DOM document.
      Returns:
        New empty DOM document.
      Throws:
        `javax.xml.parsers.ParserConfigurationException`

    - #### parseXML

          public static org.w3c.dom.DocumentFragment parseXML(org.w3c.dom.Document doc,
                                              java.lang.String fragment)

      Parse a string containing XML and return a DocumentFragment.
      Parameters:
        `doc` - The document,
        `fragment` - The XML text fragment.
      Returns:
        The document fragment.

    - #### save

          public static void save(org.w3c.dom.Document document,
                  java.lang.String path)
                           throws javax.xml.transform.TransformerException,
                                  java.io.IOException

      Saves a DOM document to an XML file in utf-8.
      Parameters:
        `document` - DOM document.
        `path` - Output file path.
      Throws:
        `TransformerException,` - IOException
        `javax.xml.transform.TransformerException`
        `java.io.IOException`

    - #### save

          public static void save(org.w3c.dom.Document document,
                  java.lang.String dtdName,
                  java.lang.String path)
                           throws javax.xml.transform.TransformerException,
                                  java.io.IOException

      Saves a DOM document to an XML file in utf-8.
      Parameters:
        `document` - DOM document.
        `dtdName` - The DTD name.
        `path` - Output file path.
      Throws:
        `TransformerException,` - IOException
        `javax.xml.transform.TransformerException`
        `java.io.IOException`

    - #### saveToString

          public static java.lang.String saveToString(org.w3c.dom.Document document)
                                               throws javax.xml.transform.TransformerException,
                                                      java.io.IOException

      Saves a DOM document to a String.
      Parameters:
        `document` - DOM document.
      Returns:
        XML version of DOM document as a string.
      Throws:
        `TransformerException,` - IOException
        `javax.xml.transform.TransformerException`
        `java.io.IOException`

    - #### saveToString

          public static java.lang.String saveToString(org.w3c.dom.Document document,
                                      java.lang.String dtdName)
                                               throws javax.xml.transform.TransformerException,
                                                      java.io.IOException

      Saves a DOM document to a String with a specified DTD name.
      Parameters:
        `document` - DOM document.
        `dtdName` - The DTD name.
      Returns:
        XML version of DOM document as a string.
      Throws:
        `TransformerException,` - IOException
        `javax.xml.transform.TransformerException`
        `java.io.IOException`

    - #### nodeHasDescendant

          public static boolean nodeHasDescendant(org.w3c.dom.Node node,
                                  java.lang.String[] names1,
                                  java.lang.String[] names2)

      Checks to see if a node has a descendant node of some name, other than those in children of some other name.
      Parameters:
        `node` - Node
        `names1` - Array of names to include.
        `names2` - Array of names to exclude.
      Returns:
        True if the node contains a descendant in names1, but not in children in names2.

    - #### validateDocument

          public static void validateDocument(org.w3c.dom.Document document,
                              javax.xml.validation.Schema schema)
                                       throws org.xml.sax.SAXException,
                                              java.io.IOException

      Validate a DOM document against a schema.
      Parameters:
        `document` - The parsed DOM document to validate.
        `schema` - A parsed schema.
      Throws:
        `java.io.IOException` - if the validation fails.
        `org.xml.sax.SAXException` - if the validation fails.

        Simply returns without error if validation succeeds.

    - #### attributesToSortedMap

          public static java.util.Map<java.lang.String,java.lang.String> attributesToSortedMap(org.xml.sax.Attributes attributes)

      Convert attributes list to sorted map.
      Parameters:
        `attributes` - Attributes.
      Returns:
        Attributes converted to sorted map.

    - #### getNodesByTagName

          public static org.w3c.dom.NodeList getNodesByTagName(org.w3c.dom.Document document,
                                               java.lang.String[] tagNames)

      Get list of nodes by one or more tag names.
      Parameters:
        `document` - Document in which to extract nodes.
        `tagNames` - String array of tag names for which to extract matching nodes.
      Returns:
        NodeList of matching nodes. Null if none found.