org.opensaml.xml.util
Class XMLHelper

java.lang.Object
  extended by org.opensaml.xml.util.XMLHelper

public final class XMLHelper
extends java.lang.Object

A helper class for working with W3C DOM objects.


Method Summary
static void adoptElement(org.w3c.dom.Element adoptee, org.w3c.dom.Document adopter)
          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 appendNamespaceDeclaration(org.w3c.dom.Element domElement, java.lang.String namespaceURI, java.lang.String prefix)
          Adds a namespace declaration (xmlns:) attribute to the given element.
static void appendTextContent(org.w3c.dom.Element domElement, 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.Attr constructAttribute(org.w3c.dom.Document owningDocument, javax.xml.namespace.QName attributeName)
          Constructs an attribute owned by the given document with the given name.
static org.w3c.dom.Attr constructAttribute(org.w3c.dom.Document document, java.lang.String namespaceURI, java.lang.String localName, java.lang.String prefix)
          Constructs an attribute owned by the given document with the given name.
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 javax.xml.namespace.QName constructQName(java.lang.String qname, org.w3c.dom.Element owningElement)
          Constructs a QName from a string (attribute element content) value.
static javax.xml.namespace.QName constructQName(java.lang.String namespaceURI, java.lang.String localName, java.lang.String prefix)
          Constructs a QName.
static javax.xml.namespace.QName constructQName(java.lang.String qname, XMLObject owningObject)
          Constructs a QName from a string (attribute or element content) value.
static long durationToLong(java.lang.String duration)
          Converts a lexical duration, as defined by XML Schema 1.0, into milliseconds.
static java.lang.Boolean getAttributeValueAsBoolean(org.w3c.dom.Attr attribute)
          Parses the attribute's value.
static java.util.List<java.lang.String> getAttributeValueAsList(org.w3c.dom.Attr attribute)
          Gets the value of a list-type attribute as a list.
static javax.xml.namespace.QName getAttributeValueAsQName(org.w3c.dom.Attr attribute)
          Constructs a QName from an attributes value.
static java.util.Map<javax.xml.namespace.QName,java.util.List<org.w3c.dom.Element>> getChildElements(org.w3c.dom.Element root)
          Gets the child elements of the given element in a single iteration.
static java.util.List<org.w3c.dom.Element> getChildElementsByTagName(org.w3c.dom.Element 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.Element root, java.lang.String namespaceURI, java.lang.String localName)
          Gets the child nodes with the given namespace qualified tag name.
static javax.xml.datatype.DatatypeFactory getDataTypeFactory()
          Gets a static instance of a JAXP DatatypeFactory.
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 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.Attr getIdAttribute(org.w3c.dom.Element domElement)
          Gets the ID attribute of a DOM element.
static java.util.Locale getLanguage(org.w3c.dom.Element element)
          Gets the lcoale currently active for the element.
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 javax.xml.namespace.QName getNodeQName(org.w3c.dom.Node domNode)
          Gets the QName for the given DOM node.
static javax.xml.namespace.QName getXSIType(org.w3c.dom.Element e)
          Gets the XSI type for a given element if it has one.
static boolean hasXSIType(org.w3c.dom.Element e)
          Checks if the given element has an xsi:type defined for it.
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 java.lang.String longToDuration(long duration)
          Converts a duration in milliseconds to a lexical duration, as defined by XML Schema 1.0.
static java.lang.String lookupNamespaceURI(org.w3c.dom.Element startingElement, org.w3c.dom.Element stopingElement, java.lang.String prefix)
          Looks up the namespace URI associated with the given prefix starting at the given element.
static java.lang.String lookupNamespaceURI(org.w3c.dom.Element startingElement, java.lang.String prefix)
          Looks up the namespace URI associated with the given prefix starting at the given element.
static java.lang.String lookupPrefix(org.w3c.dom.Element startingElement, org.w3c.dom.Element stopingElement, java.lang.String namespaceURI)
          Looks up the namespace prefix associated with the given URI starting at the given element.
static java.lang.String lookupPrefix(org.w3c.dom.Element startingElement, java.lang.String namespaceURI)
          Looks up the namespace prefix associated with the given URI starting at the given element.
static java.lang.String nodeToString(org.w3c.dom.Node node)
          Converts a Node into a String using the DOM, level 3, Load/Save serializer.
static java.lang.String prettyPrintXML(org.w3c.dom.Node node)
          Pretty prints the XML node.
static java.lang.String qnameToContentString(javax.xml.namespace.QName qname)
          Converts a QName into a string that can be used for attribute values or element content.
static void rootNamespaces(org.w3c.dom.Element domElement)
          Ensures that all the visibly used namespaces referenced by the given Element or its descendants are declared by the given Element or one of its descendants.
static void writeNode(org.w3c.dom.Node node, java.io.Writer output)
          Writes a Node out to a Writer using the DOM, level 3, Load/Save serializer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getDataTypeFactory

public static javax.xml.datatype.DatatypeFactory getDataTypeFactory()
Gets a static instance of a JAXP DatatypeFactory.

Returns:
the factory or null if the factory could not be created

hasXSIType

public static boolean hasXSIType(org.w3c.dom.Element e)
Checks if the given element has an xsi:type defined for it.

Parameters:
e - the DOM element
Returns:
true if there is a type, false if not

getXSIType

public static javax.xml.namespace.QName getXSIType(org.w3c.dom.Element e)
Gets the XSI type for a given element if it has one.

Parameters:
e - the element
Returns:
the type or null

getIdAttribute

public static org.w3c.dom.Attr getIdAttribute(org.w3c.dom.Element domElement)
Gets the ID attribute of a DOM element.

Parameters:
domElement - the DOM element
Returns:
the ID attribute or null if there isn't one

getNodeQName

public static javax.xml.namespace.QName getNodeQName(org.w3c.dom.Node domNode)
Gets the QName for the given DOM node.

Parameters:
domNode - the DOM node
Returns:
the QName for the element or null if the element was null

getLanguage

public static java.util.Locale getLanguage(org.w3c.dom.Element element)
Gets the lcoale currently active for the element. This is done by looking for an xml:lang attribute and parsing its content. If no xml:lang attribute is present the default locale is returned. This method only uses the language primary tag, as defined by RFC3066.

Parameters:
element - element to retrieve local information for
Returns:
the active local of the element

constructAttribute

public static org.w3c.dom.Attr constructAttribute(org.w3c.dom.Document owningDocument,
                                                  javax.xml.namespace.QName attributeName)
Constructs an attribute owned by the given document with the given name.

Parameters:
owningDocument - the owning document
attributeName - the name of that attribute
Returns:
the constructed attribute

constructAttribute

public static org.w3c.dom.Attr constructAttribute(org.w3c.dom.Document document,
                                                  java.lang.String namespaceURI,
                                                  java.lang.String localName,
                                                  java.lang.String prefix)
Constructs an attribute owned by the given document with the given name.

Parameters:
document - the owning document
namespaceURI - the URI for the namespace the attribute is in
localName - the local name
prefix - the prefix of the namespace that attribute is in
Returns:
the constructed attribute

getAttributeValueAsQName

public static javax.xml.namespace.QName getAttributeValueAsQName(org.w3c.dom.Attr attribute)
Constructs a QName from an attributes value.

Parameters:
attribute - the attribute with a QName value
Returns:
a QName from an attributes value, or null if the given attribute is null

getAttributeValueAsBoolean

public static java.lang.Boolean getAttributeValueAsBoolean(org.w3c.dom.Attr attribute)
Parses the attribute's value. If the value is 0 or "false" then false is returned, if the value is 1 or "true" then true is returned, if the value is anything else then null returned.

Parameters:
attribute - attribute whose value will be converted to a boolean
Returns:
boolean value of the attribute or null

getAttributeValueAsList

public static java.util.List<java.lang.String> getAttributeValueAsList(org.w3c.dom.Attr attribute)
Gets the value of a list-type attribute as a list.

Parameters:
attribute - attribute whose value will be turned into a list
Returns:
list of values, never null

getElementContentAsQName

public static javax.xml.namespace.QName getElementContentAsQName(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

getElementContentAsList

public static java.util.List<java.lang.String> getElementContentAsList(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

constructQName

public static javax.xml.namespace.QName constructQName(java.lang.String namespaceURI,
                                                       java.lang.String localName,
                                                       java.lang.String prefix)
Constructs a QName.

Parameters:
namespaceURI - the namespace of the QName
localName - the local name of the QName
prefix - the prefix of the QName, may be null
Returns:
the QName

constructQName

public static javax.xml.namespace.QName constructQName(java.lang.String qname,
                                                       XMLObject owningObject)
Constructs a QName from a string (attribute or element content) value.

Parameters:
qname - the QName string
owningObject - XMLObject, with cached DOM, owning the QName
Returns:
the QName respresented by the string

constructQName

public static javax.xml.namespace.QName constructQName(java.lang.String qname,
                                                       org.w3c.dom.Element owningElement)
Constructs a QName from a string (attribute element content) value.

Parameters:
qname - the QName string
owningElement - parent DOM element of the Node which contains the QName value
Returns:
the QName respresented by the string

constructElement

public 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.

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(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.

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

appendChildElement

public 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.

Parameters:
parentElement - the parent Element
childElement - the child Element

adoptElement

public static void adoptElement(org.w3c.dom.Element adoptee,
                                org.w3c.dom.Document adopter)
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

appendTextContent

public static void appendTextContent(org.w3c.dom.Element domElement,
                                     java.lang.String textContent)
Creates a text node with the given content and appends it as child to the given element.

Parameters:
domElement - the element to recieve the text node
textContent - the content for the text node

appendNamespaceDeclaration

public static void appendNamespaceDeclaration(org.w3c.dom.Element domElement,
                                              java.lang.String namespaceURI,
                                              java.lang.String prefix)
Adds a namespace declaration (xmlns:) attribute to the given element.

Parameters:
domElement - the element to add the attribute to
namespaceURI - the URI of the namespace
prefix - the prefix for the namespace

lookupNamespaceURI

public static java.lang.String lookupNamespaceURI(org.w3c.dom.Element startingElement,
                                                  java.lang.String prefix)
Looks up the namespace URI associated with the given prefix starting at the given element. This method differs from the Node.lookupNamespaceURI(java.lang.String) in that it only those namespaces declared by an xmlns attribute are inspected. The Node method also checks the namespace a particular node was created in by way of a call like Document.createElementNS(java.lang.String, java.lang.String) even if the resulting element doesn't have an namespace delcaration attribute.

Parameters:
startingElement - the starting element
prefix - the prefix to look up
Returns:
the namespace URI for the given prefix

lookupNamespaceURI

public static java.lang.String lookupNamespaceURI(org.w3c.dom.Element startingElement,
                                                  org.w3c.dom.Element stopingElement,
                                                  java.lang.String prefix)
Looks up the namespace URI associated with the given prefix starting at the given element. This method differs from the Node.lookupNamespaceURI(java.lang.String) in that it only those namespaces declared by an xmlns attribute are inspected. The Node method also checks the namespace a particular node was created in by way of a call like Document.createElementNS(java.lang.String, java.lang.String) even if the resulting element doesn't have an namespace delcaration attribute.

Parameters:
startingElement - the starting element
stopingElement - the ancestor of the starting element that serves as the upper-bound for the search
prefix - the prefix to look up
Returns:
the namespace URI for the given prefer or null

lookupPrefix

public static java.lang.String lookupPrefix(org.w3c.dom.Element startingElement,
                                            java.lang.String namespaceURI)
Looks up the namespace prefix associated with the given URI starting at the given element. This method differs from the Node.lookupPrefix(java.lang.String) in that it only those namespaces declared by an xmlns attribute are inspected. The Node method also checks the namespace a particular node was created in by way of a call like Document.createElementNS(java.lang.String, java.lang.String) even if the resulting element doesn't have an namespace delcaration attribute.

Parameters:
startingElement - the starting element
namespaceURI - the uri to look up
Returns:
the prefix for the given namespace URI

lookupPrefix

public static java.lang.String lookupPrefix(org.w3c.dom.Element startingElement,
                                            org.w3c.dom.Element stopingElement,
                                            java.lang.String namespaceURI)
Looks up the namespace prefix associated with the given URI starting at the given element. This method differs from the Node.lookupPrefix(java.lang.String) in that it only those namespaces declared by an xmlns attribute are inspected. The Node method also checks the namespace a particular node was created in by way of a call like Document.createElementNS(java.lang.String, java.lang.String) even if the resulting element doesn't have an namespace delcaration attribute.

Parameters:
startingElement - the starting element
stopingElement - the ancestor of the starting element that serves as the upper-bound for the search
namespaceURI - the uri to look up
Returns:
the prefix for the given namespace URI

getChildElementsByTagNameNS

public static java.util.List<org.w3c.dom.Element> getChildElementsByTagNameNS(org.w3c.dom.Element root,
                                                                              java.lang.String namespaceURI,
                                                                              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(Element).

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

getChildElementsByTagName

public static java.util.List<org.w3c.dom.Element> getChildElementsByTagName(org.w3c.dom.Element root,
                                                                            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(Element).

Parameters:
root - element to retrieve the children from
localName - local, tag, name of the child element
Returns:
list of child elements, never null

getChildElements

public static java.util.Map<javax.xml.namespace.QName,java.util.List<org.w3c.dom.Element>> getChildElements(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 qualifed tag name, never null

getElementAncestor

public static org.w3c.dom.Element getElementAncestor(org.w3c.dom.Node currentNode)
Gets the ancestor element node to the given node.

Parameters:
currentNode - the node to retrive the ancestor for
Returns:
the ancestral element node of the current node, or null

nodeToString

public static java.lang.String nodeToString(org.w3c.dom.Node node)
Converts a Node into a String using the DOM, level 3, Load/Save serializer.

Parameters:
node - the node to be written to a string
Returns:
the string representation of the node

prettyPrintXML

public static java.lang.String prettyPrintXML(org.w3c.dom.Node node)
Pretty prints the XML node.

Parameters:
node - xml node to print
Returns:
pretty-printed xml

writeNode

public static void writeNode(org.w3c.dom.Node node,
                             java.io.Writer output)
Writes a Node out to a Writer using the DOM, level 3, Load/Save serializer. The writen content is encoded using the encoding specified in the writer configuration.

Parameters:
node - the node to write out
output - the writer to write the XML to

qnameToContentString

public static java.lang.String qnameToContentString(javax.xml.namespace.QName qname)
Converts a QName into a string that can be used for attribute values or element content.

Parameters:
qname - the QName to convert to a string
Returns:
the string value of the QName

rootNamespaces

public static void rootNamespaces(org.w3c.dom.Element domElement)
                           throws XMLParserException
Ensures that all the visibly used namespaces referenced by the given Element or its descendants are declared by the given Element or one of its descendants. NOTE: This is a very costly operation.

Parameters:
domElement - the element to act as the root of the namespace declarations
Throws:
XMLParserException - thrown if a namespace prefix is encountered that can't be resolved to a namespace URI

isElementNamed

public 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.

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

getFirstChildElement

public 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.

Parameters:
n - The parent in which to search for children
Returns:
The first child Element of n, or null if none

getNextSiblingElement

public 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.

Parameters:
n - The sibling to start with
Returns:
The next sibling Element of n, or null if none

durationToLong

public static long durationToLong(java.lang.String duration)
Converts a lexical duration, as defined by XML Schema 1.0, into milliseconds.

Parameters:
duration - lexical duration representation
Returns:
duration in milliseconds

longToDuration

public static java.lang.String longToDuration(long duration)
Converts a duration in milliseconds to a lexical duration, as defined by XML Schema 1.0.

Parameters:
duration - the duration
Returns:
the lexical representation


Copyright © 2006-2011 Internet2. All Rights Reserved.