uk.ac.starlink.util

## Class DOMUtils

- java.lang.Object
- - uk.ac.starlink.util.DOMUtils

-     public class DOMUtils
      extends java.lang.Object

  Provides convenience methods for handling DOMs.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static org.w3c.dom.Element` | `getChildElementByName(org.w3c.dom.Node parent, java.lang.String name)` Returns the first child element of a node which has a given name.
    `static org.w3c.dom.Element[]` | `getChildElementsByName(org.w3c.dom.Node parent, java.lang.String name)` Returns all child elements of a node with a given name.
    `static org.w3c.dom.Element` | `getFirstElementSibling(org.w3c.dom.Node node)` Returns the first subsequent sibling of a given node which is an Element.
    `static java.lang.String` | `getTextContent(org.w3c.dom.Element el)` Returns a string representing the plain text content of an element.
    `static java.lang.String` | `mapNodeType(short nodeType)` Maps a node type, as returned by to a name.
    `static org.w3c.dom.Document` | `newDocument()` Returns a new `Document` instance.
    `static org.w3c.dom.Node` | `relativizeDOM(org.w3c.dom.Node n, java.net.URI baseURI, java.lang.String attname)` Traverses the given DOM, relativising all the URIs in the `uri` attributes of each `Element`.

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

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

- - ### Method Detail

    - #### getChildElementByName

          public static org.w3c.dom.Element getChildElementByName(org.w3c.dom.Node parent,
                                                                  java.lang.String name)

      Returns the first child element of a node which has a given name.
      Parameters:
        `parent` - the node whose children are to be searched
        `name` - the name of the element being searched for
      Returns:
        the first child of `parent` which is an `Element` and has the tagname `name`, or `null` if none match

    - #### getChildElementsByName

          public static org.w3c.dom.Element[] getChildElementsByName(org.w3c.dom.Node parent,
                                                                     java.lang.String name)

      Returns all child elements of a node with a given name.
      Parameters:
        `parent` - the node whose children are to be searched
        `name` - the name of the element being searched for
      Returns:
        array of child elements of `parent` with tagname `name`; if `name` is null, all child elements are returned

    - #### getTextContent

          public static java.lang.String getTextContent(org.w3c.dom.Element el)

      Returns a string representing the plain text content of an element. Any comments, attributes, elements or other non-text children are ignored, and all CDATA and Text nodes are merged to give a single string.
      Parameters:
        `el` - the element whose text content is wanted
      Returns:
        the pure text content. If there is none, an empty string is returned.

    - #### getFirstElementSibling

          public static org.w3c.dom.Element getFirstElementSibling(org.w3c.dom.Node node)

      Returns the first subsequent sibling of a given node which is an Element. This is useful for naviating a DOM as a tree of elements when the presence of text or attribute children is a distraction.
      Parameters:
        `node` - the node whose siblings (including itself) you are interested in. May be `null`
      Returns:
        the first sibling of `node` which is an Element. If `node` itself is an element, that is returned. If `node` has no subsequent siblings which are elements, or if it is `null`, then `null` is returned.

    - #### relativizeDOM

          public static org.w3c.dom.Node relativizeDOM(org.w3c.dom.Node n,
                                                       java.net.URI baseURI,
                                                       java.lang.String attname)

      Traverses the given DOM, relativising all the URIs in the `uri` attributes of each `Element`.

      The (uri-attribute) nodes in the input DOM are modified by this method; if this is a problem, use `Node.cloneNode(boolean)` first.

      Parameters:
        `n` - a node containing the DOM whose URIs are to be relativized. If this is null, the method immediately returns null
        `baseURI` - the URI relative to which the DOM is to be relativised. If this is null, then the input node is immediately returned unchanged.
        `attname` - the attribute name to be used. If null, this defaults to `uri`
      Returns:
        the input node
      See Also:
        `URI.relativize(java.net.URI)`

    - #### mapNodeType

          public static java.lang.String mapNodeType(short nodeType)

      Maps a node type, as returned by to a name. The node types returned by `Node.getNodeType()` are numeric and are therefore inconveniently opaque.
      Parameters:
        `nodeType` - a numeric Node type, one of the node type constants defined in `Node`
      Returns:
        a string name for the type

    - #### newDocument

          public static org.w3c.dom.Document newDocument()

      Returns a new `Document` instance. This method just does all the tedious business of mucking about with factories for you.
      Returns:
        an empty Document