Package net.shibboleth.shared.xml

# Class ElementSupport

java.lang.Object
net.shibboleth.shared.xml.ElementSupport

public final class ElementSupport extends Object
Set of helper methods for working with DOM Elements.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`private`
`ElementSupport()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`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, String namespaceURI, String localName, String prefix)`
Constructs an element, rooted in the given document, with the given information.
`static Element`
`constructElement(Document document, QName elementName)`
Constructs an element, rooted in the given document, with the given name.
`static Element`
`ensureDocumentElement(Document doc)`
Return `Document.getDocumentElement()`, raising an `IllegalStateException` if null.
`static Document`
`ensureOwnerDocument(Element e)`
Return `Node.getOwnerDocument()`, raising an `IllegalStateException` if null.
`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 Element`
`getFirstChildElement(Node root, QName name)`
Returns the first child element of the supplied element with the supplied name if it exists.
`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, String ns, String localName)`
Shortcut for checking a DOM element node's namespace and local name.
`static boolean`
`isElementNamed(Element e, QName name)`
Check if the given Element has the given 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 Details

### ElementSupport

private ElementSupport()
Constructor.

## Method Details

### 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, @Nonnull 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 receive the text node
  `textContent` - the content for the text node

### constructElement

@Nonnull 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

@Nonnull 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 @Unmodifiable @NotLive public static List<Element> getChildElements(@Nonnull 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 @Unmodifiable @NotLive public static List<Element> getChildElements(@Nonnull Node root, @Nonnull 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 Element getFirstChildElement(@Nonnull Node root, @Nonnull 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 @Unmodifiable @NotLive public static List<Element> getChildElementsByTagName(@Nonnull Node root, @Nonnull 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 @Unmodifiable @NotLive public static List<Element> getChildElementsByTagNameNS(@Nonnull Node root, @Nullable String namespaceURI, @Nonnull 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(@Nonnull 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(@Nonnull 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(@Nonnull 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(@Nonnull 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(@Nonnull 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 @Unmodifiable @NotLive public static Map<QName,List<Element>> getIndexedChildElements(@Nonnull 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 Element getNextSiblingElement(@Nonnull 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(@Nonnull Element e, @Nonnull 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(@Nonnull Element e, @Nullable String ns, @Nonnull 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

### ensureOwnerDocument

@Nonnull public static Document ensureOwnerDocument(@Nonnull Element e)
Return `Node.getOwnerDocument()`, raising an `IllegalStateException` if null.

Parameters:
  `e` - input Element
Returns:
  the owner Document
Since:
  9.0.0

### ensureDocumentElement

@Nonnull public static Element ensureDocumentElement(@Nonnull Document doc)
Return `Document.getDocumentElement()`, raising an `IllegalStateException` if null.

Parameters:
  `doc` - input Document
Returns:
  the document Element
Since:
  9.0.0