com.ibm.are.common
Class XmlUtils

java.lang.Object
  extended by com.ibm.are.common.XmlUtils

public final class XmlUtils
extends java.lang.Object

The XmlUtils class provides a variety of XML utility methods used by other ARE classes.

Version:
1.0
Author:
IBM

Nested Class Summary
protected static class XmlUtils.SingleNode
          The SingleNode class encapsulates a single XML node as well as a string value.
 
Field Summary
static java.lang.String COPYRIGHT
          Copyright for class bytecode
 
Constructor Summary
XmlUtils()
           
 
Method Summary
static org.w3c.dom.Document createNewDocument()
          Creates a new XML document
static org.w3c.dom.Element[] findAllChildElements(org.w3c.dom.Node parent, java.lang.String searchNodeName)
          Find all child elements with the given name within the direct children of the parent node.
static org.w3c.dom.Element findChildElement(org.w3c.dom.Node parent, java.lang.String searchNodeName)
          Find the first child element with the given name within the direct children of the parent node.
static org.w3c.dom.Node findNodeInList(org.w3c.dom.NodeList theList, java.lang.String searchNodeName)
          Find the first node with the given name in the node list.
static org.w3c.dom.Node[] findNodesInList(org.w3c.dom.NodeList theList, java.lang.String searchNodeName)
          Find all nodes with the given name in the node list.
static org.w3c.dom.Node findNodeWithAttributeValue(org.w3c.dom.NodeList theList, java.lang.String searchNodeName, java.lang.String attributeName, java.lang.String attributeValue)
          Searches the node list for a node with the specified name that contains an attribute with the specified name and value.
static org.w3c.dom.Node findParentNode(org.w3c.dom.Node startNode, java.lang.String parentName)
          Recursively searches back up the XML node tree, searching for a parent node that matches the specified search name.
static java.lang.String getItemFromMap(org.w3c.dom.NamedNodeMap nodeMap, java.lang.String whichItem)
          Retrieves the value for the specified attribute from the provided node map
static java.lang.String getItemFromMap(org.w3c.dom.NamedNodeMap nodeMap, java.lang.String whichItem, java.lang.String defaultValue)
          Retrieves the value for the specified attribute from the provided node map
static java.lang.String getItemFromNode(org.w3c.dom.Node theNode, java.lang.String whichItem)
          Retrieves the value for the specified attribute from the provided node
static java.lang.String getItemFromNode(org.w3c.dom.Node theNode, java.lang.String whichItem, java.lang.String defaultValue)
          Retrieves the value for the specified attribute from the provided node
static java.lang.String getNodeTextContent(org.w3c.dom.Node node)
          An alternative to the Node.getTextContent method (DOM3/JDK1.5) Note that this method only works with the simplest method to retrieve text content.
static com.ibm.are.xml.Reference getReferenceFromName(com.ibm.are.xml.XmlParsingEngine parsingEngine, java.lang.String name)
          Retrieves the specified reference from the global context of the provided parsing engine.
static java.lang.String getRequiredAttribute(org.w3c.dom.Node theNode, java.lang.String attributeName)
          Retrieves the value for the specified attribute from the given node.
static org.w3c.dom.Document getXmlDocumentFromFile(java.lang.String xmlFileName)
          Retrieves an XML document from a file
static org.w3c.dom.Document getXmlDocumentFromJar(java.lang.String xmlFileName, java.lang.ClassLoader loader)
          Retrieves an XML document from a file in a JAR
static org.w3c.dom.Document getXmlDocumentFromStream(java.io.InputStream xmlFileStream)
          Builds and returns an XML document from the provided input stream
static org.w3c.dom.Document getXmlDocumentFromUrl(java.net.URL xmlFileUrl)
          Retrieves an XML document from a URL
static int pruneNodes(org.w3c.dom.Node topNode, java.lang.String nodeName, java.lang.String attributeKey, java.lang.String valueToMatch)
          Prunes all child nodes that contain the specified attribute name and value
static boolean setItemInMap(org.w3c.dom.NamedNodeMap nodeMap, java.lang.String whichItem, java.lang.String value)
          Sets the value for the specified attribute in the provided node map
static boolean setItemInNode(org.w3c.dom.Node theNode, java.lang.String whichItem, java.lang.String value)
          Sets the value for the specified attribute in the provided node
static void setNodeTextContent(org.w3c.dom.Node node, java.lang.String text)
          An alternative to the Node.setTextContent method (DOM3/JDK1.5) Note that this is a very simple solution which should only be used for a simple text node.
static org.w3c.dom.Node sortNodes(org.w3c.dom.Node topNode, java.lang.String childNodeName, java.lang.String attributeToSortOn)
          Sorts a set of child nodes based on the specified attribute value
static void verifyNotEmpty(java.lang.String stringValue, java.lang.String exceptionMsg)
          Verifies the specified string is not null or empty
static void verifyNotNull(java.lang.Object objToVerify, java.lang.String exceptionMsg)
          Verifies the specified object reference is not null
static void verifyNull(java.lang.Object objToVerify, java.lang.String exceptionMsg)
          Verifies the specified object reference is null
static void writeDocumentToXmlFile(org.w3c.dom.Document xmlDoc, java.io.File xmlFile)
          Writes the XML document to the specified file
static void writeXmlDocumentToStream(org.w3c.dom.Document xmlDoc, java.io.Writer outWriter)
          Writes the XML document to the provided writer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT
Copyright for class bytecode

See Also:
Constant Field Values
Constructor Detail

XmlUtils

public XmlUtils()
Method Detail

getItemFromNode

public static java.lang.String getItemFromNode(org.w3c.dom.Node theNode,
                                               java.lang.String whichItem)
Retrieves the value for the specified attribute from the provided node

Parameters:
theNode - The node to retrieve the attribute value from
whichItem - The name of the attribute to retrieve the value of
Returns:
The value of the specified attribute in the node, or null if the specified attribute cannot be found in the provided node.

getItemFromNode

public static java.lang.String getItemFromNode(org.w3c.dom.Node theNode,
                                               java.lang.String whichItem,
                                               java.lang.String defaultValue)
Retrieves the value for the specified attribute from the provided node

Parameters:
theNode - The node to retrieve the attribute value from
whichItem - The name of the attribute to retrieve the value of
defaultValue - The default value to return if the specified attribute cannot be found in the provided node
Returns:
The value of the specified attribute in the node, or defaultValue if the specified attribute cannot be found in the provided node.

getItemFromMap

public static java.lang.String getItemFromMap(org.w3c.dom.NamedNodeMap nodeMap,
                                              java.lang.String whichItem)
Retrieves the value for the specified attribute from the provided node map

Parameters:
nodeMap - The node map to retrieve the attribute value from
whichItem - The name of the attribute to retrieve the value of
Returns:
The value of the specified attribute in the node map, or null if the specified attribute cannot be found in the provided node map.

getItemFromMap

public static java.lang.String getItemFromMap(org.w3c.dom.NamedNodeMap nodeMap,
                                              java.lang.String whichItem,
                                              java.lang.String defaultValue)
Retrieves the value for the specified attribute from the provided node map

Parameters:
nodeMap - The node map to retrieve the attribute value from
whichItem - The name of the attribute to retrieve the value of
defaultValue - The default value to return if the specified attribute cannot be found in the provided node map
Returns:
The value of the specified attribute in the node, or defaultValue if the specified attribute cannot be found in the provided node map.

setItemInMap

public static boolean setItemInMap(org.w3c.dom.NamedNodeMap nodeMap,
                                   java.lang.String whichItem,
                                   java.lang.String value)
Sets the value for the specified attribute in the provided node map

Parameters:
nodeMap - The node map to set the attribute value in
whichItem - The attribute whose value will be set
value - The value to set
Returns:
true if the attribute value was set, false if it was not. Typically the attribute value cannot be set due to the attribute itself not existing in the given node map.

setItemInNode

public static boolean setItemInNode(org.w3c.dom.Node theNode,
                                    java.lang.String whichItem,
                                    java.lang.String value)
Sets the value for the specified attribute in the provided node

Parameters:
theNode - The node to set the attribute value in
whichItem - The attribute whose value will be set
value - The value to set
Returns:
true if the attribute value was set, false if it was not. Typically the attribute value cannot be set due to the attribute itself not existing in the given node.

findNodeInList

public static org.w3c.dom.Node findNodeInList(org.w3c.dom.NodeList theList,
                                              java.lang.String searchNodeName)
Find the first node with the given name in the node list. The search is done in a case insensitive manner.

Parameters:
theList - The list of XML nodes to search
searchNodeName - The node name to search for
Returns:
The XML node corresponding to the search node name, if found. If the node is not found, null is returned.

findNodesInList

public static org.w3c.dom.Node[] findNodesInList(org.w3c.dom.NodeList theList,
                                                 java.lang.String searchNodeName)
Find all nodes with the given name in the node list. The search is done in a case insensitive manner.

Parameters:
theList - The list of XML nodes to search
searchNodeName - The node name to search for
Returns:
An array of XML nodes matching the search node name. If no nodes were found, a zero length array is returned.

findChildElement

public static org.w3c.dom.Element findChildElement(org.w3c.dom.Node parent,
                                                   java.lang.String searchNodeName)
Find the first child element with the given name within the direct children of the parent node. The search is done in a case insensitive manner.

Parameters:
parent - The parent XML node to start the search from
searchNodeName - The node name to search for
Returns:
The XML node corresponding to the search node name, if found. If the node is not found, null is returned.

findAllChildElements

public static org.w3c.dom.Element[] findAllChildElements(org.w3c.dom.Node parent,
                                                         java.lang.String searchNodeName)
Find all child elements with the given name within the direct children of the parent node. The search is done in a case insensitive manner.

Parameters:
parent - The parent XML node to start the search from
searchNodeName - The node name to search for
Returns:
An array of XML nodes matching the search node name. If no nodes were found, a zero length array is returned.

findParentNode

public static org.w3c.dom.Node findParentNode(org.w3c.dom.Node startNode,
                                              java.lang.String parentName)
Recursively searches back up the XML node tree, searching for a parent node that matches the specified search name. The search is done in a case insensitive manner.

Parameters:
startNode - The node to start the search from
parentName - The name of the parent node to search for
Returns:
The XML node that matched the parent node name, or null if no match was found.

findNodeWithAttributeValue

public static org.w3c.dom.Node findNodeWithAttributeValue(org.w3c.dom.NodeList theList,
                                                          java.lang.String searchNodeName,
                                                          java.lang.String attributeName,
                                                          java.lang.String attributeValue)
Searches the node list for a node with the specified name that contains an attribute with the specified name and value.

Parameters:
theList - The list of XML nodes to search
searchNodeName - The name of the node to search for
attributeName - The name of the attribute within the node to search for
attributeValue - The value of the attribute to search for
Returns:
The XML node that matches the search criteria, or null if no match was found

createNewDocument

public static org.w3c.dom.Document createNewDocument()
                                              throws java.lang.Exception
Creates a new XML document

Returns:
A newly created XML document
Throws:
java.lang.Exception - If an exception occurs during the creation of the XML document

getXmlDocumentFromJar

public static org.w3c.dom.Document getXmlDocumentFromJar(java.lang.String xmlFileName,
                                                         java.lang.ClassLoader loader)
Retrieves an XML document from a file in a JAR

Parameters:
xmlFileName - The name of the XML file
loader - The class loader to use when searching for the XML file resource. If null is specified for the class loader, then the class loader for the XmlUtils class is used.
Returns:
An XML document representing the specified XML file, or null if an exception occurred.

getXmlDocumentFromFile

public static org.w3c.dom.Document getXmlDocumentFromFile(java.lang.String xmlFileName)
Retrieves an XML document from a file

Parameters:
xmlFileName - The name of the XML file
Returns:
An XML document representing the specified XML file, or null if an exception occurred.

getXmlDocumentFromUrl

public static org.w3c.dom.Document getXmlDocumentFromUrl(java.net.URL xmlFileUrl)
Retrieves an XML document from a URL

Parameters:
xmlFileUrl - The URL to the XML file
Returns:
An XML document representing the specified XML file, or null if an exception occurred.

getXmlDocumentFromStream

public static org.w3c.dom.Document getXmlDocumentFromStream(java.io.InputStream xmlFileStream)
Builds and returns an XML document from the provided input stream

Parameters:
xmlFileStream - The input stream to build the XML document from
Returns:
An XML document representing the data read from the input stream, or null if an exception occurred.

writeXmlDocumentToStream

public static void writeXmlDocumentToStream(org.w3c.dom.Document xmlDoc,
                                            java.io.Writer outWriter)
                                     throws java.lang.Exception
Writes the XML document to the provided writer

Parameters:
xmlDoc - The XML document to write
outWriter - The writer to write the XML document to
Throws:
java.lang.Exception - If an exception occurs while writing the XML document

writeDocumentToXmlFile

public static void writeDocumentToXmlFile(org.w3c.dom.Document xmlDoc,
                                          java.io.File xmlFile)
                                   throws java.lang.Exception
Writes the XML document to the specified file

Parameters:
xmlDoc - The XML document to write
xmlFile - The name of the file to write the XML document to
Throws:
java.lang.Exception - If an exception occurs while writing the XML document

sortNodes

public static org.w3c.dom.Node sortNodes(org.w3c.dom.Node topNode,
                                         java.lang.String childNodeName,
                                         java.lang.String attributeToSortOn)
Sorts a set of child nodes based on the specified attribute value

Parameters:
topNode - The parent of the child nodes that need to be sorted
childNodeName - The name of the child nodes that will be sorted
attributeToSortOn - The name of the attribute whose value will be used to sort the child nodes.
Returns:
A new top node with all of its child nodes sorted

pruneNodes

public static int pruneNodes(org.w3c.dom.Node topNode,
                             java.lang.String nodeName,
                             java.lang.String attributeKey,
                             java.lang.String valueToMatch)
Prunes all child nodes that contain the specified attribute name and value

Parameters:
topNode - The parent of the child nodes that need to be pruned
nodeName - The name of the node to evaluate and potentially prune
attributeKey - The name of the attribute to inspect
valueToMatch - The attribute value to match, where a match means the node is pruned (removed) from the XML document.
Returns:
The number of nodes that were pruned

verifyNull

public static void verifyNull(java.lang.Object objToVerify,
                              java.lang.String exceptionMsg)
Verifies the specified object reference is null

Parameters:
objToVerify - The object to verify
exceptionMsg - If the object is not null, the detail message for the exception
Throws:
com.ibm.are.xml.XmlFormatException - If the object is not null

verifyNotNull

public static void verifyNotNull(java.lang.Object objToVerify,
                                 java.lang.String exceptionMsg)
Verifies the specified object reference is not null

Parameters:
objToVerify - The object to verify
exceptionMsg - If the object is null, the detail message for the exception
Throws:
com.ibm.are.xml.XmlFormatException - If the object is null

verifyNotEmpty

public static void verifyNotEmpty(java.lang.String stringValue,
                                  java.lang.String exceptionMsg)
Verifies the specified string is not null or empty

Parameters:
stringValue - The string to verify
exceptionMsg - If the string is null or empty, the detail message for the exception that is thrown
Throws:
com.ibm.are.xml.XmlFormatException - If the string is null or empty

getRequiredAttribute

public static java.lang.String getRequiredAttribute(org.w3c.dom.Node theNode,
                                                    java.lang.String attributeName)
Retrieves the value for the specified attribute from the given node. If the specified attribute does not exist in the node, an exception is thrown.

Parameters:
theNode - The node to retrieve the attribute value from
attributeName - The name of the attribute to retrieve the value of
Returns:
The specified attribute value
Throws:
com.ibm.are.xml.XmlFormatException - If the specified attribute does not exist in the node

getReferenceFromName

public static com.ibm.are.xml.Reference getReferenceFromName(com.ibm.are.xml.XmlParsingEngine parsingEngine,
                                                             java.lang.String name)
Retrieves the specified reference from the global context of the provided parsing engine.

Parameters:
parsingEngine - The parsing engine whose global context contains the specified reference
name - The name of the reference to retrieve
Returns:
The specified reference
Throws:
com.ibm.are.xml.XmlFormatException - If the specified reference cannot be found

getNodeTextContent

public static java.lang.String getNodeTextContent(org.w3c.dom.Node node)
An alternative to the Node.getTextContent method (DOM3/JDK1.5) Note that this method only works with the simplest method to retrieve text content. The return value is undefined for more complex cases, for example 'node with a non-text child node'.

Parameters:
node - The XML node to get the text content from
Returns:
The text content for the given XML node

setNodeTextContent

public static void setNodeTextContent(org.w3c.dom.Node node,
                                      java.lang.String text)
An alternative to the Node.setTextContent method (DOM3/JDK1.5) Note that this is a very simple solution which should only be used for a simple text node. This method first removes any text node type children of the given node, and then adds a text node (the content) to the given node.

Parameters:
node - The XML node to set the text content for
text - The text to set