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

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

public final class ElementSupport
extends Object

Set of helper methods for working with DOM Elements.

Constructor Summary

private

ElementSupport() Constructor.

Method Summary

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

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

Parameters:

element - the element to recieve the text node

textContent - the content for the text node

constructElement

public static Element constructElement(@Nonnull
                                       Document document,
                                       @Nonnull
                                       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 Element constructElement(@Nonnull
                                       Document document,
                                       @Nullable
                                       String namespaceURI,
                                       @Nonnull
                                       String localName,
                                       @Nullable
                                       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 List<Element> getChildElements(@Nullable
                                                     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 List<Element> getChildElements(@Nullable
                                                     Node root,
                                                     @Nullable
                                                     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

getChildElementsByTagName

@Nonnull
public static List<Element> getChildElementsByTagName(@Nullable
                                                              Node root,
                                                              @Nullable
                                                              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 List<Element> getChildElementsByTagNameNS(@Nullable
                                                                Node root,
                                                                @Nullable
                                                                String namespaceURI,
                                                                @Nullable
                                                                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 Element getElementAncestor(@Nullable
                                                  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 String getElementContentAsString(@Nullable
                                                       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 List<String> getElementContentAsList(@Nullable
                                                           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 QName getElementContentAsQName(@Nullable
                                                      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 Element getFirstChildElement(@Nullable
                                                    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 Map<QName,List<Element>> getIndexedChildElements(@Nullable
                                                                       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 qualifed tag name, never null

getNextSiblingElement

@Nullable
public static Element getNextSiblingElement(@Nullable
                                                     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
                                     Element e,
                                     @Nullable
                                     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
                                     Element e,
                                     @Nullable
                                     String ns,
                                     @Nullable
                                     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
                                      Document document,
                                      @Nonnull
                                      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