com.pega.pegarules.pub.util

Class XMLUtils

java.lang.Object

com.pega.pegarules.pub.util.XMLUtils

public class XMLUtils
extends java.lang.Object

Utilities for dealing with XML NOTE: XMLEncode is available in JDK 1.4 (java.beans.XMLEncoder)

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COPYRIGHT
static java.lang.String	VERSION

Constructor Summary

Constructors

Constructor and Description
XMLUtils()

Method Summary

Modifier and Type	Method and Description
static void	collectElements(java.lang.StringBuilder aXMLBuffer, java.lang.String aTypeRegex, boolean aIsPrefix, boolean aIgnoreCase, boolean aRemove, java.util.Collection aCollection) Collects (as Strings) all elements from the XML String that have types matching the regex in the first argument.
static java.lang.StringBuffer	encode(java.lang.String string) Deprecated.
static java.lang.StringBuffer	encode(java.lang.StringBuffer in) Encode the xml special characters "<",">","'",""","&".
static java.lang.StringBuilder	encode(java.lang.StringBuilder in) Encode the xml special characters "<",">","'",""","&".
static java.lang.String	encodeString(java.lang.String in) Encode the xml special characters "<",">","'",""","&".
static org.w3c.dom.Node	findNode(org.w3c.dom.Element aElement, java.lang.String aNodeType, java.util.Map<java.lang.String,java.lang.String> aAttributeMap) Finds the "first" node in the children of an Element that matches the input criteria.
static org.w3c.dom.Node	findNode(org.w3c.dom.Element aElement, java.lang.String aNodeType, java.lang.String aAttrKey, java.lang.String aAttrValue) Finds the "first" node in the children of an Element that matches the input criteria.
static java.util.List	getAllAttributes(org.w3c.dom.Element aNode) Return all attributes of the given element node.
static java.util.List	getAllChildElements(org.w3c.dom.Element aNode) Return all child elements of the given element node.
static java.util.Map<java.lang.String,java.lang.String>	getAttributesFromTag(java.lang.String aTag) Obtains a mapping of attribute keys and values from an XML or HTML tag
static java.util.Map<java.lang.String,java.lang.String>	getAttributesFromTag(java.lang.String aTag, boolean isHTML) Obtains a mapping of attribute keys and values from an XML or HTML tag
static java.lang.String	getAttributeValue(org.w3c.dom.Element aNode, java.lang.String aAttrName) Return the string value of the named attribute.
static java.lang.String	getAttributeValue(org.w3c.dom.Element aNode, java.lang.String aNamespaceURI, java.lang.String aLocalName) Return the string value of the fully-qualified attribute.
static org.w3c.dom.Element	getChildElement(org.w3c.dom.Element aParent, java.lang.String aName) Perform a depth-first traversal of the parent element, and return the first child element with a matching tag name.
static java.lang.String	getElementNodeValue(org.w3c.dom.Element aNode) Return a concatenated string of the text node children of the given element node.
static org.w3c.dom.Element	getFirstChildElement(org.w3c.dom.Element aNode) Return the first child element node of the given element node.
static org.w3c.dom.Element	getNamedChildElement(org.w3c.dom.Element aNode, java.lang.String aElemName) Return the first child element node with a matching unqualified name.
static org.w3c.dom.Element	getNamedChildElement(org.w3c.dom.Element aNode, java.lang.String aNamespaceURI, java.lang.String aLocalName) Return the first child element node with a matching qualified name.
static java.util.List	getNamedChildElements(org.w3c.dom.Element aNode, java.lang.String aElemName) Return all child element nodes with a matching unqualified name.
static java.util.List	getNamedChildElements(org.w3c.dom.Element aNode, java.lang.String aNamespaceURI, java.lang.String aLocalName) Return all child element nodes with a matching qualified name.
static org.w3c.dom.Element	getNamedSiblingElement(org.w3c.dom.Element aNode, java.lang.String aElemName) Return the first sibling element node with a matching unqualified name.
static org.w3c.dom.Element	getNamedSiblingElement(org.w3c.dom.Element aNode, java.lang.String aNamespaceURI, java.lang.String aLocalName) Return the first sibling element node with a matching qualified name.
static org.w3c.dom.Element	getNextSiblingElement(org.w3c.dom.Element aNode) Return the immediate sibling element node of the given element node.
static javax.xml.namespace.QName	getTypeQName(org.w3c.dom.Element aNode) Return the resolved qualified name of the type referred to by the 'xsi:type' attribute of the given element node.
static boolean	isNil(org.w3c.dom.Element aNode) Return the boolean value of the named attribute.
static java.lang.String	makeCloseTag(java.lang.String aType) Makes a closing XML tag String based on the input.
static java.lang.String	makeTag(java.lang.String aType, java.util.Map<java.lang.String,java.lang.String> aAttrMap, boolean aSelfClosing) Makes an XML tag String based on the input.
static void	removeElements(java.lang.StringBuilder aXMLBuffer, java.lang.String aTypeRegex, boolean aIsPrefix, boolean aIgnoreCase) Removes all elements from the XML String that have types matching the regex in the first argument.
static void	removeElementsByNSPrefix(java.lang.StringBuilder aXMLBuffer, java.lang.String aNsPrefix, boolean aIgnoreCase) Removes all elements from the XML string that have a namespace prefix matching the regex in the first argument.
static java.lang.String	resolveNamespaceURI(org.w3c.dom.Element aNode, java.lang.String aPrefix) Return the namespace URI associated with the given prefix.
static java.lang.String	resolveNSPrefix(org.w3c.dom.Element aNode, java.lang.String aNamespaceURI) Return the prefix associated with the given namespace URI.
static javax.xml.namespace.QName	resolveQNameRef(org.w3c.dom.Element aNode, java.lang.String aRefVal) Return the resolved qualified name of the specified value, which may contain a prefix that refers to a namespace mapping in one of the node's ancestors.
static void	simpleAddElement(java.lang.StringBuffer xml, java.lang.String tag, long data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleAddElement(java.lang.StringBuffer xml, java.lang.String tag, java.lang.String data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleAddElement(java.lang.StringBuffer xml, java.lang.String tag, java.lang.StringBuffer data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleAddElement(java.lang.StringBuilder xml, java.lang.String tag, long data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleAddElement(java.lang.StringBuilder xml, java.lang.String tag, java.lang.String data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleAddElement(java.lang.StringBuilder xml, java.lang.String tag, java.lang.StringBuilder data) Given a stringbuilder of xml data, append a new tag named tag data of data.
static void	simpleEmbedElements(java.lang.StringBuffer xml, java.lang.String tag, java.lang.String data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleEmbedElements(java.lang.StringBuffer xml, java.lang.String tag, java.lang.StringBuffer data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static void	simpleEmbedElements(java.lang.StringBuilder xml, java.lang.String tag, java.lang.String data) Given a StringBuilder of xml data, append a new tag named tag data of data.
static void	simpleEmbedElements(java.lang.StringBuilder xml, java.lang.String tag, java.lang.StringBuilder data) Given a stringbuffer of xml data, append a new tag named tag data of data.
static java.lang.String	simpleStripHeader(java.lang.String xml) Remove the XML header.
static java.lang.String	simpleStripRoot(java.lang.String xml) Strips root element from a string of xml.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT

See Also:

Constant Field Values

VERSION

public static final java.lang.String VERSION

Constructor Detail

XMLUtils

public XMLUtils()

Method Detail

resolveNamespaceURI

public static java.lang.String resolveNamespaceURI(org.w3c.dom.Element aNode,
                                                   java.lang.String aPrefix)

Return the namespace URI associated with the given prefix. Traverse through all ancestors of the given node looking for the 'xmlns:prefix' attribute.

Parameters:

aNode - the element node that the search will start from

aPrefix - the prefix shortcut for the namespace URI

Returns:

the namespace URI, or null if not found

resolveNSPrefix

public static java.lang.String resolveNSPrefix(org.w3c.dom.Element aNode,
                                               java.lang.String aNamespaceURI)

Return the prefix associated with the given namespace URI. Traverse through all ancestors of the given node looking for the 'xmlns:prefix' attribute.

Parameters:

aNode - the element node that the search will start from

aNamespaceURI - the namespace URI for the prefix

Returns:

the prefix, or null if not found

resolveQNameRef

public static javax.xml.namespace.QName resolveQNameRef(org.w3c.dom.Element aNode,
                                                        java.lang.String aRefVal)

Return the resolved qualified name of the specified value, which may contain a prefix that refers to a namespace mapping in one of the node's ancestors.

Parameters:

aNode - the element node that the search will start from

aRefVal - the value to be resolved

Returns:

the qualified name, or null if the namespace URI could not be resolved

getTypeQName

public static javax.xml.namespace.QName getTypeQName(org.w3c.dom.Element aNode)

Return the resolved qualified name of the type referred to by the 'xsi:type' attribute of the given element node. The type reference may contain a prefix that refers to a namespace mapping in one of the node's ancestors.

Parameters:

aNode - the element node that may contain the 'xsi:type' attribute

Returns:

the qualified name, or null if the type attribute isn't present or the namespace URI could not be resolved

getAttributeValue

public static java.lang.String getAttributeValue(org.w3c.dom.Element aNode,
                                                 java.lang.String aAttrName)

Return the string value of the named attribute.

Parameters:

aNode - the element that contains the attribute

aAttrName - the unqualified attribute name

Returns:

the attribute value, or null if not found

isNil

public static boolean isNil(org.w3c.dom.Element aNode)

Return the boolean value of the named attribute.

Parameters:

aNode - the element that contains the attribute

Returns:

the attribute value

getAttributeValue

public static java.lang.String getAttributeValue(org.w3c.dom.Element aNode,
                                                 java.lang.String aNamespaceURI,
                                                 java.lang.String aLocalName)

Return the string value of the fully-qualified attribute.

Parameters:

aNode - the element node that contains the attribute

aNamespaceURI - the namespace qualifier of the attribute name

aLocalName - the local part of the attribute name

Returns:

the attribute value, or null if not found

getElementNodeValue

public static java.lang.String getElementNodeValue(org.w3c.dom.Element aNode)

Return a concatenated string of the text node children of the given element node.

Parameters:

aNode - the element node

Returns:

the concatenated value of the child text nodes

getFirstChildElement

public static org.w3c.dom.Element getFirstChildElement(org.w3c.dom.Element aNode)

Return the first child element node of the given element node.

Parameters:

aNode - the parent element node

Returns:

the child element node, or null if not found

getNextSiblingElement

public static org.w3c.dom.Element getNextSiblingElement(org.w3c.dom.Element aNode)

Return the immediate sibling element node of the given element node.

Parameters:

aNode - the element node

Returns:

the sibling element node, or null if not found

getNamedChildElement

public static org.w3c.dom.Element getNamedChildElement(org.w3c.dom.Element aNode,
                                                       java.lang.String aElemName)

Return the first child element node with a matching unqualified name.

Parameters:

aNode - the parent element node

aElemName - the unqualified child element name

Returns:

the child element node, or null if not found

getNamedChildElement

public static org.w3c.dom.Element getNamedChildElement(org.w3c.dom.Element aNode,
                                                       java.lang.String aNamespaceURI,
                                                       java.lang.String aLocalName)

Return the first child element node with a matching qualified name.

Parameters:

aNode - the parent element node

aNamespaceURI - the namespace qualifier of the child element name

aLocalName - the local part of the child element name

Returns:

the child element node, or null if not found

getNamedSiblingElement

public static org.w3c.dom.Element getNamedSiblingElement(org.w3c.dom.Element aNode,
                                                         java.lang.String aElemName)

Return the first sibling element node with a matching unqualified name.

Parameters:

aNode - the starting element node

aElemName - the unqualified sibling element name

Returns:

the sibling element node, or null if not found

getNamedSiblingElement

public static org.w3c.dom.Element getNamedSiblingElement(org.w3c.dom.Element aNode,
                                                         java.lang.String aNamespaceURI,
                                                         java.lang.String aLocalName)

Return the first sibling element node with a matching qualified name.

Parameters:

aNode - the starting element node

aNamespaceURI - the namespace qualifier of the sibling element name

aLocalName - the local part of the sibling element name

Returns:

the sibling element node, or null if not found

getNamedChildElements

public static java.util.List getNamedChildElements(org.w3c.dom.Element aNode,
                                                   java.lang.String aElemName)

Return all child element nodes with a matching unqualified name.

Parameters:

aNode - the parent element node

aElemName - the unqualified child element name

Returns:

the list of matching child element nodes

getNamedChildElements

public static java.util.List getNamedChildElements(org.w3c.dom.Element aNode,
                                                   java.lang.String aNamespaceURI,
                                                   java.lang.String aLocalName)

Return all child element nodes with a matching qualified name.

Parameters:

aNode - the parent element node

aNamespaceURI - the namespace qualifier of the child element name

aLocalName - the local part of the child element name

Returns:

the list of matching child element nodes

getAllAttributes

public static java.util.List getAllAttributes(org.w3c.dom.Element aNode)

Return all attributes of the given element node.

Parameters:

aNode - the element node

Returns:

the list of attribute nodes

getAllChildElements

public static java.util.List getAllChildElements(org.w3c.dom.Element aNode)

Return all child elements of the given element node.

Parameters:

aNode - the parent element node

Returns:

the list of child element nodes

getChildElement

public static org.w3c.dom.Element getChildElement(org.w3c.dom.Element aParent,
                                                  java.lang.String aName)

Perform a depth-first traversal of the parent element, and return the first child element with a matching tag name.

Parameters:

aParent - the parent element node

aName - the element tag name to search for

Returns:

the matching child element, or null if not found

encodeString

public static java.lang.String encodeString(java.lang.String in)

Encode the xml special characters "<",">","'",""","&". Prefer this method over encode(String), if no encoding is required then there are no extra objects created.

Parameters:

in - string to encode

Returns:

the encoded string or null on null input

encode

public static java.lang.StringBuffer encode(java.lang.String string)

Deprecated.

Encode the xml special characters "<",">","'",""","&".

Parameters:

string - to encode

Returns:

encoded string as a stringbuffer

encode

public static java.lang.StringBuffer encode(java.lang.StringBuffer in)

Encode the xml special characters "<",">","'",""","&".

Parameters:

in - buffer to encode

Returns:

new encoded buffer

encode

public static java.lang.StringBuilder encode(java.lang.StringBuilder in)

Encode the xml special characters "<",">","'",""","&".

Parameters:

in - buffer to encode

Returns:

new encoded buffer

simpleAddElement

public static void simpleAddElement(java.lang.StringBuffer xml,
                                    java.lang.String tag,
                                    java.lang.StringBuffer data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Data will be encoded.

Parameters:

xml -

tag -

data -

simpleAddElement

public static void simpleAddElement(java.lang.StringBuilder xml,
                                    java.lang.String tag,
                                    java.lang.StringBuilder data)

Given a stringbuilder of xml data, append a new tag named tag data of data.

Data will be encoded.

Parameters:

xml -

tag -

data -

simpleAddElement

public static void simpleAddElement(java.lang.StringBuffer xml,
                                    java.lang.String tag,
                                    java.lang.String data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Data will be encoded.

Parameters:

xml -

tag -

data -

simpleAddElement

public static void simpleAddElement(java.lang.StringBuilder xml,
                                    java.lang.String tag,
                                    java.lang.String data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Data will be encoded.

Parameters:

xml -

tag -

data -

simpleAddElement

public static void simpleAddElement(java.lang.StringBuffer xml,
                                    java.lang.String tag,
                                    long data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Parameters:

xml -

tag -

data -

simpleAddElement

public static void simpleAddElement(java.lang.StringBuilder xml,
                                    java.lang.String tag,
                                    long data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Parameters:

xml -

tag -

data -

simpleEmbedElements

public static void simpleEmbedElements(java.lang.StringBuffer xml,
                                       java.lang.String tag,
                                       java.lang.StringBuffer data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Data will *not* be encoded.

Parameters:

xml -

tag -

data -

simpleEmbedElements

public static void simpleEmbedElements(java.lang.StringBuilder xml,
                                       java.lang.String tag,
                                       java.lang.StringBuilder data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Data will *not* be encoded.

Parameters:

xml -

tag -

data -

simpleEmbedElements

public static void simpleEmbedElements(java.lang.StringBuffer xml,
                                       java.lang.String tag,
                                       java.lang.String data)

Given a stringbuffer of xml data, append a new tag named tag data of data.

Data will *not* be encoded.

Parameters:

xml -

tag -

data -

simpleEmbedElements

public static void simpleEmbedElements(java.lang.StringBuilder xml,
                                       java.lang.String tag,
                                       java.lang.String data)

Given a StringBuilder of xml data, append a new tag named tag data of data.

Data will *not* be encoded.

Parameters:

xml -

tag -

data -

simpleStripHeader

public static java.lang.String simpleStripHeader(java.lang.String xml)

Remove the XML header.

Useful if this XML is to be encapsulated by other tags...

Parameters:

xml -

Returns:

xml without the header

simpleStripRoot

public static java.lang.String simpleStripRoot(java.lang.String xml)

Strips root element from a string of xml.

 ex:   in: 
                out: 
 

Parameters:

xml - XML to strip

Returns:

the stipped xml

removeElementsByNSPrefix

public static void removeElementsByNSPrefix(java.lang.StringBuilder aXMLBuffer,
                                            java.lang.String aNsPrefix,
                                            boolean aIgnoreCase)

Removes all elements from the XML string that have a namespace prefix matching the regex in the first argument. The namespace declaration(s) will NOT be removed.

Parameters:

aXMLBuffer - a StringBuilder containing XML data to process

aNsPrefix - a namespace prefix

aIgnoreCase - enables case-insensitivty for the regular expression.

removeElements

public static void removeElements(java.lang.StringBuilder aXMLBuffer,
                                  java.lang.String aTypeRegex,
                                  boolean aIsPrefix,
                                  boolean aIgnoreCase)

Removes all elements from the XML String that have types matching the regex in the first argument. See BUG-58098

Parameters:

aXMLBuffer - a StringBuilder containing XML data to process

aTypeRegex - a java-formatted regular expression for finding elements

aIsPrefix - enables using the regex as a prefix for element types intead of exact.

aIgnoreCase - enables case-insensitive mode for regular expression

collectElements

public static void collectElements(java.lang.StringBuilder aXMLBuffer,
                                   java.lang.String aTypeRegex,
                                   boolean aIsPrefix,
                                   boolean aIgnoreCase,
                                   boolean aRemove,
                                   java.util.Collection aCollection)

Collects (as Strings) all elements from the XML String that have types matching the regex in the first argument. See BUG-58098 Note that both a nested match and the match that contains it will be returned as separate tokens.

Parameters:

aXMLBuffer - a StringBuilder containing XML data to process

aTypeRegex - a java-formatted regular expression for finding elements

aIsPrefix - enables using the regex as a prefix for element types instead of exact.

aIgnoreCase - enables case-insensitive mode for regular expression

aRemove - removes elements upon discovery

aCollection - a java collection for placing String representations of discovered elements

getAttributesFromTag

public static java.util.Map<java.lang.String,java.lang.String> getAttributesFromTag(java.lang.String aTag)
                                                                             throws java.lang.IllegalArgumentException

Obtains a mapping of attribute keys and values from an XML or HTML tag

Parameters:

aTag - the text rep of a tag

Returns:

a map of the attributes of the tag

Throws:

java.lang.IllegalArgumentException

getAttributesFromTag

public static java.util.Map<java.lang.String,java.lang.String> getAttributesFromTag(java.lang.String aTag,
                                                                                    boolean isHTML)
                                                                             throws java.lang.IllegalArgumentException

Obtains a mapping of attribute keys and values from an XML or HTML tag

Parameters:

aTag - the text rep of a tag

isHTML - enables or disables forcing lowercase-key entries in the map

Returns:

a map of the attributes of the tag

Throws:

java.lang.IllegalArgumentException

makeCloseTag

public static java.lang.String makeCloseTag(java.lang.String aType)

Makes a closing XML tag String based on the input.

Parameters:

aType - the type of tag

Returns:

the String representation of the XML tag that is described.

makeTag

public static java.lang.String makeTag(java.lang.String aType,
                                       java.util.Map<java.lang.String,java.lang.String> aAttrMap,
                                       boolean aSelfClosing)

Makes an XML tag String based on the input.

Parameters:

aType - the type of tag

aAttrMap - a map of attributes to include

aSelfClosing - enables the tag to close itself

Returns:

the String representation of the XML tag that is described.

findNode

public static org.w3c.dom.Node findNode(org.w3c.dom.Element aElement,
                                        java.lang.String aNodeType,
                                        java.lang.String aAttrKey,
                                        java.lang.String aAttrValue)

Finds the "first" node in the children of an Element that matches the input criteria.

Parameters:

aNodeType - - the type of node to find

aAttrKey - - the key of an attribute to search for

aAttrValue - - the value of an attribute to search for

aElement - - an element to search

Returns:

the Node that was found, or null.

findNode

public static org.w3c.dom.Node findNode(org.w3c.dom.Element aElement,
                                        java.lang.String aNodeType,
                                        java.util.Map<java.lang.String,java.lang.String> aAttributeMap)

Finds the "first" node in the children of an Element that matches the input criteria.

Parameters:

aNodeType - - the type of node to search for

aAttributeMap - - a subset of the attributes for the Node to be found

aElement - the element with children to be searched

Returns:

the Node that was found, or null.