org.jboss.cache.xml
Class XmlHelper

java.lang.Object
  org.jboss.cache.xml.XmlHelper

public class XmlHelper
extends java.lang.Object

A simple XML utility class for reading configuration elements

Author:

Manik Surtani (manik@jboss.org)

Field Summary

static java.lang.String	ATTR The <attribute> tag which forms the bulk of JBoss Cache configuration elements
static java.lang.String	CONFIG_ATTR The <config> tag may be embedded in the contents of an <attribute>, to specify more complex configuration for certain parameters.
static java.lang.String	NAME The <name> attribute to an <attribute> tag.
static java.lang.String	ROOT The root of a JBoss Cache configuration XML file.

Constructor Summary

XmlHelper()

Method Summary

static java.lang.String	escapeBackslashes(java.lang.String value) Escapes backslashes ('\') with additional backslashes in a given String, returning a new, escaped String.
static java.lang.String	getAttributeValue(org.w3c.dom.Element elem, java.lang.String elementName, java.lang.String attributeName) Retrieves the value of a given attribute for the first encountered instance of a tag in an element.
static org.w3c.dom.Element	getConfigSubElement(org.w3c.dom.Element element) Convenience method, equivalent to calling getSubElement(element, "config");
static org.w3c.dom.Element	getDocumentRoot(java.io.InputStream is) Returns the root element of a given input stream
static java.lang.String	getElementContent(org.w3c.dom.Element element, boolean trim) Reads the contents of the element passed in.
static org.w3c.dom.Element	getSubElement(org.w3c.dom.Element element, java.lang.String subElementName) Returns a named sub-element of the current element passed in.
static java.lang.String	getTagContents(org.w3c.dom.Element elem, java.lang.String value, java.lang.String elementName, java.lang.String attributeName) Returns the contents of a specific node of given element name, provided a certain attribute exists and is set to value.
static boolean	readBooleanAttribute(org.w3c.dom.Element elem, java.lang.String elementName, java.lang.String attributeName, boolean defaultValue) Retrieves the boolean value of a given attribute for the first encountered instance of elementName
static boolean	readBooleanContents(org.w3c.dom.Element element, java.lang.String elementName) Similar to readStringContents(org.w3c.dom.Element,String) except that it returns a boolean.
static boolean	readBooleanContents(org.w3c.dom.Element element, java.lang.String elementName, boolean defaultValue) Similar to readStringContents(org.w3c.dom.Element,String) except that it returns a boolean.
static java.util.Properties	readPropertiesContents(org.w3c.dom.Element element, java.lang.String elementName) Reads the contents of a named sub element within a given element, and attempts to parse the contents as a Java properties file.
static java.lang.String	readStringContents(org.w3c.dom.Element element, java.lang.String elementName) Reads the contents of the first occurence of elementName under the given element, trimming results of whitespace.
static org.w3c.dom.Element	stringToElement(java.lang.String xml) Converts a String representing an XML snippet into an Element.

Methods inherited from class java.lang.Object

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

Field Detail

ROOT

public static final java.lang.String ROOT

The root of a JBoss Cache configuration XML file. This is the <mbean> tag.

See Also:

Constant Field Values

ATTR

public static final java.lang.String ATTR

The <attribute> tag which forms the bulk of JBoss Cache configuration elements

See Also:

Constant Field Values

CONFIG_ATTR

public static final java.lang.String CONFIG_ATTR

The <config> tag may be embedded in the contents of an <attribute>, to specify more complex configuration for certain parameters.

See Also:

Constant Field Values

NAME

public static final java.lang.String NAME

The <name> attribute to an <attribute> tag.

See Also:

Constant Field Values

Constructor Detail

XmlHelper

public XmlHelper()

Method Detail

getTagContents

public static java.lang.String getTagContents(org.w3c.dom.Element elem,
                                              java.lang.String value,
                                              java.lang.String elementName,
                                              java.lang.String attributeName)

Returns the contents of a specific node of given element name, provided a certain attribute exists and is set to value. E.g., if you have a Element which represents the following XML snippet:

   <ItemQuantity Colour="Red">100</ItemQuantity>
   <ItemQuantity Colour="Blue">30</ItemQuantity>
   <ItemQuantity Colour="Black">10</ItemQuantity>
 
 

 The following results could be expected:
 
 
    getTagContents(element, "Red", "ItemQuantity", "Colour"); // 100
    getTagContents(element, "Black", "ItemQuantity", "Colour"); // 10
    getTagContents(element, "Blah", "ItemQuantity", "Colour"); // null
    getTagContents(element, "Red", "Blah", "Colour"); // null
    getTagContents(element, "Black", "ItemQuantity", "Blah"); // null
 
 

 None of the parameters should be null - otherwise the method may throw a NullPointerException.
 


Parameters:
elem - - element to search through.
value - - expected value to match against
elementName - - element name
attributeName - - attribute name of the element that would contain the expected value.
Returns:
the contents of the matched element, or null if not found/matched

getAttributeValue

public static java.lang.String getAttributeValue(org.w3c.dom.Element elem,
                                                 java.lang.String elementName,
                                                 java.lang.String attributeName)

Retrieves the value of a given attribute for the first encountered instance of a tag in an element.

E.g., if you have a Element which represents the following XML snippet:

   <ItemQuantity Colour="Red">100</ItemQuantity>
   <ItemQuantity Colour="Blue">30</ItemQuantity>
   <ItemQuantity Colour="Black">10</ItemQuantity>
 
 

 The following results could be expected:
 
 
    getAttributeValue(element, "ItemQuantity", "Colour"); // "Red"
    getTagContents(element, "Blah", "Colour"); // null
    getTagContents(element, "ItemQuantity", "Blah"); // null
 
 None of the parameters should be null - otherwise the method may throw a NullPointerException.


Parameters:
elem - - element to search through.
elementName - - element name
attributeName - - attribute name of the element that would contain the expected value.
Returns:
the contents of the matched attribute, or null if not found/matched

getConfigSubElement

public static org.w3c.dom.Element getConfigSubElement(org.w3c.dom.Element element)

Convenience method, equivalent to calling getSubElement(element, "config");

getSubElement

public static org.w3c.dom.Element getSubElement(org.w3c.dom.Element element,
                                                java.lang.String subElementName)

Returns a named sub-element of the current element passed in.

None of the parameters should be null - otherwise the method may throw a NullPointerException.

Parameters:

element - - element to search through.

subElementName - - the name of a sub element to look for

Returns:

the first matching sub element, if found, or null otherwise.

getElementContent

public static java.lang.String getElementContent(org.w3c.dom.Element element,
                                                 boolean trim)

Reads the contents of the element passed in.

None of the parameters should be null - otherwise the method may throw a NullPointerException.

Parameters:

element - - element to search through.

trim - - if true, whitespace is trimmed before returning

Returns:

the contents of the element passed in. Will return an empty String if the element is empty.

readStringContents

public static java.lang.String readStringContents(org.w3c.dom.Element element,
                                                  java.lang.String elementName)

Reads the contents of the first occurence of elementName under the given element, trimming results of whitespace.

None of the parameters should be null - otherwise the method may throw a NullPointerException.

Parameters:

element - - element to search through.

elementName - - name of the element to find within the element passed in

Returns:

may return an empty String of not found.

escapeBackslashes

public static java.lang.String escapeBackslashes(java.lang.String value)

Escapes backslashes ('\') with additional backslashes in a given String, returning a new, escaped String.

Parameters:

value - String to escape. Cannot be null.

Returns:

escaped String. Never is null.

readPropertiesContents

public static java.util.Properties readPropertiesContents(org.w3c.dom.Element element,
                                                          java.lang.String elementName)
                                                   throws java.io.IOException

Reads the contents of a named sub element within a given element, and attempts to parse the contents as a Java properties file.

E.g., if you have a Element which represents the following XML snippet:

   <props>
       my.attrib.1 = blah
       my.attrib.2 = blahblah
   </props>
 
 

 The following results could be expected:
 

 
    Properties p = readPropertiesContents(element, "props");
    p.getProperty("my.attrib.1"); // blah
    p.getProperty("my.attrib.2"); // blahblah
 
 None of the parameters should be null - otherwise the method may throw a NullPointerException.


Parameters:
element - - element to search through.
elementName - - name of the element to find within the element passed in
Returns:
a Properties object, never null.
Throws:
java.io.IOException - if unable to parse the contents of the element

readBooleanContents

public static boolean readBooleanContents(org.w3c.dom.Element element,
                                          java.lang.String elementName)

Similar to readStringContents(org.w3c.dom.Element,String) except that it returns a boolean.

Parameters:

element - - element to search through.

elementName - - name of the element to find within the element passed in

Returns:

the contents of the element as a boolean, or false if not found.

readBooleanContents

public static boolean readBooleanContents(org.w3c.dom.Element element,
                                          java.lang.String elementName,
                                          boolean defaultValue)

Similar to readStringContents(org.w3c.dom.Element,String) except that it returns a boolean.

Parameters:

element - - element to search through.

elementName - - name of the element to find within the element passed in

defaultValue - - value to return if the element is not found or cannot be parsed.

Returns:

the contents of the element as a boolean

stringToElement

public static org.w3c.dom.Element stringToElement(java.lang.String xml)
                                           throws java.lang.Exception

Converts a String representing an XML snippet into an Element.

Parameters:

xml - snippet as a string

Returns:

a DOM Element

Throws:

java.lang.Exception - if unable to parse the String or if it doesn't contain valid XML.

getDocumentRoot

public static org.w3c.dom.Element getDocumentRoot(java.io.InputStream is)

Returns the root element of a given input stream

Parameters:

is - stream to parse

Returns:

XML DOM element, or null if unable to parse stream

readBooleanAttribute

public static boolean readBooleanAttribute(org.w3c.dom.Element elem,
                                           java.lang.String elementName,
                                           java.lang.String attributeName,
                                           boolean defaultValue)

Retrieves the boolean value of a given attribute for the first encountered instance of elementName

Parameters:

elem - - element to search

elementName - - name of element to find

attributeName - - name of attribute to retrieve the value of

defaultValue - - default value to return if not found