Package 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 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, @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 receive 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

    • getFirstChildElement

      @Nullable public static Element getFirstChildElement​(@Nullable Node root, @Nullable 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 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 qualified 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