com.helger.xml

Class XMLHelper

java.lang.Object

com.helger.xml.XMLHelper

@Immutable
public final class XMLHelper
extends Object

This class contains multiple XML utility methods.

Author:

Philip Helger

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XMLHelper.PathToNodeBuilder Builder class for the different possibilities to get the path of a node

Method Summary

Modifier and Type	Method and Description
static void	append(Node aParentNode, Iterable<?> aNodesToAppend)
static Node	append(Node aParentNode, Object aChild)
static Predicate<? super Element>	filterElementWithNamespace()
static Predicate<? super Element>	filterElementWithNamespace(String sNamespaceURI)
static Predicate<? super Element>	filterElementWithNamespaceAndLocalName(String sNamespaceURI, String sLocalName)
static Predicate<? super Element>	filterElementWithoutNamespace()
static Predicate<? super Element>	filterElementWithTagName(String sTagName)
static Predicate<? super Element>	filterElementWithTagNameNoNS(String sTagName)
static Predicate<? super Node>	filterNodeIsElement()
static void	forAllAttributes(Element aSrcNode, BiConsumer<? super String,? super String> aConsumer)
static void	forAllAttributes(Element aSrcNode, Consumer<? super Attr> aConsumer)
static com.helger.commons.collection.impl.ICommonsList<Attr>	getAllAttributesAsList(Element aSrcNode)
static com.helger.commons.collection.impl.ICommonsOrderedMap<String,String>	getAllAttributesAsMap(Element aSrcNode)
static String	getAttributeValue(Element aElement, String sAttrName) The latest version of XercesJ 2.9 returns an empty string for non existing attributes.
static String	getAttributeValue(Element aElement, String sAttrName, String sDefault) The latest version of XercesJ 2.9 returns an empty string for non existing attributes.
static String	getAttributeValueNS(Element aElement, String sNamespaceURI, String sAttrName) The latest version of XercesJ 2.9 returns an empty string for non existing attributes.
static String	getAttributeValueNS(Element aElement, String sNamespaceURI, String sAttrName, String sDefault) The latest version of XercesJ 2.9 returns an empty string for non existing attributes.
static com.helger.commons.collection.iterate.IIterableIterator<Element>	getChildElementIterator(Node aStartNode) Get an iterator over all child elements.
static com.helger.commons.collection.iterate.IIterableIterator<Element>	getChildElementIterator(Node aStartNode, String sTagName) Get an iterator over all child elements that have the desired tag name (but potentially a namespace URI).
static com.helger.commons.collection.iterate.IIterableIterator<Element>	getChildElementIteratorNoNS(Node aStartNode) Get an iterator over all child elements that have no namespace.
static com.helger.commons.collection.iterate.IIterableIterator<Element>	getChildElementIteratorNoNS(Node aStartNode, String sTagName) Get an iterator over all child elements that have no namespace and the desired tag name.
static com.helger.commons.collection.iterate.IIterableIterator<Element>	getChildElementIteratorNS(Node aStartNode, String sNamespaceURI)
static com.helger.commons.collection.iterate.IIterableIterator<Element>	getChildElementIteratorNS(Node aStartNode, String sNamespaceURI, String sLocalName)
static Element	getChildElementOfNames(Element aStartElement, String... aTagNames) Find a direct child using multiple levels, starting from a given start element.
static int	getDirectChildElementCount(Element aParent)
static int	getDirectChildElementCount(Element aParent, String sTagName)
static int	getDirectChildElementCountNoNS(Element aParent)
static int	getDirectChildElementCountNoNS(Element aParent, String sTagName)
static int	getDirectChildElementCountNS(Element aParent, String sNamespaceURI)
static int	getDirectChildElementCountNS(Element aParent, String sNamespaceURI, String sLocalName)
static Element	getDocumentElement(Node aNode)
static String	getElementName(Node aNode)
static Element	getFirstChildElement(Node aStartNode) Get the first direct child element of the passed element.
static Element	getFirstChildElementOfName(Node aStartNode, String sTagName) Search all child nodes of the given for the first element that has the specified tag name.
static Element	getFirstChildElementOfName(Node aStartNode, String sNamespaceURI, String sLocalName) Search all child nodes of the given for the first element that has the specified tag name.
static String	getFirstChildText(Node aStartNode) Get the content of the first Text child element of the passed element.
static int	getLength(NodeList aNL)
static String	getLocalNameOrName(Attr aAttr)
static String	getLocalNameOrTagName(Element aElement)
static String	getNamespaceURI(Node aNode)
static Document	getOwnerDocument(Node aNode) Get the owner document of the passed node.
static String	getPathToNode(Node aNode) Shortcut for getPathToNode(Node, String) using "/" as the separator.
static String	getPathToNode(Node aNode, String sSep) Get the path from root node to the passed node.
static String	getPathToNode2(Node aNode) Shortcut for getPathToNode2(Node,String) using "/" as the separator.
static String	getPathToNode2(Node aNode, String sSep) Get the path from root node to the passed node.
static String	getPrefix(Element aElement) Get the namespace prefix of the passed element in a safe way.
static QName	getQName(Element aElement) Get the QName of the passed element.
static QName	getXMLNSAttrQName(String sNSPrefix) Get the full qualified attribute name to use for the given namespace prefix.
static boolean	hasChildElementNodes(Node aStartNode) Check if the passed node has at least one direct child element or not.
static boolean	hasNamespaceURI(Node aNode, String sNamespaceURI)
static boolean	hasNoNamespaceURI(Node aNode)
static boolean	hasSameElementName(Element aFirst, Element aSecond)
static boolean	isEmpty(NodeList aNL)
static boolean	isInlineNode(Node aNode) Check if the passed node is a text node.
static void	iterateChildren(Node aParent, Consumer<? super Node> aConsumer) Iterate all child nodes of the provided element NOT recursive.
static XMLHelper.PathToNodeBuilder	pathToNodeBuilder()
static void	recursiveIterateChildren(Node aParent, Consumer<? super Node> aConsumer) Recursively iterate all children of the provided element.
static void	removeAllChildElements(Element aElement) Remove all child nodes of the given node.

Methods inherited from class java.lang.Object

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

Method Detail

getOwnerDocument

@Nullable
public static Document getOwnerDocument(@Nullable
                                                   Node aNode)

Get the owner document of the passed node. If the node itself is a document, only a cast is performed.

Parameters:

aNode - The node to get the document from. May be null.

Returns:

null if the passed node was null.

getDocumentElement

@Nullable
public static Element getDocumentElement(@Nullable
                                                    Node aNode)

getNamespaceURI

@Nullable
public static String getNamespaceURI(@Nullable
                                                Node aNode)

getLocalNameOrTagName

@Nonnull
public static String getLocalNameOrTagName(@Nonnull
                                                     Element aElement)

getLocalNameOrName

@Nonnull
public static String getLocalNameOrName(@Nonnull
                                                  Attr aAttr)

getElementName

@Nullable
public static String getElementName(@Nullable
                                               Node aNode)

hasNoNamespaceURI

public static boolean hasNoNamespaceURI(@Nonnull
                                        Node aNode)

hasNamespaceURI

public static boolean hasNamespaceURI(@Nullable
                                      Node aNode,
                                      @Nullable
                                      String sNamespaceURI)

isInlineNode

public static boolean isInlineNode(@Nullable
                                   Node aNode)

Check if the passed node is a text node. This includes all nodes derived from Text (Text and CData) or EntityReference nodes.

Parameters:

aNode - The node to be checked.

Returns:

true if the passed node is a text node, false otherwise.

getLength

@Nonnegative
public static int getLength(@Nullable
                                          NodeList aNL)

isEmpty

public static boolean isEmpty(@Nullable
                              NodeList aNL)

filterNodeIsElement

@Nonnull
public static Predicate<? super Node> filterNodeIsElement()

filterElementWithNamespace

@Nonnull
public static Predicate<? super Element> filterElementWithNamespace()

filterElementWithoutNamespace

@Nonnull
public static Predicate<? super Element> filterElementWithoutNamespace()

filterElementWithNamespace

@Nonnull
public static Predicate<? super Element> filterElementWithNamespace(@Nullable
                                                                              String sNamespaceURI)

filterElementWithNamespaceAndLocalName

@Nonnull
public static Predicate<? super Element> filterElementWithNamespaceAndLocalName(@Nullable
                                                                                          String sNamespaceURI,
                                                                                          @Nonnull @Nonempty
                                                                                          String sLocalName)

filterElementWithTagName

@Nonnull
public static Predicate<? super Element> filterElementWithTagName(@Nonnull @Nonempty
                                                                            String sTagName)

filterElementWithTagNameNoNS

@Nonnull
public static Predicate<? super Element> filterElementWithTagNameNoNS(@Nonnull @Nonempty
                                                                                String sTagName)

getFirstChildElement

@Nullable
public static Element getFirstChildElement(@Nullable
                                                      Node aStartNode)

Get the first direct child element of the passed element.

Parameters:

aStartNode - The element to start searching. May be null.

Returns:

null if the passed element does not have any direct child element.

hasChildElementNodes

public static boolean hasChildElementNodes(@Nullable
                                           Node aStartNode)

Check if the passed node has at least one direct child element or not.

Parameters:

aStartNode - The parent element to be searched. May be null.

Returns:

true if the passed node has at least one child element, false otherwise.

getFirstChildElementOfName

@Nullable
public static Element getFirstChildElementOfName(@Nullable
                                                            Node aStartNode,
                                                            @Nonnull @Nonempty
                                                            String sTagName)

Search all child nodes of the given for the first element that has the specified tag name.

Parameters:

aStartNode - The parent element to be searched. May be null.

sTagName - The tag name to search.

Returns:

null if the parent element has no such child element.

getFirstChildElementOfName

@Nullable
public static Element getFirstChildElementOfName(@Nullable
                                                            Node aStartNode,
                                                            @Nullable
                                                            String sNamespaceURI,
                                                            @Nonnull @Nonempty
                                                            String sLocalName)

Search all child nodes of the given for the first element that has the specified tag name.

Parameters:

aStartNode - The parent element to be searched. May be null.

sNamespaceURI - Namespace URI to search. May be null.

sLocalName - The tag name to search.

Returns:

null if the parent element has no such child element.

getChildElementOfNames

@Nullable
public static Element getChildElementOfNames(@Nullable
                                                        Element aStartElement,
                                                        @Nonnull
                                                        String... aTagNames)

Find a direct child using multiple levels, starting from a given start element.

Parameters:

aStartElement - The element to start from. May be null.

aTagNames - The child elements to be found in order. May neither be null nor empty and may not contain null elements.

Returns:

null if no such child element was found, of if the start element was null.

Since:

10.1.2

See Also:

getFirstChildElementOfName(Node, String)

append

@Nonnull
public static Node append(@Nonnull
                                    Node aParentNode,
                                    @Nullable
                                    Object aChild)

append

public static void append(@Nonnull
                          Node aParentNode,
                          @Nonnull
                          Iterable<?> aNodesToAppend)

getDirectChildElementCount

@Nonnegative
public static int getDirectChildElementCount(@Nullable
                                                           Element aParent)

getDirectChildElementCountNoNS

@Nonnegative
public static int getDirectChildElementCountNoNS(@Nullable
                                                               Element aParent)

getDirectChildElementCount

@Nonnegative
public static int getDirectChildElementCount(@Nullable
                                                           Element aParent,
                                                           @Nonnull @Nonempty
                                                           String sTagName)

getDirectChildElementCountNoNS

@Nonnegative
public static int getDirectChildElementCountNoNS(@Nullable
                                                               Element aParent,
                                                               @Nonnull @Nonempty
                                                               String sTagName)

getDirectChildElementCountNS

@Nonnegative
public static int getDirectChildElementCountNS(@Nullable
                                                             Element aParent,
                                                             @Nullable
                                                             String sNamespaceURI)

getDirectChildElementCountNS

@Nonnegative
public static int getDirectChildElementCountNS(@Nullable
                                                             Element aParent,
                                                             @Nullable
                                                             String sNamespaceURI,
                                                             @Nonnull @Nonempty
                                                             String sLocalName)

getChildElementIterator

@Nonnull
public static com.helger.commons.collection.iterate.IIterableIterator<Element> getChildElementIterator(@Nullable
                                                                                                                 Node aStartNode)

Get an iterator over all child elements.

Parameters:

aStartNode - the parent element

Returns:

a non-null Iterator

getChildElementIteratorNoNS

@Nonnull
public static com.helger.commons.collection.iterate.IIterableIterator<Element> getChildElementIteratorNoNS(@Nullable
                                                                                                                     Node aStartNode)

Get an iterator over all child elements that have no namespace.

Parameters:

aStartNode - the parent element

Returns:

a non-null Iterator

getChildElementIteratorNoNS

@Nonnull
public static com.helger.commons.collection.iterate.IIterableIterator<Element> getChildElementIteratorNoNS(@Nullable
                                                                                                                     Node aStartNode,
                                                                                                                     @Nonnull @Nonempty
                                                                                                                     String sTagName)

Get an iterator over all child elements that have no namespace and the desired tag name.

Parameters:

aStartNode - the parent element

sTagName - the name of the tag that is desired

Returns:

a non-null Iterator

Throws:

IllegalArgumentException - if the passed tag name is null or empty

getChildElementIterator

@Nonnull
public static com.helger.commons.collection.iterate.IIterableIterator<Element> getChildElementIterator(@Nullable
                                                                                                                 Node aStartNode,
                                                                                                                 @Nonnull @Nonempty
                                                                                                                 String sTagName)

Get an iterator over all child elements that have the desired tag name (but potentially a namespace URI).

Parameters:

aStartNode - the parent element

sTagName - the name of the tag that is desired

Returns:

a non-null Iterator

Throws:

IllegalArgumentException - if the passed tag name is null or empty

getChildElementIteratorNS

@Nonnull
public static com.helger.commons.collection.iterate.IIterableIterator<Element> getChildElementIteratorNS(@Nullable
                                                                                                                   Node aStartNode,
                                                                                                                   @Nullable
                                                                                                                   String sNamespaceURI)

getChildElementIteratorNS

@Nonnull
public static com.helger.commons.collection.iterate.IIterableIterator<Element> getChildElementIteratorNS(@Nullable
                                                                                                                   Node aStartNode,
                                                                                                                   @Nullable
                                                                                                                   String sNamespaceURI,
                                                                                                                   @Nonnull @Nonempty
                                                                                                                   String sLocalName)

hasSameElementName

public static boolean hasSameElementName(@Nonnull
                                         Element aFirst,
                                         @Nonnull
                                         Element aSecond)

pathToNodeBuilder

@Nonnull
public static XMLHelper.PathToNodeBuilder pathToNodeBuilder()

getPathToNode

@Nonnull
public static String getPathToNode(@Nonnull
                                             Node aNode)

Shortcut for getPathToNode(Node, String) using "/" as the separator.

Parameters:

aNode - The node to check.

Returns:

A non-null path.

getPathToNode

@Nonnull
public static String getPathToNode(@Nonnull
                                             Node aNode,
                                             @Nonnull
                                             String sSep)

Get the path from root node to the passed node. This includes all nodes up to the document node!

Parameters:

aNode - The node to start. May not be null.

sSep - The separator string to use. May not be null.

Returns:

The path to the node.

getPathToNode2

@Nonnull
public static String getPathToNode2(@Nonnull
                                              Node aNode)

Shortcut for getPathToNode2(Node,String) using "/" as the separator.

Parameters:

aNode - The node to check.

Returns:

A non-null path.

getPathToNode2

@Nonnull
public static String getPathToNode2(@Nonnull
                                              Node aNode,
                                              @Nonnull
                                              String sSep)

Get the path from root node to the passed node. This includes all nodes but excluding the document node!

Parameters:

aNode - The node to start. May not be null.

sSep - The separator string to use. May not be null.

Returns:

The path to the node.

removeAllChildElements

public static void removeAllChildElements(@Nonnull
                                          Element aElement)

Remove all child nodes of the given node.

Parameters:

aElement - The element whose children are to be removed.

getFirstChildText

@Nullable
public static String getFirstChildText(@Nullable
                                                  Node aStartNode)

Get the content of the first Text child element of the passed element.

Parameters:

aStartNode - the element to scan for a TextNode child

Returns:

null if the element contains no text node as child

getAttributeValue

@Nullable
public static String getAttributeValue(@Nonnull
                                                  Element aElement,
                                                  @Nonnull
                                                  String sAttrName)

The latest version of XercesJ 2.9 returns an empty string for non existing attributes. To differentiate between empty attributes and non-existing attributes, this method returns null for non existing attributes.

Parameters:

aElement - the source element to get the attribute from

sAttrName - the name of the attribute to query

Returns:

null if the attribute does not exists, the string value otherwise

getAttributeValue

@Nullable
public static String getAttributeValue(@Nonnull
                                                  Element aElement,
                                                  @Nonnull
                                                  String sAttrName,
                                                  @Nullable
                                                  String sDefault)

The latest version of XercesJ 2.9 returns an empty string for non existing attributes. To differentiate between empty attributes and non-existing attributes, this method returns a default value for non existing attributes.

Parameters:

aElement - the source element to get the attribute from. May not be null.

sAttrName - the name of the attribute to query. May not be null.

sDefault - the value to be returned if the attribute is not present.

Returns:

the default value if the attribute does not exists, the string value otherwise

getAttributeValueNS

@Nullable
public static String getAttributeValueNS(@Nonnull
                                                    Element aElement,
                                                    @Nullable
                                                    String sNamespaceURI,
                                                    @Nonnull
                                                    String sAttrName)

The latest version of XercesJ 2.9 returns an empty string for non existing attributes. To differentiate between empty attributes and non-existing attributes, this method returns null for non existing attributes.

Parameters:

aElement - the source element to get the attribute from

sNamespaceURI - The namespace URI of the attribute to retrieve. May be null.

sAttrName - the name of the attribute to query

Returns:

null if the attribute does not exists, the string value otherwise

getAttributeValueNS

@Nullable
public static String getAttributeValueNS(@Nonnull
                                                    Element aElement,
                                                    @Nullable
                                                    String sNamespaceURI,
                                                    @Nonnull
                                                    String sAttrName,
                                                    @Nullable
                                                    String sDefault)

The latest version of XercesJ 2.9 returns an empty string for non existing attributes. To differentiate between empty attributes and non-existing attributes, this method returns a default value for non existing attributes.

Parameters:

aElement - the source element to get the attribute from. May not be null.

sNamespaceURI - The namespace URI of the attribute to retrieve. May be null.

sAttrName - the name of the attribute to query. May not be null.

sDefault - the value to be returned if the attribute is not present.

Returns:

the default value if the attribute does not exists, the string value otherwise

getAllAttributesAsList

@Nonnull
 @ReturnsMutableCopy
public static com.helger.commons.collection.impl.ICommonsList<Attr> getAllAttributesAsList(@Nullable
                                                                                                                           Element aSrcNode)

getAllAttributesAsMap

@Nonnull
 @ReturnsMutableCopy
public static com.helger.commons.collection.impl.ICommonsOrderedMap<String,String> getAllAttributesAsMap(@Nullable
                                                                                                                                         Element aSrcNode)

forAllAttributes

public static void forAllAttributes(@Nullable
                                    Element aSrcNode,
                                    @Nonnull
                                    Consumer<? super Attr> aConsumer)

forAllAttributes

public static void forAllAttributes(@Nullable
                                    Element aSrcNode,
                                    @Nonnull
                                    BiConsumer<? super String,? super String> aConsumer)

getXMLNSAttrQName

@Nonnull
public static QName getXMLNSAttrQName(@Nullable
                                                String sNSPrefix)

Get the full qualified attribute name to use for the given namespace prefix. The result will e.g. be xmlns or {http://www.w3.org/2000/xmlns/}xmlns:foo.

Parameters:

sNSPrefix - The namespace prefix to build the attribute name from. May be null or empty.

Returns:

If the namespace prefix is empty (if it equals XMLConstants.DEFAULT_NS_PREFIX or null) than "xmlns" is returned, else "xmlns:prefix" is returned.

getPrefix

@Nonnull
public static String getPrefix(@Nullable
                                         Element aElement)

Get the namespace prefix of the passed element in a safe way.

Parameters:

aElement - The element to be queried. May be null.

Returns:

XMLConstants.DEFAULT_NS_PREFIX or the provided prefix. Never null.

Since:

8.4.1

getQName

@Nonnull
public static QName getQName(@Nonnull
                                       Element aElement)

Get the QName of the passed element. If the passed element has no namespace URI, only the tag name is used. Otherwise namespace URI, local name and prefix are used.

Parameters:

aElement - The element to be used. May not be null.

Returns:

The created QName.

Since:

8.4.1

iterateChildren

public static void iterateChildren(@Nonnull
                                   Node aParent,
                                   @Nonnull
                                   Consumer<? super Node> aConsumer)

Iterate all child nodes of the provided element NOT recursive. The provided consumer is invoked for every child node. Please note: the Consumer is not invoked for the parent element itself.

Parameters:

aParent - The parent node to start from. May not be null.

aConsumer - The Consumer to be invoked for every node. May not be null.

Since:

10.1.7

recursiveIterateChildren

public static void recursiveIterateChildren(@Nonnull
                                            Node aParent,
                                            @Nonnull
                                            Consumer<? super Node> aConsumer)

Recursively iterate all children of the provided element. The provided consumer is invoked for every child node. Please note: the Consumer is not invoked for the parent element itself.

Parameters:

aParent - The parent node to start from. May not be null.

aConsumer - The Consumer to be invoked for every node. May not be null.

Since:

10.1.7