net.sf.practicalxml

Class DomUtil

java.lang.Object

net.sf.practicalxml.DomUtil

public class DomUtil
extends Object

A collection of static utility methods for working with DOM trees. Most of these are usability workarounds for the org.w3c.dom interfaces.

Any method may throw XmlException, typically wrapping a checked exception from the DOM class.

Constructor Summary

Constructors

Constructor and Description
DomUtil()

Method Summary

Methods

Modifier and Type	Method and Description
static void	adoptChild(Element adopter, Element adoptee) Adopts a child from another DOM, appending it to the passed element.
static Element	appendChild(Element parent, String lclName) Appends a child element with the specified name and no namespace, to a passed parent element.
static Element	appendChild(Element parent, String nsUri, String qname) Appends a child element with the specified name and namespace, to a passed parent element.
static Element	appendChildInheritNamespace(Element parent, String qname) Appends a child element with the specified name to a passed parent element.
static Text	appendText(Element elem, String text) Appends the specified text as a new text node on the specified element.
static <T> List<T>	asList(NodeList nodelist, Class<T> ofClass) Creates a parameterized list from a NodeList, making it usable within the Java coding idiom.
static <T> List<T>	filter(NodeList list, Class<T> klass) Extracts all nodes of a given type from the passed NodeList, creating a Java list of the nodes in document order.
static String	getAbsolutePath(Element elem) Returns the path from the root of the document to the specified element, as an XPath expression using positional predicates to differentiate between nodes with the same local name, ignoring namespace.
static String	getAbsolutePath(Element elem, NamespaceContext nsLookup) Returns the path from the root of the document to the specified element, as an XPath expression using positional predicates to differentiate between nodes with the same name and namespace.
static String	getAbsolutePath(Element elem, NamespaceResolver nsLookup) Returns the path from the root of the document to the specified element, as an XPath expression using positional predicates to differentiate between nodes with the same name and namespace.
static List<Attr>	getAttributes(Element elem) Returns all attributes for the passed element, in a mutable list.
static Element	getChild(Node parent, String lclName) Returns the first child element with the given localname, null if there are no such nodes.
static Element	getChild(Node parent, String nsUri, String lclName) Returns the first child element with the given namespace and local name, null if there are no such elements.
static List<Element>	getChildren(Node parent) Returns all Element children of the passed node, in document order.
static List<Element>	getChildren(Node parent, String lclName) Returns the children of the passed element that have the given localname, ignoring namespace.
static List<Element>	getChildren(Node parent, String nsUri, String lclName) Returns the children of the passed element that have the given namespace and localname (ignoring prefix).
static String	getLocalName(Attr attr) Returns the local name of an attribute.
static String	getLocalName(Element elem) Returns the local name of an element.
static String	getPath(Element elem, String... attrNames) Returns the path from the root of the document to the specified element, consisting of each node's qualified name, separated by slashes.
static List<Element>	getSiblings(Element elem) Returns all Element children of the passed element's parent (ie, the element and its siblings).
static List<Element>	getSiblings(Element elem, String lclName) Returns all Element children of the passed element's parent that have the specified localname, ignoring namespace.
static List<Element>	getSiblings(Element elem, String nsUri, String lclName) Returns all Element children of the passed element's parent that have the specified namespace and local name.
static String	getText(Element elem) Returns the concatenation of all text and CDATA nodes that are immediate children of the passed node.
static boolean	hasChildren(Element elem) Determines whether the passed element has any child nodes, of any type.
static boolean	hasElementChildren(Element elem) Determines whether the passed element has any element children.
static boolean	hasTextChildren(Element elem) Determines whether the passed element has any text/cdata children.
static boolean	isNamed(Element elem, String nsUri, String localName) Determines whether the passed element has the expected namespace URI and local name.
static Document	newDocument() Creates a new empty Document.
static Element	newDocument(QName qname) Creates a new Document, along with a root Element with the specified qualified name.
static Element	newDocument(String name) Creates a new Document, along with a root Element with the specified name and no namespace.
static Element	newDocument(String nsUri, String qname) Creates a new Document, along with a root Element with the specified name and namespace.
static void	removeAllChildren(Node parent) Removes all children from the passed node.
static void	removeEmptyTextRecursive(Node node) Removes all descendent text nodes that contain only whitespace.
static void	setText(Element elem, String text) Replaces all existing text nodes on the specified element with a single node containing the specified text.
static void	trimTextRecursive(Node node) Removes leading and trailing whitespace from all descendent text nodes.

Methods inherited from class java.lang.Object

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

Constructor Detail

DomUtil

public DomUtil()

Method Detail

newDocument

public static Document newDocument()

Creates a new empty Document. Avoids the code cruft of factory creation.

newDocument

public static Element newDocument(String nsUri,
                  String qname)

Creates a new Document, along with a root Element with the specified name and namespace.

Parameters:

nsUri - Namespace for the root element. May be null to create an element sans namespace.

qname - Qualified name for the root element.

Returns:

The root element, as that's usually what you want to use.

newDocument

public static Element newDocument(String name)

Creates a new Document, along with a root Element with the specified name and no namespace.

Parameters:

name - Name for the root element.

Returns:

The root element, as that's usually what you want to use.

newDocument

public static Element newDocument(QName qname)

Creates a new Document, along with a root Element with the specified qualified name.

Parameters:

qname - Name for the root element.

Returns:

The root element, as that's usually what you want to use.

Since:

1.1.3

appendChild

public static Element appendChild(Element parent,
                  String lclName)

Appends a child element with the specified name and no namespace, to a passed parent element.

Parameters:

parent - The parent element.

lclName - Qualified name for the new element.

Returns:

The newly created child element.

appendChild

public static Element appendChild(Element parent,
                  String nsUri,
                  String qname)

Appends a child element with the specified name and namespace, to a passed parent element.

Parameters:

parent - The parent element.

nsUri - Namespace for the new element. May be null to create an element sans namespace.

qname - Qualified name for the new element.

Returns:

The newly created child element.

appendChildInheritNamespace

public static Element appendChildInheritNamespace(Element parent,
                                  String qname)

Appends a child element with the specified name to a passed parent element. The child will inherit the parent's namespace (if any), and may also inherit the parent's namespace prefix.

Parameters:

parent - The parent element.

qname - Qualified name for the new element. If passed a simple name, will inherit the parent's prefix if any.

Returns:

The newly created child element.

adoptChild

public static void adoptChild(Element adopter,
              Element adoptee)

Adopts a child from another DOM, appending it to the passed element.

Parameters:

adopter - The element that will become the new parent of the adoptee.

adoptee - The element to be adopted. After adoption, this element will no longer belong to its former DOM.

Since:

1.1.16

getSiblings

public static List<Element> getSiblings(Element elem)

Returns all Element children of the passed element's parent (ie, the element and its siblings). Result is in document order.

getSiblings

public static List<Element> getSiblings(Element elem,
                        String lclName)

Returns all Element children of the passed element's parent that have the specified localname, ignoring namespace. Result is in document order (and will only contain the passed element if it satisfies the name test).

getSiblings

public static List<Element> getSiblings(Element elem,
                        String nsUri,
                        String lclName)

Returns all Element children of the passed element's parent that have the specified namespace and local name. Result is in document order (note that it may not contain the passed element). Specified namespace may be null, in which case selected children must not have a namespace.

hasChildren

public static boolean hasChildren(Element elem)

Determines whether the passed element has any child nodes, of any type.

Since:

1.1.3

hasElementChildren

public static boolean hasElementChildren(Element elem)

Determines whether the passed element has any element children.

Since:

1.1.3

hasTextChildren

public static boolean hasTextChildren(Element elem)

Determines whether the passed element has any text/cdata children.

Since:

1.1.3

getChildren

public static List<Element> getChildren(Node parent)

Returns all Element children of the passed node, in document order. Will accept any node type, although only Document and Element make sense.

getChildren

public static List<Element> getChildren(Node parent,
                        String lclName)

Returns the children of the passed element that have the given localname, ignoring namespace.

Returns the children in document order. Returns an empty list if there are no children matching the specified name.

getChildren

public static List<Element> getChildren(Node parent,
                        String nsUri,
                        String lclName)

Returns the children of the passed element that have the given namespace and localname (ignoring prefix). Namespace may be null, in which case the child element must not have a namespace.

Returns the children in document order. Returns an empty list if there are no children matching the specified namespace/name.

getChild

public static Element getChild(Node parent,
               String lclName)

Returns the first child element with the given localname, null if there are no such nodes.

getChild

public static Element getChild(Node parent,
               String nsUri,
               String lclName)

Returns the first child element with the given namespace and local name, null if there are no such elements.

getAttributes

public static List<Attr> getAttributes(Element elem)

Returns all attributes for the passed element, in a mutable list.

getText

public static String getText(Element elem)

Returns the concatenation of all text and CDATA nodes that are immediate children of the passed node. If there are no text/CDATA nodes, returns null.

This method differs from Node.getTextContent() in two ways: the latter concatenates all descendent text nodes, and will return an empty string (rather than null) if there are none.

appendText

public static Text appendText(Element elem,
              String text)

Appends the specified text as a new text node on the specified element.

setText

public static void setText(Element elem,
           String text)

Replaces all existing text nodes on the specified element with a single node containing the specified text. This is not equivalent to Node.setTextContent(), which replaces all children with a single text node.

trimTextRecursive

public static void trimTextRecursive(Node node)

Removes leading and trailing whitespace from all descendent text nodes. Will remove text nodes that trim to an empty string.

removeEmptyTextRecursive

public static void removeEmptyTextRecursive(Node node)

Removes all descendent text nodes that contain only whitespace. These come from the newlines and indentation between child elements, and could be removed by by the parser if you had a DTD that specified element-only content.

removeAllChildren

public static void removeAllChildren(Node parent)

Removes all children from the passed node. The children remain associated with the document, and may be re-attached to this or another node.

getLocalName

public static String getLocalName(Element elem)

Returns the local name of an element. Unlike Node.getLocalName() , properly handles elements that don't have a namespace.

getLocalName

public static String getLocalName(Attr attr)

Returns the local name of an attribute. Unlike Node.getLocalName() , properly handles elements that don't have a namespace.

isNamed

public static boolean isNamed(Element elem,
              String nsUri,
              String localName)

Determines whether the passed element has the expected namespace URI and local name. The expected namespace may be null, in which case the element must not have a namespace.

asList

public static <T> List<T> asList(NodeList nodelist,
                 Class<T> ofClass)

Creates a parameterized list from a NodeList, making it usable within the Java coding idiom.

Parameters:

nodelist - The list of nodes to convert.

ofClass - The type of the nodes being converted.

Throws:

ClassCastException - if any node in the list is not the expected type.

filter

public static <T> List<T> filter(NodeList list,
                 Class<T> klass)

Extracts all nodes of a given type from the passed NodeList, creating a Java list of the nodes in document order.

Parameters:

list - The source list, which may contain any node type.

klass - The desired node type to extract from this list.

Since:

1.0.5

getPath

public static String getPath(Element elem,
             String... attrNames)

Returns the path from the root of the document to the specified element, consisting of each node's qualified name, separated by slashes. Accepts an arbitrary number of attribute names, and inserts these as predicates into the path nodes where they apply.

This method is meant primarily for logging and debugging. While the returned path can by passed to an XPath evaluator, it has several limitations: First, it doesn't handle namespaces, although it does use qualified names where they appear in the document. Second, it doesn't properly escape quotes in attribute values. Third, and most important, it doesn't differentiate between sibling nodes with the same name and attribute values.

If you want a path that can later be used to select the element, see getAbsolutePath(org.w3c.dom.Element)

getAbsolutePath

public static String getAbsolutePath(Element elem)

Returns the path from the root of the document to the specified element, as an XPath expression using positional predicates to differentiate between nodes with the same local name, ignoring namespace.

Warning: if your document has namespaces, you will not be able to use the returned path to select the same node. Use one of the other variants of this method instead.

getAbsolutePath

public static String getAbsolutePath(Element elem,
                     NamespaceContext nsLookup)

Returns the path from the root of the document to the specified element, as an XPath expression using positional predicates to differentiate between nodes with the same name and namespace.

The nsLookup parameter is used to retrieve prefixes for the passed element and its ancestors. If all namespaces can be resolved to a prefix, then the returned path may be evaluated against the document to retrieve the element.

If nsLookup does not have a mapping for a given namespace, the returned path will contain a dummy prefix of the form "NSx", where "x" is incremented for each unknown namespace. In this case, you will not be able to use the returned path to select the element, without adding context entries for those generated namespaces.

Note that any prefixes in the source document are ignored. If an element has a prefix in the source document, but that element's namespace is not present in nsLookup, the path will contain a generated prefix. Similarly, if nsLookup.getPrefix() returns a value for the prefix, that value is used for the generated path.

getAbsolutePath

public static String getAbsolutePath(Element elem,
                     NamespaceResolver nsLookup)

Returns the path from the root of the document to the specified element, as an XPath expression using positional predicates to differentiate between nodes with the same name and namespace.

The nsLookup parameter is used to retrieve prefixes for the passed element and its ancestors. If it does not contain a mapping for a given namespace, one will be added with a prefix of the form "NSx" (where "x" is a number that's incremented for each unknown namespace).

Note that any prefixes in the source document are ignored. If an element has a prefix in the source document, but that element's namespace is not present in nsLookup, the path will contain a generated prefix. Similarly, if nsLookup.getPrefix() returns a value for the prefix, that value is used for the generated path.

The returned path may be used to select the element, provided that nsLookup is provided as the namespace context.