org.milyn.xml
Class DomUtils

java.lang.Object
  org.milyn.xml.DomUtils

public abstract class DomUtils
extends Object

W3C DOM utility methods.

Author:

tfennelly

Constructor Summary

DomUtils()

Method Summary

static void	addLiteral(Element element, String literalText) Add literal text to the supplied element.
static void	appendList(Node node, List nodes) Append the nodes from the supplied list to the supplied node.
static void	copyChildNodes(Node source, Node target) Copy child node references from source to target.
static List	copyNodeList(NodeList nodeList) Copy the nodes of a NodeList into the supplied list.
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.
static int	countNodesBefore(Node node) Count the DOM nodes before the supplied node, not including the node itself.
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.
static int	countNodesBetween(Node node1, Node node2) Count the DOM nodes between the supplied sibling nodes, not including the nodes themselves.
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.
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.
static String	getAttributeValue(Element element, String attributeName) Get attribute value, returning null if unset.
static String	getAttributeValue(Element element, String attributeName, String namespaceURI) Get attribute value, returning null if unset.
static boolean	getBooleanAttrib(Element element, String attribName) Get a boolean attribute from the supplied element.
static boolean	getBooleanAttrib(Element element, String attribName, String namespaceURI) Get a boolean attribute from the supplied element.
static int	getDepth(Element element)
static Element	getElement(Element parent, String localname, int position) Get the child element having the supplied localname, position and namespace.
static Element	getElement(Element parent, String localname, int position, String namespaceURI) Get the child element having the supplied localname, position and namespace.
static List	getElements(Element parent, String localname, String namespaceURI) Get the child elements having the supplied localname and namespace.
static List	getElements(NodeList nodeList, String localname, String namespaceURI) Get the child elements having the supplied localname and namespace.
static String	getName(Element element) Get the name from the supplied element.
static Element	getParentElement(Element child, String parentLocalName) Get the parent element of the supplied element having the specified tag name.
static Element	getParentElement(Element child, String parentLocalName, String namespaceURI) Get the parent element of the supplied element having the specified tag name.
static Node	getPreviousSibling(Node node, short nodeType)
static String	getTextBefore(Node node) Get all the text DOM sibling nodes before the supplied node and concatenate them together into a single String.
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.
static String	getXPath(Node node) Construct the XPath of the supplied DOM Node.
static void	insertBefore(NodeList newNodes, Node refNode) Insert the supplied nodes before the supplied reference node (refNode).
static void	insertBefore(Node newNode, Node refNode) Insert the supplied node before the supplied reference node (refNode).
static void	removeChildren(Node node) Remove all child nodes from the supplied node.
static void	removeElement(Element element, boolean keepChildren) Remove the supplied element from its containing document.
static Element	renameElement(Element element, String replacementElement, boolean keepChildContent, boolean keepAttributes) Rename element.
static Element	renameElementNS(Element element, String replacementElement, String namespace, boolean keepChildContent, boolean keepAttributes) Rename element.
static void	replaceNode(NodeList newNodes, Node oldNode) Replace one node with a list of nodes.
static void	replaceNode(NodeList newNodes, Node oldNode, boolean clone) Replace one node with a list of nodes.
static void	replaceNode(Node newNode, Node oldNode) Replace one node with another node.

Methods inherited from class java.lang.Object

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

Constructor Detail

DomUtils

public DomUtils()

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(Element element)

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.