net.shibboleth.utilities.java.support.xml

Class ElementSupport

java.lang.Object

net.shibboleth.utilities.java.support.xml.ElementSupport

public final class ElementSupport
extends java.lang.Object

Set of helper methods for working with DOM Elements.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	ElementSupport() Constructor.

Method Summary

Modifier and Type	Method and Description
static void	adoptElement(org.w3c.dom.Document adopter, org.w3c.dom.Element adoptee) Adopts an element into a document if the child is not already in the document.
static void	appendChildElement(org.w3c.dom.Element parentElement, org.w3c.dom.Element childElement) Appends the child Element to the parent Element, adopting the child Element into the parent's Document if needed.
static void	appendTextContent(org.w3c.dom.Element element, java.lang.String textContent) Creates a text node with the given content and appends it as child to the given element.
static org.w3c.dom.Element	constructElement(org.w3c.dom.Document document, javax.xml.namespace.QName elementName) Constructs an element, rooted in the given document, with the given name.
static org.w3c.dom.Element	constructElement(org.w3c.dom.Document document, java.lang.String namespaceURI, java.lang.String localName, java.lang.String prefix) Constructs an element, rooted in the given document, with the given information.
static java.util.List<org.w3c.dom.Element>	getChildElements(org.w3c.dom.Node root) Gets the child elements of the given element.
static java.util.List<org.w3c.dom.Element>	getChildElements(org.w3c.dom.Node root, javax.xml.namespace.QName name) Gets the child nodes with the given local tag name.
static java.util.List<org.w3c.dom.Element>	getChildElementsByTagName(org.w3c.dom.Node root, java.lang.String localName) Gets the child nodes with the given local tag name.
static java.util.List<org.w3c.dom.Element>	getChildElementsByTagNameNS(org.w3c.dom.Node root, java.lang.String namespaceURI, java.lang.String localName) Gets the child nodes with the given namespace qualified tag name.
static org.w3c.dom.Element	getElementAncestor(org.w3c.dom.Node currentNode) Gets the ancestor element node to the given node.
static java.util.List<java.lang.String>	getElementContentAsList(org.w3c.dom.Element element) Gets the value of a list-type element as a list.
static javax.xml.namespace.QName	getElementContentAsQName(org.w3c.dom.Element element) Constructs a QName from an element's adjacent Text child nodes.
static java.lang.String	getElementContentAsString(org.w3c.dom.Element element) Gets the text content for this Element only.
static org.w3c.dom.Element	getFirstChildElement(org.w3c.dom.Node n) Gets the first child Element of the node, skipping any Text nodes such as whitespace.
static org.w3c.dom.Element	getFirstChildElement(org.w3c.dom.Node root, javax.xml.namespace.QName name) Returns the first child element of the supplied element with the supplied name if it exists.
static java.util.Map<javax.xml.namespace.QName,java.util.List<org.w3c.dom.Element>>	getIndexedChildElements(org.w3c.dom.Element root) Gets the child elements of the given element in a single iteration.
static org.w3c.dom.Element	getNextSiblingElement(org.w3c.dom.Node n) Gets the next sibling Element of the node, skipping any Text nodes such as whitespace.
static boolean	isElementNamed(org.w3c.dom.Element e, javax.xml.namespace.QName name) Check if the given Element has the given name.
static boolean	isElementNamed(org.w3c.dom.Element e, java.lang.String ns, java.lang.String localName) Shortcut for checking a DOM element node's namespace and local name.
static void	setDocumentElement(org.w3c.dom.Document document, org.w3c.dom.Element element) Sets a given Element as the root element of a given document.

Methods inherited from class java.lang.Object

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

Constructor Detail

ElementSupport

private ElementSupport()

Constructor.

Method Detail

adoptElement

public static void adoptElement(@Nonnull
                                org.w3c.dom.Document adopter,
                                @Nonnull
                                org.w3c.dom.Element adoptee)

Adopts an element into a document if the child is not already in the document.

Parameters:

adoptee - the element to be adopted

adopter - the document into which the element is adopted

appendChildElement

public static void appendChildElement(@Nonnull
                                      org.w3c.dom.Element parentElement,
                                      @Nullable
                                      org.w3c.dom.Element childElement)

Appends the child Element to the parent Element, adopting the child Element into the parent's Document if needed.

Parameters:

parentElement - the parent Element

childElement - the child Element

appendTextContent

public static void appendTextContent(@Nonnull
                                     org.w3c.dom.Element element,
                                     @Nullable
                                     java.lang.String textContent)

Creates a text node with the given content and appends it as child to the given element.

Parameters:

element - the element to receive the text node

textContent - the content for the text node

constructElement

public static org.w3c.dom.Element constructElement(@Nonnull
                                                   org.w3c.dom.Document document,
                                                   @Nonnull
                                                   javax.xml.namespace.QName elementName)

Constructs an element, rooted in the given document, with the given name.

Parameters:

document - the document containing the element

elementName - the name of the element, must contain a local name, may contain a namespace URI and prefix

Returns:

the element

constructElement

public static org.w3c.dom.Element constructElement(@Nonnull
                                                   org.w3c.dom.Document document,
                                                   @Nullable
                                                   java.lang.String namespaceURI,
                                                   @Nonnull
                                                   java.lang.String localName,
                                                   @Nullable
                                                   java.lang.String prefix)

Constructs an element, rooted in the given document, with the given information.

Parameters:

document - the document containing the element

namespaceURI - the URI of the namespace the element is in

localName - the element's local name

prefix - the prefix of the namespace the element is in

Returns:

the element

getChildElements

@Nonnull
public static java.util.List<org.w3c.dom.Element> getChildElements(@Nullable
                                                                            org.w3c.dom.Node root)

Gets the child elements of the given element.

Parameters:

root - element to get the child elements of

Returns:

list of child elements or an empty list if the root is null.

getChildElements

@Nonnull
public static java.util.List<org.w3c.dom.Element> getChildElements(@Nullable
                                                                            org.w3c.dom.Node root,
                                                                            @Nullable
                                                                            javax.xml.namespace.QName name)

Gets the child nodes with the given local tag name. If you need to retrieve multiple, named, children consider using getChildElements(Node).

Parameters:

root - element to retrieve the children from

name - name of the child elements to be retrieved

Returns:

list of child elements, never null

getFirstChildElement

@Nullable
public static org.w3c.dom.Element getFirstChildElement(@Nullable
                                                                 org.w3c.dom.Node root,
                                                                 @Nullable
                                                                 javax.xml.namespace.QName name)

Returns the first child element of the supplied element with the supplied name if it exists. Otherwise null. See getChildElements(Node, QName).

Parameters:

root - element to parse child elements

name - name of the child elements to parse

Returns:

first child element or null

getChildElementsByTagName

@Nonnull
public static java.util.List<org.w3c.dom.Element> getChildElementsByTagName(@Nullable
                                                                                     org.w3c.dom.Node root,
                                                                                     @Nullable
                                                                                     java.lang.String localName)

Gets the child nodes with the given local tag name. If you need to retrieve multiple, named, children consider using getChildElements(Node).

Parameters:

root - element to retrieve the children from

localName - local, tag, name of the child element

Returns:

list of child elements, never null

getChildElementsByTagNameNS

@Nonnull
public static java.util.List<org.w3c.dom.Element> getChildElementsByTagNameNS(@Nullable
                                                                                       org.w3c.dom.Node root,
                                                                                       @Nullable
                                                                                       java.lang.String namespaceURI,
                                                                                       @Nullable
                                                                                       java.lang.String localName)

Gets the child nodes with the given namespace qualified tag name. If you need to retrieve multiple, named, children consider using getChildElements(Node).

Parameters:

root - element to retrieve the children from

namespaceURI - namespace URI of the child element

localName - local, tag, name of the child element

Returns:

list of child elements, never null

getElementAncestor

@Nullable
public static org.w3c.dom.Element getElementAncestor(@Nullable
                                                               org.w3c.dom.Node currentNode)

Gets the ancestor element node to the given node.

Parameters:

currentNode - the node to retrieve the ancestor for

Returns:

the ancestral element node of the current node, or null

getElementContentAsString

@Nonnull
public static java.lang.String getElementContentAsString(@Nullable
                                                                  org.w3c.dom.Element element)

Gets the text content for this Element only. Whereas Node.getTextContent() will return all text for this element and all children, this just grabs the text for this element (which may be spread over multiple lines).

Parameters:

element - The element to look at.

Returns:

The text content, or "" if there is none, never null.

getElementContentAsList

@Nonnull
public static java.util.List<java.lang.String> getElementContentAsList(@Nullable
                                                                                org.w3c.dom.Element element)

Gets the value of a list-type element as a list.

Parameters:

element - element whose value will be turned into a list

Returns:

list of values, never null

getElementContentAsQName

@Nullable
public static javax.xml.namespace.QName getElementContentAsQName(@Nullable
                                                                           org.w3c.dom.Element element)

Constructs a QName from an element's adjacent Text child nodes.

Parameters:

element - the element with a QName value

Returns:

a QName from an element's value, or null if the given element is empty

getFirstChildElement

@Nullable
public static org.w3c.dom.Element getFirstChildElement(@Nullable
                                                                 org.w3c.dom.Node n)

Gets the first child Element of the node, skipping any Text nodes such as whitespace.

Parameters:

n - The parent in which to search for children

Returns:

The first child Element of n, or null if none

getIndexedChildElements

@Nonnull
public static java.util.Map<javax.xml.namespace.QName,java.util.List<org.w3c.dom.Element>> getIndexedChildElements(@Nullable
                                                                                                                            org.w3c.dom.Element root)

Gets the child elements of the given element in a single iteration.

Parameters:

root - element to get the child elements of

Returns:

child elements indexed by namespace qualified tag name, never null

getNextSiblingElement

@Nullable
public static org.w3c.dom.Element getNextSiblingElement(@Nullable
                                                                  org.w3c.dom.Node n)

Gets the next sibling Element of the node, skipping any Text nodes such as whitespace.

Parameters:

n - The sibling to start with

Returns:

The next sibling Element of n, or null if none

isElementNamed

public static boolean isElementNamed(@Nullable
                                     org.w3c.dom.Element e,
                                     @Nullable
                                     javax.xml.namespace.QName name)

Check if the given Element has the given name.

Parameters:

e - element to check

name - name to check for

Returns:

true if the element has the given name, false otherwise

isElementNamed

public static boolean isElementNamed(@Nullable
                                     org.w3c.dom.Element e,
                                     @Nullable
                                     java.lang.String ns,
                                     @Nullable
                                     java.lang.String localName)

Shortcut for checking a DOM element node's namespace and local name.

Parameters:

e - An element to compare against

ns - An XML namespace to compare

localName - A local name to compare

Returns:

true iff the element's local name and namespace match the parameters

setDocumentElement

public static void setDocumentElement(@Nonnull
                                      org.w3c.dom.Document document,
                                      @Nonnull
                                      org.w3c.dom.Element element)

Sets a given Element as the root element of a given document. If the given element is not owned by the given document than it is adopted first.

Parameters:

document - document whose root element will be set

element - element that will be the new root element