org.jboss.cache.xml
Class XmlHelper

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

public class XmlHelper
extends Object

A simple XML utility class for reading configuration elements

Author:

Manik Surtani (manik@jboss.org)

Field Summary

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

Constructor Summary

XmlHelper()

Method Summary

static String	escapeBackslashes(String value) Escapes backslashes ('\') with additional backslashes in a given String, returning a new, escaped String.
static String	getAttributeValue(Element elem, String elementName, String attributeName) Retrieves the value of a given attribute for the first encountered instance of a tag in an element.
static Element	getConfigSubElement(Element element) Convenience method, equivalent to calling getSubElement(element, "config");
static Element	getDocumentRoot(InputStream is) Returns the root element of a given input stream
static String	getElementContent(Element element, boolean trim) Reads the contents of the element passed in.
static Element	getSubElement(Element element, String subElementName) Returns a named sub-element of the current element passed in.
static String	getTagContents(Element elem, String value, String elementName, 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(Element elem, String elementName, String attributeName, boolean defaultValue) Retrieves the boolean value of a given attribute for the first encountered instance of elementName
static boolean	readBooleanContents(Element element, String elementName) Similar to readStringContents(org.w3c.dom.Element,String) except that it returns a boolean.
static boolean	readBooleanContents(Element element, String elementName, boolean defaultValue) Similar to readStringContents(org.w3c.dom.Element,String) except that it returns a boolean.
static Properties	readPropertiesContents(Element element, 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 String	readStringContents(Element element, String elementName) Reads the contents of the first occurence of elementName under the given element, trimming results of whitespace.
static Element	stringToElement(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 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 String ATTR

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

See Also:

Constant Field Values

CONFIG_ATTR

public static final 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 String NAME

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

See Also:

Constant Field Values

Constructor Detail

XmlHelper

public XmlHelper()

Method Detail

getTagContents

public static String getTagContents(Element elem,
                                    String value,
                                    String elementName,
                                    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 String getAttributeValue(Element elem,
                                       String elementName,
                                       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 Element getConfigSubElement(Element element)

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

getSubElement

public static Element getSubElement(Element element,
                                    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 String getElementContent(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 String readStringContents(Element element,
                                        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 String escapeBackslashes(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 Properties readPropertiesContents(Element element,
                                                String elementName)
                                         throws 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:
IOException - if unable to parse the contents of the element

readBooleanContents

public static boolean readBooleanContents(Element element,
                                          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(Element element,
                                          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 Element stringToElement(String xml)
                               throws Exception

Converts a String representing an XML snippet into an Element.

Parameters:

xml - snippet as a string

Returns:

a DOM Element

Throws:

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

getDocumentRoot

public static Element getDocumentRoot(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(Element elem,
                                           String elementName,
                                           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