Package org.smooks.support

Class DomUtils

  • public final class DomUtils
extends Object
    W3C DOM utility methods.
    Author:
    tfennelly

    • Method Detail

      • copyChildNodes

        public static void copyChildNodes​(Node source,
                                  Node target)
        Copy child node references from source to target.
        Parameters:
        source - Source Node.
        target - Target Node.

      • replaceNode

        public static void replaceNode​(Node newNode,
                               Node oldNode)
        Replace one node with another node.
        Parameters:
        newNode - New node - added in same location as oldNode.
        oldNode - Old node - removed.

      • replaceNode

        public static void replaceNode​(NodeList newNodes,
                               Node oldNode)
        Replace one node with a list of nodes.

        Clones the NodeList elements.

        Parameters:
        newNodes - New nodes - added in same location as oldNode.
        oldNode - Old node - removed.

      • replaceNode

        public static void replaceNode​(NodeList newNodes,
                               Node oldNode,
                               boolean clone)
        Replace one node with a list of nodes.
        Parameters:
        newNodes - New nodes - added in same location as oldNode.
        oldNode - Old node - removed.
        clone - Clone Nodelist Nodes.

      • insertBefore

        public static void insertBefore​(Node newNode,
                                Node refNode)
        Insert the supplied node before the supplied reference node (refNode).
        Parameters:
        newNode - Node to be inserted.
        refNode - Reference node before which the supplied nodes should be inserted.

      • insertBefore

        public static void insertBefore​(NodeList newNodes,
                                Node refNode)
        Insert the supplied nodes before the supplied reference node (refNode).
        Parameters:
        newNodes - Nodes to be inserted.
        refNode - Reference node before which the supplied nodes should be inserted.

      • renameElement

        public static Element renameElement​(Element element,
                                    String replacementElement,
                                    boolean keepChildContent,
                                    boolean keepAttributes)
        Rename element.
        Parameters:
        element - The element to be renamed.
        replacementElement - The tag name of the replacement element.
        keepChildContent - true if the target element's child content is to be copied to the replacement element, false if not. Default true.
        keepAttributes - true if the target element's attributes are to be copied to the replacement element, false if not. Default true.
        Returns:
        The renamed element.

      • renameElementNS

        public static Element renameElementNS​(Element element,
                                      String replacementElement,
                                      String namespace,
                                      boolean keepChildContent,
                                      boolean keepAttributes)
        Rename element.
        Parameters:
        element - The element to be renamed.
        replacementElement - The tag name of the replacement element. Can be a prefix qualified name if the namespace is not the null namepsace (XMLConstants.NULL_NS_URI).
        namespace - The element namespace.
        keepChildContent - true if the target element's child content is to be copied to the replacement element, false if not. Default true.
        keepAttributes - true if the target element's attributes are to be copied to the replacement element, false if not. Default true.
        Returns:
        The renamed element.

      • removeElement

        public static void removeElement​(Element element,
                                 boolean keepChildren)
        Remove the supplied element from its containing document.

        Tries to manage scenarios where a request is made to remove the root element. Cannot remove the root element in any of the following situations:

        • "keepChildren" parameter is false.
        • root element is empty of Node.ELEMENT_NODE nodes.
        Parameters:
        element - Element to be removed.
        keepChildren - Keep child content.

      • removeChildren

        public static void removeChildren​(Node node)
        Remove all child nodes from the supplied node.
        Parameters:
        node - to be "cleared".

      • copyNodeList

        public static List copyNodeList​(NodeList nodeList)
        Copy the nodes of a NodeList into the supplied list.

        This is not a clone. It's just a copy of the node references.

        Allows iteration over the Nodelist using the copy in the knowledge that the list will remain the same length. Using the NodeList can result in problems because elements can get removed from the list while we're iterating over it.

        Parameters:
        nodeList - Nodelist to copy.
        Returns:
        List copy.

      • appendList

        public static void appendList​(Node node,
                              List nodes)
        Append the nodes from the supplied list to the supplied node.
        Parameters:
        node - Node to be appended to.
        nodes - List of nodes to append.

      • getBooleanAttrib

        public static boolean getBooleanAttrib​(Element element,
                                       String attribName)
        Get a boolean attribute from the supplied element.
        Parameters:
        element - The element.
        attribName - The attribute name.
        Returns:
        True if the attribute value is "true" (case insensitive), otherwise false.

      • getBooleanAttrib

        public static boolean getBooleanAttrib​(Element element,
                                       String attribName,
                                       String namespaceURI)
        Get a boolean attribute from the supplied element.
        Parameters:
        element - The element.
        namespaceURI - Namespace URI of the required attribute.
        attribName - The attribute name.
        Returns:
        True if the attribute value is "true" (case insensitive), otherwise false.

      • getParentElement

        public static Element getParentElement​(Element child,
                                       String parentLocalName)
        Get the parent element of the supplied element having the specified tag name.
        Parameters:
        child - Child element.
        parentLocalName - Parent element local name.
        Returns:
        The first parent element of "child" having the tagname "parentName", or null if no such parent element exists.

      • getParentElement

        public static Element getParentElement​(Element child,
                                       String parentLocalName,
                                       String namespaceURI)
        Get the parent element of the supplied element having the specified tag name.
        Parameters:
        child - Child element.
        parentLocalName - Parent element local name.
        namespaceURI - Namespace URI of the required parent element, or null if a non-namespaced get is to be performed.
        Returns:
        The first parent element of "child" having the tagname "parentName", or null if no such parent element exists.

      • getName

        public static String getName​(Element element)
        Get the name from the supplied element.

        Returns the localName of the element if set (namespaced element), otherwise the element's tagName is returned.

        Parameters:
        element - The element.
        Returns:
        The element name.

      • getAttributeValue

        public static String getAttributeValue​(Element element,
                                       String attributeName)
        Get attribute value, returning null if unset.

        Some DOM implementations return an empty string for an unset attribute.

        Parameters:
        element - The DOM element.
        attributeName - The attribute to get.
        Returns:
        The attribute value, or null if unset.

      • getAttributeValue

        public static String getAttributeValue​(Element element,
                                       String attributeName,
                                       String namespaceURI)
        Get attribute value, returning null if unset.

        Some DOM implementations return an empty string for an unset attribute.

        Parameters:
        element - The DOM element.
        attributeName - The attribute to get.
        namespaceURI - Namespace URI of the required attribute, or null to perform a non-namespaced get.
        Returns:
        The attribute value, or null if unset.

      • getPreviousSibling

        public static Node getPreviousSibling​(Node node,
                                      short nodeType)

      • countNodesBefore

        public static int countNodesBefore​(Node node,
                                   short nodeType)
        Count the DOM nodes of the supplied type (nodeType) before the supplied node, not including the node itself.

        Counts the sibling nodes.

        Parameters:
        node - Node whose siblings are to be counted.
        nodeType - The DOM Node type of the siblings to be counted.
        Returns:
        The number of siblings of the supplied type before the supplied node.

      • countNodesBetween

        public static int countNodesBetween​(Node node1,
                                    Node node2,
                                    short nodeType)
        Count the DOM nodes of the supplied type (nodeType) between the supplied sibling nodes, not including the nodes themselves.

        Counts the sibling nodes.

        Parameters:
        node1 - First sibling node.
        node2 - Second sibling node.
        nodeType - The DOM Node type of the siblings to be counted.
        Returns:
        The number of siblings of the supplied type between the supplied sibling nodes.
        Throws:
        UnsupportedOperationException - if the supplied Nodes don't have the same parent node i.e. are not sibling nodes.

      • countNodesBefore

        public static int countNodesBefore​(Node node)
        Count the DOM nodes before the supplied node, not including the node itself.

        Counts the sibling nodes.

        Parameters:
        node - Node whose siblings are to be counted.
        Returns:
        The number of siblings before the supplied node.

      • countNodesBetween

        public static int countNodesBetween​(Node node1,
                                    Node node2)
        Count the DOM nodes between the supplied sibling nodes, not including the nodes themselves.

        Counts the sibling nodes.

        Parameters:
        node1 - First sibling node.
        node2 - Second sibling node.
        Returns:
        The number of siblings between the supplied sibling nodes.
        Throws:
        UnsupportedOperationException - if the supplied Nodes don't have the same parent node i.e. are not sibling nodes.

      • countElementsBefore

        public static int countElementsBefore​(Node node,
                                      String tagName)
        Count the DOM element nodes before the supplied node, having the specified tag name, not including the node itself.

        Counts the sibling nodes.

        Parameters:
        node - Node whose element siblings are to be counted.
        tagName - The tag name of the sibling elements to be counted.
        Returns:
        The number of siblings elements before the supplied node with the specified tag name.

      • getTextBefore

        public static String getTextBefore​(Node node)
        Get all the text DOM sibling nodes before the supplied node and concatenate them together into a single String.
        Parameters:
        node - Text node.
        Returns:
        String containing the concatentated text.

      • getTextBetween

        public static String getTextBetween​(Node node1,
                                    Node node2)
        Get all the text DOM sibling nodes before the supplied node and concatenate them together into a single String.
        Parameters:
        node1 - Test node.
        Returns:
        String containing the concatentated text.

      • getXPath

        public static String getXPath​(Node node)
        Construct the XPath of the supplied DOM Node.

        Supports element, comment and cdata sections DOM Node types.

        Parameters:
        node - DOM node for XPath generation.
        Returns:
        XPath string representation of the supplied DOM Node.

      • getDepth

        public static int getDepth​(Node node)

      • getAllText

        public static String getAllText​(Element parent,
                                boolean removeEntities)
        Get the combined text from all the text, comment and cdata DOM nodes contained within the supplied parent element.
        Parameters:
        parent - The parent DOM element.
        removeEntities - Remove all HTML entity and character references from the DOM Text child nodes and replace them with their equivalent characters. Note this is not performed on Comment or CDATA section nodes.
        Returns:
        The combined (concatenated) contents of all child text, comment and cdata DOM nodes. An empty String no such nodes are present.

      • addLiteral

        public static void addLiteral​(Element element,
                              String literalText)
        Add literal text to the supplied element.
        Parameters:
        element - Target DOM Element.
        literalText - Literal text to be added.

      • getElement

        public static Element getElement​(Element parent,
                                 String localname,
                                 int position)
        Get the child element having the supplied localname, position and namespace.

        Can be used instead of XPath.

        Parameters:
        parent - Parent element to be searched.
        localname - Localname of the element required.
        position - The position of the element relative to other sibling elements having the same name (and namespace if specified) e.g. if searching for the 2nd <input> element, this param needs to have a value of 2.
        Returns:
        The element at the requested position, or null if no such child element exists on the parent element.

      • getElement

        public static Element getElement​(Element parent,
                                 String localname,
                                 int position,
                                 String namespaceURI)
        Get the child element having the supplied localname, position and namespace.

        Can be used instead of XPath.

        Parameters:
        parent - Parent element to be searched.
        localname - Localname of the element required.
        position - The position of the element relative to other sibling elements having the same name (and namespace if specified) e.g. if searching for the 2nd <input> element, this param needs to have a value of 2.
        namespaceURI - Namespace URI of the required element, or null if a namespace comparison is not to be performed.
        Returns:
        The element at the requested position, or null if no such child element exists on the parent element.

      • getElements

        public static List getElements​(Element parent,
                               String localname,
                               String namespaceURI)
        Get the child elements having the supplied localname and namespace.

        Can be used instead of XPath.

        Parameters:
        parent - Parent element to be searched.
        localname - Localname of the element required. Supports "*" wildcards.
        namespaceURI - Namespace URI of the required element, or null if a namespace comparison is not to be performed.
        Returns:
        A list of W3C DOM Elements. An empty list if no such child elements exist on the parent element.

      • getElements

        public static List getElements​(NodeList nodeList,
                               String localname,
                               String namespaceURI)
        Get the child elements having the supplied localname and namespace.

        Can be used instead of XPath.

        Parameters:
        nodeList - List of DOM nodes on which to perform the search.
        localname - Localname of the element required. Supports "*" wildcards.
        namespaceURI - Namespace URI of the required element, or null if a namespace comparison is not to be performed.
        Returns:
        A list of W3C DOM Elements. An empty list if no such child elements exist on the parent element.

      • getElementByTagName

        public static Element getElementByTagName​(Element configElement,
                                          String name)