org.peace_tools.workspace
Class DOMHelper

java.lang.Object
  org.peace_tools.workspace.DOMHelper

public class DOMHelper
extends java.lang.Object

This class contains a collection of static utility method that are used to retrieve or create elements in a given DOM tree. All the methods in this class are static methods and can be directly invoked. This class is not meant to be (and cannot be) instantiated.

Field Summary

static java.lang.String

PEACE_NS This string defines the name space for the XML elements created by the utility methods.

Constructor Summary

private

DOMHelper() This class is not meant to be instantiated.

Method Summary

static org.w3c.dom.Element	addElement(org.w3c.dom.Element parent, java.lang.String name, java.lang.String value) Helper method to add a new element to a given DOM node.
static org.w3c.dom.Element	getElement(org.w3c.dom.Document parent, java.lang.String childName) Utility method to search for a given immediate child element.
static org.w3c.dom.Element	getElement(org.w3c.dom.Element parent, java.lang.String childName) Utility method to search for a given immediate child element.
private static org.w3c.dom.Element	getElement(org.w3c.dom.NodeList nodes, java.lang.String elementName) Helper method to search within a given list of nodes to locate a given element.
static int	getIntValue(org.w3c.dom.Element parent, java.lang.String elementName) Utility method to obtain the value of a given element as an integer.
static java.lang.String	getStringValue(org.w3c.dom.Document domDoc, java.lang.String elementName) Utility method to obtain the value of a given element as a string.
static java.lang.String	getStringValue(org.w3c.dom.Element parent, java.lang.String elementName) Utility method to obtain the value of a given element as a string.
static java.lang.String	getStringValue(org.w3c.dom.Element parent, java.lang.String elementName, boolean canBeNull) Utility method to obtain the value of a given element as a string.
static java.lang.String	getStringValue(org.w3c.dom.NodeList nodes, java.lang.String elementName, boolean canBeNull) Utility method to obtain the value of a given element as a String.
static boolean	hasElement(org.w3c.dom.Element parent, java.lang.String elementName) Utility method to determine if a given DOM element has an optional sub-element.
static java.lang.String	xmlEncode(java.lang.String text) Encodes any text as PCDATA.

Methods inherited from class java.lang.Object

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

Field Detail

PEACE_NS

public static java.lang.String PEACE_NS

This string defines the name space for the XML elements created by the utility methods.

Constructor Detail

DOMHelper

private DOMHelper()

This class is not meant to be instantiated. Therefore the constructor has been made private to enforce this policy.

Method Detail

getStringValue

public static java.lang.String getStringValue(org.w3c.dom.Document domDoc,
                                              java.lang.String elementName)

Utility method to obtain the value of a given element as a string. This method can be used to search for a given child-element within the root document and if the element is found, it returns the value of the child element as a String.

Note: This method does not recursively search child elements. Only the immediate underlying child elements are searched.

Parameters:

domDoc - The root of the DOM document tree whose immediate underlying child elements are to be searched.

elementName - The name of the element whose value is to be converted to an integer and returned.

Returns:

The value of the element. If the element was not found, then this method will raise an exception. So prior to calling this method check to ensure the element exists via a call to DOMHelper.hasElement()

getStringValue

public static java.lang.String getStringValue(org.w3c.dom.Element parent,
                                              java.lang.String elementName)

Utility method to obtain the value of a given element as a string. This method can be used to search for a given child-element within another element and if the element is found, it returns the value of the child element as a string.

Note: This method does not recursively search its child elements. Only the immediate underlying child elements are searched.

Parameters:

parent - The parent element whose immediate child elements are to be searched.

elementName - The name of the element whose value is to be converted to an integer and returned.

Returns:

The value of the element. If the element was not found, then this method will raise an exception. So prior to calling this method check to ensure the element exists via a call to DOMHelper.hasElement()

getStringValue

public static java.lang.String getStringValue(org.w3c.dom.Element parent,
                                              java.lang.String elementName,
                                              boolean canBeNull)

Utility method to obtain the value of a given element as a string. This method can be used to search for a given child-element within another element and if the element is found, it returns the value of the child element as a string.

Note: This method does not recursively search its child elements. Only the immediate underlying child elements are searched.

Parameters:

parent - The parent element whose immediate child elements are to be searched.

elementName - The name of the element whose value is to be converted to an integer and returned.

canBeNull - This flag indicates that the data can be null.

Returns:

The value of the element. If the element was not found, then this method will raise an exception. So prior to calling this method check to ensure the element exists via a call to DOMHelper.hasElement()

getStringValue

public static java.lang.String getStringValue(org.w3c.dom.NodeList nodes,
                                              java.lang.String elementName,
                                              boolean canBeNull)

Utility method to obtain the value of a given element as a String. This method can be used to search for a given child-element within a list of nodes and if the element is found, it returns the value of the child element as a String. No interpretations are performed on the String value returned by this method.

Note: This method does not recursively search the list of nodes. It only checks the given list of nodes.

Parameters:

nodes - The list of nodes to be searched.

elementName - The name of the element whose value is to be returned as a String.

canBeNull - This flag indicates that the data can be null.

Returns:

The value of the element. If the element was not found, then this method will raise an exception. So prior to calling this method check to ensure the element exists via a call to DOMHelper.hasElement()

getIntValue

public static int getIntValue(org.w3c.dom.Element parent,
                              java.lang.String elementName)

Utility method to obtain the value of a given element as an integer. This method can be used to search for a given child-element within another element and if the element is found, it returns the value of the child element as an integer. This method assumes that the value of the element is expected to be an integer and it has passed validation.

Note: This method does not recursively search its child elements. Only the immediate underlying child elements are searched.

Parameters:

parent - The parent element whose immediate child elements are to be searched.

elementName - The name of the element whose value is to be converted to an integer and returned.

Returns:

The value of the element. If the element was not found, then this method will raise an exception. So prior to calling this method check to ensure the element exists via a call to DOMHelper.hasElement()

hasElement

public static boolean hasElement(org.w3c.dom.Element parent,
                                 java.lang.String elementName)

Utility method to determine if a given DOM element has an optional sub-element. This is a utility method that can be used to determine if an immediate underlying child element is present within a DOM document.

Parameters:

parent - The DOM element within which to search.

elementName - The name of element to be located and returned.

Returns:

This method returns true if the DOM element exists. Otherwise this method returns false.

getElement

public static org.w3c.dom.Element getElement(org.w3c.dom.Document parent,
                                             java.lang.String childName)

Utility method to search for a given immediate child element. This is a utility method that can be used to search for an immediate underlying child element within a DOM document.

Parameters:

parent - The root DOM document within which to search.

childName - The name of element to be located and returned.

Returns:

This method returns a valid DOM element object if an element with the given (childName) was found. If the element was not found then this method returns null.

getElement

public static org.w3c.dom.Element getElement(org.w3c.dom.Element parent,
                                             java.lang.String childName)

Utility method to search for a given immediate child element. This is a utility method that can be used to search for an immediate underlying child element within a DOM element.

Parameters:

parent - The parent DOM element within which to search.

childName - The name of element to be located and returned.

Returns:

This method returns a valid DOM element object if an element with the given (childName) was found. If the element was not found then this method returns null.

getElement

private static org.w3c.dom.Element getElement(org.w3c.dom.NodeList nodes,
                                              java.lang.String elementName)

Helper method to search within a given list of nodes to locate a given element. This method is an internal helper method that is called from other overloaded getElement() methods to locate, test, and return the element corresponding to a given element name.

Note: This method does not search recursively within the list of nodes. Only the immediately underlying child elements are searched for a match.

Parameters:

nodes - The list of DOM nodes in which to search for a given element.

elementName - The name of element to search for.

Returns:

The element node within the list of DOM nodes. If the element is not found, this method returns null.

addElement

public static org.w3c.dom.Element addElement(org.w3c.dom.Element parent,
                                             java.lang.String name,
                                             java.lang.String value)

Helper method to add a new element to a given DOM node. This method is a helper method that is used to add a simple element (under the PEACE name space) with a simple text value to a given DOM element.

Parameters:

parent - The DOM element to which a new element is to be added.

name - The name of the new element to be added to the DOM tree.

value - The value to be associated with the new element.

Returns:

If the element is added successfully, then this method returns the newly created element. On errors it returns null.

xmlEncode

public static final java.lang.String xmlEncode(java.lang.String text)

Encodes any text as PCDATA. This is a helper method that is used to encode a given string into XML safe character set. Specifically, this method translates the following characters: &, <, >, ", and '.

Parameters:

text - The text to be encoded to XML. If this parameter is null, this method immediately exits with null.

Returns:

The string character data suitably encoded into a XML safe string.