org.apache.ode.utils

## Class DOMUtils

- java.lang.Object
- - org.apache.ode.utils.DOMUtils

-     public class DOMUtils
      extends java.lang.Object

  Utility class for dealing with the Document Object Model (DOM).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `NS_URI_XMLNS` The namespaceURI represented by the prefix `xmlns`.
    `static java.lang.String` | `WSDL_NS`
    `static java.lang.String` | `WSDL_ROOT_ELEMENT`
    `static java.lang.String` | `XSD_NS`
    `static java.lang.String` | `XSD_ROOT_ELEMENT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DOMUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static org.w3c.dom.Node` | `cloneNode(org.w3c.dom.Document document, org.w3c.dom.Node sourceNode)` Deep clone, but don't fry, the given node in the context of the given document.
    `static void` | `copyNSContext(org.w3c.dom.Element source, org.w3c.dom.Element dest)`
    `static int` | `countKids(org.w3c.dom.Element elem, short nodeType)` Count number of children of a certain type of the given element.
    `static byte[]` | `domToBytes(org.w3c.dom.Element element)`
    `static java.lang.String` | `domToString(org.w3c.dom.Node node)` Convert a DOM node to a stringified XML representation.
    `static java.lang.String` | `domToStringLevel2(org.w3c.dom.Node node)` Convert a DOM node to a stringified XML representation.
    `static org.w3c.dom.Element` | `findChildByName(org.w3c.dom.Element parent, javax.xml.namespace.QName name)`
    `static org.w3c.dom.Element` | `findChildByName(org.w3c.dom.Element parent, javax.xml.namespace.QName name, boolean recurse)`
    `static org.w3c.dom.Node` | `findChildByType(org.w3c.dom.Element elem, int type)`
    `static org.w3c.dom.Element` | `findChildElementWithAttribute(org.w3c.dom.Element elem, java.lang.String attrName, java.lang.String attrValue)` Return the first child element of the given element which has the given attribute with the given value.
    `static java.util.List<org.w3c.dom.Element>` | `findChildrenByName(org.w3c.dom.Element parent, javax.xml.namespace.QName name)`
    `static java.lang.String` | `getAttribute(org.w3c.dom.Element el, java.lang.String attrName)` Returns the value of an attribute of an element.
    `static java.lang.String` | `getAttributeNS(org.w3c.dom.Element el, java.lang.String namespaceURI, java.lang.String localPart)` Returns the value of an attribute of an element.
    `static java.lang.String` | `getChildCharacterData(org.w3c.dom.Element parentEl)` Concat all the text and cdata node children of this elem and return the resulting text.
    `static org.w3c.dom.Document` | `getDocument(org.w3c.dom.Node contextNode)`
    `static org.w3c.dom.Element` | `getElementByID(org.w3c.dom.Element el, java.lang.String id)` DOCUMENTME
    `static org.w3c.dom.Element` | `getElementContent(org.w3c.dom.Node node)`
    `static org.w3c.dom.Element` | `getFirstChildElement(org.w3c.dom.Element elem)` Return the first child element of the given element.
    `static java.util.Map<java.lang.String,java.lang.String>` | `getMyNamespaces(org.w3c.dom.Element el)`
    `static NSContext` | `getMyNSContext(org.w3c.dom.Element el)` Construct a `NSContext` instance for the supplied element.
    `static java.lang.String` | `getNamespaceURIFromPrefix(org.w3c.dom.Node context, java.lang.String prefix)` Given a prefix and a node, return the namespace URI that the prefix has been associated with.
    `static org.w3c.dom.Element` | `getNextSiblingElement(org.w3c.dom.Element elem)` Return the next sibling element of the given element.
    `static javax.xml.namespace.QName` | `getNodeQName(org.w3c.dom.Node el)`
    `static javax.xml.namespace.QName` | `getNodeQName(java.lang.String qualifiedName)`
    `static java.lang.String` | `getNSPrefixFromNSAttr(org.w3c.dom.Attr a)` Fetch the non-null namespace prefix from a `Attr` that declares a namespace.
    `static java.util.Map<java.lang.String,java.lang.String>` | `getParentNamespaces(org.w3c.dom.Element el)` This method traverses the DOM and grabs namespace declarations on parent elements with the intent of preserving them for children.
    `static javax.xml.namespace.QName` | `getQualifiedAttributeValue(org.w3c.dom.Element el, java.lang.String attrName)` DOCUMENTME
    `static java.lang.String` | `getQualifiedName(javax.xml.namespace.QName qName)`
    `static java.lang.String` | `getTextContent(org.w3c.dom.Node node)`
    `static void` | `injectNamespaces(org.w3c.dom.Element domElement, NSContext nscontext)`
    `static void` | `injectNamespacesWithAllPrefixes(org.w3c.dom.Element domElement, NSContext nscontext)` Adds namespaces including all prefixes.
    `static boolean` | `isEmptyElement(org.w3c.dom.Element el)` Check that an element is empty, i.e., it contains no non-whitespace text or elements as children.
    `static boolean` | `isNSAttribute(org.w3c.dom.Attr a)` Test whether an attribute contains a namespace declaration.
    `static boolean` | `isWsdlDocument(org.w3c.dom.Document d)` Perform a naive check to see if a document is a WSDL document based on the root element name and namespace URI.
    `static boolean` | `isXmlSchemaDocument(org.w3c.dom.Document d)` Perform a naive check to see if a document is an XML schema document based on the root element name and namespace URI.
    `static org.w3c.dom.Document` | `newDocument()`
    `static void` | `pancakeNamespaces(org.w3c.dom.Element el)`
    `static org.w3c.dom.Document` | `parse(org.xml.sax.InputSource inputSource)` Parse an XML document located using an `InputSource` using the pooled document builder.
    `static org.w3c.dom.Document` | `parse(java.io.InputStream inputStream)` Parse an XML stream using the pooled document builder.
    `static org.w3c.dom.Document` | `parse(javax.xml.stream.XMLStreamReader reader)`
    `static java.lang.String` | `prettyPrint(org.w3c.dom.Element e)` Deprecated. relies on XMLSerializer which is a deprecated Xerces class, use domToString instead
    `static void` | `removeAttributes(org.w3c.dom.Element target, boolean flag)` Drop the attributes from an element, except possibly an `xmlns` attribute that declares its namespace.
    `static void` | `removeChildren(org.w3c.dom.Node target)` Remove the child nodes under another node.
    `static void` | `serialize(org.w3c.dom.Element elmt, java.io.OutputStream ostr)`
    `static org.w3c.dom.Document` | `sourceToDOM(javax.xml.transform.Source inputSource)` Parse an XML document located using an `InputSource` using the pooled document builder.
    `static org.w3c.dom.Element` | `stringToDOM(byte[] bytes)`
    `static org.w3c.dom.Element` | `stringToDOM(java.lang.String s)` Parse a String into a DOM.
    `static org.w3c.dom.Document` | `toDocumentFromStream(javax.xml.transform.stream.StreamSource source)`
    `static org.w3c.dom.Document` | `toDOMDocument(org.w3c.dom.Node node)`
    `static java.util.List<org.w3c.dom.Node>` | `toList(java.lang.Object nl)` Somewhat eases the pain of dealing with both Lists and Nodelists by converting either passed as parameter to a List.

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

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

- - ### Field Detail

    - #### NS_URI_XMLNS

          public static final java.lang.String NS_URI_XMLNS

      The namespaceURI represented by the prefix `xmlns`.
      See Also:
        Constant Field Values

    - #### WSDL_NS

          public static final java.lang.String WSDL_NS

      See Also:
        Constant Field Values

    - #### WSDL_ROOT_ELEMENT

          public static final java.lang.String WSDL_ROOT_ELEMENT

      See Also:
        Constant Field Values

    - #### XSD_NS

          public static final java.lang.String XSD_NS

      See Also:
        Constant Field Values

    - #### XSD_ROOT_ELEMENT

          public static final java.lang.String XSD_ROOT_ELEMENT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DOMUtils

          public DOMUtils()

  - ### Method Detail

    - #### getAttribute

          public static java.lang.String getAttribute(org.w3c.dom.Element el,
                                      java.lang.String attrName)

      Returns the value of an attribute of an element. Returns null if the attribute is not found (whereas Element.getAttribute returns "" if an attrib is not found).
      Parameters:
        `el` - Element whose attrib is looked for
        `attrName` - name of attribute to look for
      Returns:
        the attribute value

    - #### prettyPrint

          public static java.lang.String prettyPrint(org.w3c.dom.Element e)
                                              throws java.io.IOException

      Deprecated. relies on XMLSerializer which is a deprecated Xerces class, use domToString instead
      Throws:
        `java.io.IOException`

    - #### getAttributeNS

          public static java.lang.String getAttributeNS(org.w3c.dom.Element el,
                                        java.lang.String namespaceURI,
                                        java.lang.String localPart)

      Returns the value of an attribute of an element. Returns null if the attribute is not found (whereas Element.getAttributeNS returns "" if an attrib is not found).
      Parameters:
        `el` - Element whose attrib is looked for
        `namespaceURI` - namespace URI of attribute to look for
        `localPart` - local part of attribute to look for
      Returns:
        the attribute value

    - #### getChildCharacterData

          public static java.lang.String getChildCharacterData(org.w3c.dom.Element parentEl)

      Concat all the text and cdata node children of this elem and return the resulting text.
      Parameters:
        `parentEl` - the element whose cdata/text node values are to be combined.
      Returns:
        the concatanated string.

    - #### getElementByID

          public static org.w3c.dom.Element getElementByID(org.w3c.dom.Element el,
                                           java.lang.String id)

      DOCUMENTME
      Parameters:
        `el` - DOCUMENTME
        `id` - DOCUMENTME
      Returns:
        DOCUMENTME

    - #### getFirstChildElement

          public static org.w3c.dom.Element getFirstChildElement(org.w3c.dom.Element elem)

      Return the first child element of the given element. Null if no children are found.
      Parameters:
        `elem` - Element whose child is to be returned
      Returns:
        the first child element.

    - #### getNamespaceURIFromPrefix

          public static java.lang.String getNamespaceURIFromPrefix(org.w3c.dom.Node context,
                                                   java.lang.String prefix)

      Given a prefix and a node, return the namespace URI that the prefix has been associated with. This method is useful in resolving the namespace URI of attribute values which are being interpreted as QNames. If prefix is null, this method will return the default namespace.
      Parameters:
        `context` - the starting node (looks up recursively from here)
        `prefix` - the prefix to find an xmlns:prefix=uri for
      Returns:
        the namespace URI or null if not found

    - #### getNextSiblingElement

          public static org.w3c.dom.Element getNextSiblingElement(org.w3c.dom.Element elem)

      Return the next sibling element of the given element. Null if no more sibling elements are found.
      Parameters:
        `elem` - Element whose sibling element is to be returned
      Returns:
        the next sibling element.

    - #### getQualifiedAttributeValue

          public static javax.xml.namespace.QName getQualifiedAttributeValue(org.w3c.dom.Element el,
                                                             java.lang.String attrName)
                                                                      throws java.lang.IllegalArgumentException

      DOCUMENTME
      Parameters:
        `el` - DOCUMENTME
        `attrName` - DOCUMENTME
      Returns:
        DOCUMENTME
      Throws:
        `java.lang.IllegalArgumentException` - DOCUMENTME

    - #### countKids

          public static int countKids(org.w3c.dom.Element elem,
                      short nodeType)

      Count number of children of a certain type of the given element.
      Parameters:
        `elem` - the element whose kids are to be counted
        `nodeType` - DOCUMENTME
      Returns:
        the number of matching kids.

    - #### getParentNamespaces

          public static java.util.Map<java.lang.String,java.lang.String> getParentNamespaces(org.w3c.dom.Element el)

      This method traverses the DOM and grabs namespace declarations on parent elements with the intent of preserving them for children. Note that the DOM level 3 document method `Element.getAttribute(java.lang.String)` is not desirable in this case, as it does not respect namespace prefix bindings that may affect attribute values. (Namespaces in DOM are uncategorically a mess, especially in the context of XML Schema.)
      Parameters:
        `el` - the starting element
      Returns:
        a `Map` containing prefix bindings.

    - #### getMyNSContext

          public static NSContext getMyNSContext(org.w3c.dom.Element el)

      Construct a `NSContext` instance for the supplied element.
      Parameters:
        `el` - the `Element` to gather the namespace context for
      Returns:
        the `NSContext`

    - #### getMyNamespaces

          public static java.util.Map<java.lang.String,java.lang.String> getMyNamespaces(org.w3c.dom.Element el)

    - #### isNSAttribute

          public static boolean isNSAttribute(org.w3c.dom.Attr a)

      Test whether an attribute contains a namespace declaration.
      Parameters:
        `a` - an `Attr` to test.
      Returns:
        `true` if the `Attr` is a namespace declaration

    - #### getNSPrefixFromNSAttr

          public static java.lang.String getNSPrefixFromNSAttr(org.w3c.dom.Attr a)

      Fetch the non-null namespace prefix from a `Attr` that declares a namespace. (The DOM APIs will return `null` for a non-prefixed declaration.
      Parameters:
        `a` - the `Attr` with the declaration (must be non-`null`
      Returns:
        the namespace prefix or `""` if none was declared, e.g., `xmlns="foo"`.

    - #### domToString

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

      Convert a DOM node to a stringified XML representation.

    - #### serialize

          public static void serialize(org.w3c.dom.Element elmt,
                       java.io.OutputStream ostr)

    - #### domToStringLevel2

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

      Convert a DOM node to a stringified XML representation.

    - #### findChildElementWithAttribute

          public static org.w3c.dom.Element findChildElementWithAttribute(org.w3c.dom.Element elem,
                                                          java.lang.String attrName,
                                                          java.lang.String attrValue)

      Return the first child element of the given element which has the given attribute with the given value.
      Parameters:
        `elem` - the element whose children are to be searched
        `attrName` - the attrib that must be present
        `attrValue` - the desired value of the attribute
      Returns:
        the first matching child element.

    - #### stringToDOM

          public static org.w3c.dom.Element stringToDOM(java.lang.String s)
                                                 throws org.xml.sax.SAXException,
                                                        java.io.IOException

      Parse a String into a DOM.
      Parameters:
        `s` - DOCUMENTME
      Returns:
        DOCUMENTME
      Throws:
        `org.xml.sax.SAXException` - DOCUMENTME
        `java.io.IOException` - DOCUMENTME

    - #### isWsdlDocument

          public static boolean isWsdlDocument(org.w3c.dom.Document d)

      Perform a naive check to see if a document is a WSDL document based on the root element name and namespace URI.
      Parameters:
        `d` - the `Document` to check
      Returns:
        `true` if the root element appears correct

    - #### isXmlSchemaDocument

          public static boolean isXmlSchemaDocument(org.w3c.dom.Document d)

      Perform a naive check to see if a document is an XML schema document based on the root element name and namespace URI.
      Parameters:
        `d` - the `Document` to check
      Returns:
        `true` if the root element appears correct

    - #### pancakeNamespaces

          public static void pancakeNamespaces(org.w3c.dom.Element el)

      Parameters:
        `el` -

    - #### newDocument

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

    - #### parse

          public static org.w3c.dom.Document parse(java.io.InputStream inputStream)
                                            throws org.xml.sax.SAXException,
                                                   java.io.IOException

      Parse an XML stream using the pooled document builder.
      Parameters:
        `inputStream` - input stream
      Returns:
        parsed XML document
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### parse

          public static org.w3c.dom.Document parse(org.xml.sax.InputSource inputSource)
                                            throws org.xml.sax.SAXException,
                                                   java.io.IOException

      Parse an XML document located using an `InputSource` using the pooled document builder.
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### sourceToDOM

          public static org.w3c.dom.Document sourceToDOM(javax.xml.transform.Source inputSource)
                                                  throws java.io.IOException

      Parse an XML document located using an `InputSource` using the pooled document builder.
      Throws:
        `java.io.IOException`

    - #### isEmptyElement

          public static boolean isEmptyElement(org.w3c.dom.Element el)

      Check that an element is empty, i.e., it contains no non-whitespace text or elements as children.
      Parameters:
        `el` - the element
      Returns:
        `true` if the element is empty, `false` if not.

    - #### getNodeQName

          public static javax.xml.namespace.QName getNodeQName(org.w3c.dom.Node el)

    - #### getNodeQName

          public static javax.xml.namespace.QName getNodeQName(java.lang.String qualifiedName)

    - #### removeChildren

          public static void removeChildren(org.w3c.dom.Node target)

      Remove the child nodes under another node.
      Parameters:
        `target` - the `Node` to remove the children from.

    - #### removeAttributes

          public static void removeAttributes(org.w3c.dom.Element target,
                              boolean flag)

      Drop the attributes from an element, except possibly an `xmlns` attribute that declares its namespace.
      Parameters:
        `target` - the element whose attributes will be removed.
        `flag` - preserve namespace declaration

    - #### findChildByName

          public static org.w3c.dom.Element findChildByName(org.w3c.dom.Element parent,
                                            javax.xml.namespace.QName name)

    - #### findChildByName

          public static org.w3c.dom.Element findChildByName(org.w3c.dom.Element parent,
                                            javax.xml.namespace.QName name,
                                            boolean recurse)

    - #### findChildByType

          public static org.w3c.dom.Node findChildByType(org.w3c.dom.Element elem,
                                         int type)

    - #### getTextContent

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

    - #### getElementContent

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

    - #### injectNamespaces

          public static void injectNamespaces(org.w3c.dom.Element domElement,
                              NSContext nscontext)

    - #### injectNamespacesWithAllPrefixes

          public static void injectNamespacesWithAllPrefixes(org.w3c.dom.Element domElement,
                                             NSContext nscontext)

      Adds namespaces including all prefixes. This is needed for correct handling of xsi:type attributes.
      Parameters:
        `domElement` - An element wi which the namespace attributes should be added.
        `nscontext` - A namespace context.

    - #### copyNSContext

          public static void copyNSContext(org.w3c.dom.Element source,
                           org.w3c.dom.Element dest)

    - #### toDOMDocument

          public static org.w3c.dom.Document toDOMDocument(org.w3c.dom.Node node)
                                                    throws javax.xml.transform.TransformerException

      Throws:
        `javax.xml.transform.TransformerException`

    - #### toDocumentFromStream

          public static org.w3c.dom.Document toDocumentFromStream(javax.xml.transform.stream.StreamSource source)
                                                           throws java.io.IOException,
                                                                  org.xml.sax.SAXException

      Throws:
        `java.io.IOException`
        `org.xml.sax.SAXException`

    - #### parse

          public static org.w3c.dom.Document parse(javax.xml.stream.XMLStreamReader reader)
                                            throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### findChildrenByName

          public static java.util.List<org.w3c.dom.Element> findChildrenByName(org.w3c.dom.Element parent,
                                                               javax.xml.namespace.QName name)

    - #### toList

          public static java.util.List<org.w3c.dom.Node> toList(java.lang.Object nl)

      Somewhat eases the pain of dealing with both Lists and Nodelists by converting either passed as parameter to a List.
      Parameters:
        `nl` - a NodeList or a List
      Returns:
        a List

    - #### getDocument

          public static org.w3c.dom.Document getDocument(org.w3c.dom.Node contextNode)

    - #### getQualifiedName

          public static java.lang.String getQualifiedName(javax.xml.namespace.QName qName)

    - #### cloneNode

          public static org.w3c.dom.Node cloneNode(org.w3c.dom.Document document,
                                   org.w3c.dom.Node sourceNode)

      Deep clone, but don't fry, the given node in the context of the given document. For all intents and purposes, the clone is the exact same copy of the node, except that it might have a different owner document. This method is fool-proof, unlike the `adoptNode` or `adoptNode` methods, in that it doesn't assume that the given node has a parent or a owner document.
      Parameters:
        `document` -
        `sourceNode` -
      Returns:
        a clone of node

    - #### stringToDOM

          public static org.w3c.dom.Element stringToDOM(byte[] bytes)
                                                 throws org.xml.sax.SAXException,
                                                        java.io.IOException

      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### domToBytes

          public static byte[] domToBytes(org.w3c.dom.Element element)