org.opensaml.xml.util
Class XMLHelper

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

public final class XMLHelper
extends Object

A helper class for working with W3C DOM objects.

Field Summary

private static DatatypeFactory	dataTypeFactory JAXP DatatypeFactory.
static String	LIST_DELIMITERS A string which contains the valid delimiters for the XML Schema 'list' type.
private static Map<String,Object>	prettyPrintParams DOM configuration parameters used by LSSerializer in pretty print format output.

Constructor Summary

private

XMLHelper() Constructor.

Method Summary

static void	adoptElement(Element adoptee, Document adopter) 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	appendNamespaceDeclaration(Element domElement, String namespaceURI, String prefix) Adds a namespace declaration (xmlns:) attribute to the given element.
static void	appendTextContent(Element domElement, String textContent) Creates a text node with the given content and appends it as child to the given element.
static Attr	constructAttribute(Document owningDocument, QName attributeName) Constructs an attribute owned by the given document with the given name.
static Attr	constructAttribute(Document document, String namespaceURI, String localName, String prefix) Constructs an attribute owned by the given document with the given name.
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 QName	constructQName(String qname, Element owningElement) Constructs a QName from a string (attribute element content) value.
static QName	constructQName(String namespaceURI, String localName, String prefix) Constructs a QName.
static QName	constructQName(String qname, XMLObject owningObject) Constructs a QName from a string (attribute or element content) value.
static long	durationToLong(String duration) Converts a lexical duration, as defined by XML Schema 1.0, into milliseconds.
static Boolean	getAttributeValueAsBoolean(Attr attribute) Parses the attribute's value.
static List<String>	getAttributeValueAsList(Attr attribute) Gets the value of a list-type attribute as a list.
static QName	getAttributeValueAsQName(Attr attribute) Constructs a QName from an attributes value.
static Map<QName,List<Element>>	getChildElements(Element root) Gets the child elements of the given element in a single iteration.
static List<Element>	getChildElementsByTagName(Element root, String localName) Gets the child nodes with the given local tag name.
static List<Element>	getChildElementsByTagNameNS(Element root, String namespaceURI, String localName) Gets the child nodes with the given namespace qualified tag name.
static DatatypeFactory	getDataTypeFactory() Gets a static instance of a JAXP DatatypeFactory.
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 Element	getFirstChildElement(Node n) Gets the first child Element of the node, skipping any Text nodes such as whitespace.
static Attr	getIdAttribute(Element domElement) Gets the ID attribute of a DOM element.
static Locale	getLanguage(Element element) Gets the lcoale currently active for the element.
static DOMImplementationLS	getLSDOMImpl(Node node) Get the DOM Level 3 Load/Save DOMImplementationLS for the given node.
static LSSerializer	getLSSerializer(DOMImplementationLS domImplLS, Map<String,Object> serializerParams) Obtain a the DOM, level 3, Load/Save serializer LSSerializer instance from the given DOMImplementationLS instance.
static Element	getNextSiblingElement(Node n) Gets the next sibling Element of the node, skipping any Text nodes such as whitespace.
static QName	getNodeQName(Node domNode) Gets the QName for the given DOM node.
private static Map<String,Object>	getPrettyPrintParams() Create the parameters set used in pretty print formatting of an LSSerializer.
static QName	getXSIType(Element e) Gets the XSI type for a given element if it has one.
static boolean	hasXSIType(Element e) Checks if the given element has an xsi:type defined for it.
static boolean	isElementNamed(Element e, String ns, String localName) Shortcut for checking a DOM element node's namespace and local name.
static String	longToDuration(long duration) Converts a duration in milliseconds to a lexical duration, as defined by XML Schema 1.0.
static String	lookupNamespaceURI(Element startingElement, Element stopingElement, String prefix) Looks up the namespace URI associated with the given prefix starting at the given element.
static String	lookupNamespaceURI(Element startingElement, String prefix) Looks up the namespace URI associated with the given prefix starting at the given element.
static String	lookupPrefix(Element startingElement, Element stopingElement, String namespaceURI) Looks up the namespace prefix associated with the given URI starting at the given element.
static String	lookupPrefix(Element startingElement, String namespaceURI) Looks up the namespace prefix associated with the given URI starting at the given element.
static void	marshallAttribute(QName attributeName, List<String> attributeValues, Element domElement, boolean isIDAttribute) Marshall an attribute name and value to a DOM Element.
static void	marshallAttribute(QName attributeName, String attributeValue, Element domElement, boolean isIDAttribute) Marshall an attribute name and value to a DOM Element.
static void	marshallAttributeMap(AttributeMap attributeMap, Element domElement) Marshall the attributes represented by the indicated AttributeMap into the indicated DOM Element.
static String	nodeToString(Node node) Converts a Node into a String using the DOM, level 3, Load/Save serializer.
static String	prettyPrintXML(Node node) Pretty prints the XML node.
static String	qnameToContentString(QName qname) Converts a QName into a string that can be used for attribute values or element content.
static void	rootNamespaces(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.
private static void	rootNamespaces(Element domElement, Element upperNamespaceSearchBound) Recursively called function that ensures all the visibly used namespaces referenced by the given Element or its descendants are declared if they don't appear in the list of already resolved namespaces.
static void	unmarshallToAttributeMap(AttributeMap attributeMap, Attr attribute) Unmarshall a DOM Attr to an AttributeMap.
static void	writeNode(Node node, OutputStream output) Writes a Node out to an OutputStream using the DOM, level 3, Load/Save serializer.
static void	writeNode(Node node, OutputStream output, Map<String,Object> serializerParams) Writes a Node out to an OutputStream using the DOM, level 3, Load/Save serializer.
static void	writeNode(Node node, Writer output) Writes a Node out to a Writer using the DOM, level 3, Load/Save serializer.
static void	writeNode(Node node, Writer output, Map<String,Object> serializerParams) 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

Field Detail

LIST_DELIMITERS

public static final String LIST_DELIMITERS

A string which contains the valid delimiters for the XML Schema 'list' type. These are: space, newline, carriage return, and tab.

See Also:

Constant Field Values

prettyPrintParams

private static Map<String,Object> prettyPrintParams

DOM configuration parameters used by LSSerializer in pretty print format output.

dataTypeFactory

private static DatatypeFactory dataTypeFactory

JAXP DatatypeFactory.

Constructor Detail

XMLHelper

private XMLHelper()

Constructor.

Method Detail

getDataTypeFactory

public static 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(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 QName getXSIType(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 Attr getIdAttribute(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 QName getNodeQName(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 Locale getLanguage(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 Attr constructAttribute(Document owningDocument,
                                      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 Attr constructAttribute(Document document,
                                      String namespaceURI,
                                      String localName,
                                      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 QName getAttributeValueAsQName(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 Boolean getAttributeValueAsBoolean(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 List<String> getAttributeValueAsList(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

marshallAttribute

public static void marshallAttribute(QName attributeName,
                                     String attributeValue,
                                     Element domElement,
                                     boolean isIDAttribute)

Marshall an attribute name and value to a DOM Element. This is particularly useful for attributes whose names appear in namespace-qualified form.

Parameters:

attributeName - the attribute name in QName form

attributeValue - the attribute value

domElement - the target element to which to marshall

isIDAttribute - flag indicating whether the attribute being marshalled should be handled as an ID-typed attribute

marshallAttribute

public static void marshallAttribute(QName attributeName,
                                     List<String> attributeValues,
                                     Element domElement,
                                     boolean isIDAttribute)

Marshall an attribute name and value to a DOM Element. This is particularly useful for attributes whose names appear in namespace-qualified form.

Parameters:

attributeName - the attribute name in QName form

attributeValues - the attribute values

domElement - the target element to which to marshall

isIDAttribute - flag indicating whether the attribute being marshalled should be handled as an ID-typed attribute

marshallAttributeMap

public static void marshallAttributeMap(AttributeMap attributeMap,
                                        Element domElement)

Marshall the attributes represented by the indicated AttributeMap into the indicated DOM Element.

Parameters:

attributeMap - the AttributeMap

domElement - the target Element

unmarshallToAttributeMap

public static void unmarshallToAttributeMap(AttributeMap attributeMap,
                                            Attr attribute)

Unmarshall a DOM Attr to an AttributeMap.

Parameters:

attributeMap - the target AttributeMap

attribute - the target DOM Attr

getElementContentAsQName

public static QName getElementContentAsQName(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 List<String> getElementContentAsList(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 QName constructQName(String namespaceURI,
                                   String localName,
                                   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 QName constructQName(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 QName constructQName(String qname,
                                   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 Element constructElement(Document document,
                                       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(Document document,
                                       String namespaceURI,
                                       String localName,
                                       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(Element parentElement,
                                      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(Element adoptee,
                                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(Element domElement,
                                     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(Element domElement,
                                              String namespaceURI,
                                              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 String lookupNamespaceURI(Element startingElement,
                                        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 String lookupNamespaceURI(Element startingElement,
                                        Element stopingElement,
                                        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, inclusive, for the search

prefix - the prefix to look up

Returns:

the namespace URI for the given prefer or null

lookupPrefix

public static String lookupPrefix(Element startingElement,
                                  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 String lookupPrefix(Element startingElement,
                                  Element stopingElement,
                                  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, inclusive, for the search

namespaceURI - the uri to look up

Returns:

the prefix for the given namespace URI

getChildElementsByTagNameNS

public static List<Element> getChildElementsByTagNameNS(Element root,
                                                        String namespaceURI,
                                                        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 List<Element> getChildElementsByTagName(Element root,
                                                      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 Map<QName,List<Element>> getChildElements(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 Element getElementAncestor(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 String nodeToString(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 String prettyPrintXML(Node node)

Pretty prints the XML node.

Parameters:

node - xml node to print

Returns:

pretty-printed xml

getPrettyPrintParams

private static Map<String,Object> getPrettyPrintParams()

Create the parameters set used in pretty print formatting of an LSSerializer.

Returns:

the params map

writeNode

public static void writeNode(Node node,
                             Writer output)

Writes a Node out to a Writer using the DOM, level 3, Load/Save serializer. The written 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

writeNode

public static void writeNode(Node node,
                             Writer output,
                             Map<String,Object> serializerParams)

Writes a Node out to a Writer using the DOM, level 3, Load/Save serializer. The written 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

serializerParams - parameters to pass to the DOMConfiguration of the serializer instance, obtained via LSSerializer.getDomConfig(). May be null.

writeNode

public static void writeNode(Node node,
                             OutputStream output)

Writes a Node out to an OutputStream using the DOM, level 3, Load/Save serializer. The written content is encoded using the encoding specified in the output stream configuration.

Parameters:

node - the node to write out

output - the output stream to write the XML to

writeNode

public static void writeNode(Node node,
                             OutputStream output,
                             Map<String,Object> serializerParams)

Writes a Node out to an OutputStream using the DOM, level 3, Load/Save serializer. The written content is encoded using the encoding specified in the output stream configuration.

Parameters:

node - the node to write out

output - the output stream to write the XML to

serializerParams - parameters to pass to the DOMConfiguration of the serializer instance, obtained via LSSerializer.getDomConfig(). May be null.

getLSSerializer

public static LSSerializer getLSSerializer(DOMImplementationLS domImplLS,
                                           Map<String,Object> serializerParams)

Obtain a the DOM, level 3, Load/Save serializer LSSerializer instance from the given DOMImplementationLS instance.

The serializer instance will be configured with the parameters passed as the serializerParams argument. It will also be configured with an LSSerializerFilter that shows all nodes to the filter, and accepts all nodes shown.

Parameters:

domImplLS - the DOM Level 3 Load/Save implementation to use

serializerParams - parameters to pass to the DOMConfiguration of the serializer instance, obtained via LSSerializer.getDomConfig(). May be null.

Returns:

a new LSSerializer instance

getLSDOMImpl

public static DOMImplementationLS getLSDOMImpl(Node node)

Get the DOM Level 3 Load/Save DOMImplementationLS for the given node.

Parameters:

node - the node to evaluate

Returns:

the DOMImplementationLS for the given node

qnameToContentString

public static String qnameToContentString(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(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

rootNamespaces

private static void rootNamespaces(Element domElement,
                                   Element upperNamespaceSearchBound)
                            throws XMLParserException

Recursively called function that ensures all the visibly used namespaces referenced by the given Element or its descendants are declared if they don't appear in the list of already resolved namespaces.

Parameters:

domElement - the Element

upperNamespaceSearchBound - the "root" element of the fragment where namespaces may be rooted

Throws:

XMLParserException - thrown if a namespace prefix is encountered that can't be resolved to a namespace URI

isElementNamed

public static boolean isElementNamed(Element e,
                                     String ns,
                                     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 Element getFirstChildElement(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 Element getNextSiblingElement(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(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 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