[jboss-cvs] JBossCache/src/org/jboss/cache/xml ...
Manik Surtani
manik at jboss.org
Mon Jul 16 23:14:50 EDT 2007
User: msurtani
Date: 07/07/16 23:14:50
Modified: src/org/jboss/cache/xml XmlHelper.java
Log:
JBCACHE-1135
Revision Changes Path
1.16 +157 -29 JBossCache/src/org/jboss/cache/xml/XmlHelper.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: XmlHelper.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/xml/XmlHelper.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -b -r1.15 -r1.16
--- XmlHelper.java 26 Mar 2007 13:30:03 -0000 1.15
+++ XmlHelper.java 17 Jul 2007 03:14:50 -0000 1.16
@@ -39,16 +39,35 @@
/**
- * Returns the contents of a specific node of given tagName, provided a certain attribute exists and contains value myValue.
+ * 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 {@link Element} which represents the following XML snippet:
+ * <pre>
+ * >ItemQuantity Colour="Red"<100>/ItemQuantity<
+ * >ItemQuantity Colour="Blue"<30>/ItemQuantity<
+ * >ItemQuantity Colour="Black"<10>/ItemQuantity<
+ * <pre>
+ * <p/>
+ * The following results could be expected:
+ * <p/>
+ * <pre>
+ * 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
+ * </pre>
+ * <p/>
+ * None of the parameters should be null - otherwise the method may throw a NullPointerException.
*
- * @param elem
- * @param myName
- * @param tagName
- * @param attributeName
+ * @param elem - element to search through.
+ * @param value - expected value to match against
+ * @param elementName - element name
+ * @param attributeName - attribute name of the element that would contain the expected value.
+ * @return the contents of the matched element, or null if not found/matched
*/
- public static String getTagContents(Element elem, String myName, String tagName, String attributeName)
+ public static String getTagContents(Element elem, String value, String elementName, String attributeName)
{
- NodeList list = elem.getElementsByTagName(tagName);
+ NodeList list = elem.getElementsByTagName(elementName);
for (int s = 0; s < list.getLength(); s++)
{
@@ -58,7 +77,7 @@
Element element = (Element) node;
String name = element.getAttribute(attributeName);
- if (name.equals(myName))
+ if (name.equals(value))
{
return getElementContent(element, true);
}
@@ -68,14 +87,32 @@
/**
* Retrieves the value of a given attribute for the first encountered instance of a tag in an element.
+ * <p/>
+ * E.g., if you have a {@link Element} which represents the following XML snippet:
+ * <p/>
+ * <pre>
+ * >ItemQuantity Colour="Red"<100>/ItemQuantity<
+ * >ItemQuantity Colour="Blue"<30>/ItemQuantity<
+ * >ItemQuantity Colour="Black"<10>/ItemQuantity<
+ * <pre>
+ * <p/>
+ * The following results could be expected:
+ * <p/>
+ * <pre>
+ * getAttributeValue(element, "ItemQuantity", "Colour"); // "Red"
+ * getTagContents(element, "Blah", "Colour"); // null
+ * getTagContents(element, "ItemQuantity", "Blah"); // null
+ * </pre>
+ * None of the parameters should be null - otherwise the method may throw a NullPointerException.
*
- * @param elem
- * @param tagName
- * @param attributeName
+ * @param elem - element to search through.
+ * @param elementName - element name
+ * @param attributeName - attribute name of the element that would contain the expected value.
+ * @return the contents of the matched attribute, or null if not found/matched
*/
- public static String getAttributeValue(Element elem, String tagName, String attributeName)
+ public static String getAttributeValue(Element elem, String elementName, String attributeName)
{
- NodeList list = elem.getElementsByTagName(tagName);
+ NodeList list = elem.getElementsByTagName(elementName);
for (int s = 0; s < list.getLength(); s++)
{
@@ -90,11 +127,23 @@
return null;
}
+ /**
+ * Convenience method, equivalent to calling <tt>getSubElement(element, "config");</tt>
+ */
public static Element getConfigSubElement(Element element)
{
return getSubElement(element, CONFIG_ATTR);
}
+ /**
+ * Returns a named sub-element of the current element passed in.
+ * <p/>
+ * None of the parameters should be null - otherwise the method may throw a NullPointerException.
+ *
+ * @param element - element to search through.
+ * @param subElementName - the name of a sub element to look for
+ * @return the first matching sub element, if found, or null otherwise.
+ */
public static Element getSubElement(Element element, String subElementName)
{
NodeList nl = element.getChildNodes();
@@ -111,6 +160,15 @@
return null;
}
+ /**
+ * Reads the contents of the element passed in.
+ * <p/>
+ * None of the parameters should be null - otherwise the method may throw a NullPointerException.
+ *
+ * @param element - element to search through.
+ * @param trim - if true, whitespace is trimmed before returning
+ * @return the contents of the element passed in. Will return an empty String if the element is empty.
+ */
public static String getElementContent(Element element, boolean trim)
{
NodeList nl = element.getChildNodes();
@@ -128,9 +186,18 @@
return attributeText;
}
- public static String readStringContents(Element element, String tagName)
+ /**
+ * Reads the contents of the first occurence of elementName under the given element, trimming results of whitespace.
+ * <p/>
+ * None of the parameters should be null - otherwise the method may throw a NullPointerException.
+ *
+ * @param element - element to search through.
+ * @param elementName - name of the element to find within the element passed in
+ * @return may return an empty String of not found.
+ */
+ public static String readStringContents(Element element, String elementName)
{
- NodeList nodes = element.getElementsByTagName(tagName);
+ NodeList nodes = element.getElementsByTagName(elementName);
if (nodes.getLength() > 0)
{
Node node = nodes.item(0);
@@ -155,6 +222,12 @@
}
}
+ /**
+ * Escapes backslashes ('\') with additional backslashes in a given String, returning a new, escaped String.
+ *
+ * @param value String to escape. Cannot be null.
+ * @return escaped String. Never is null.
+ */
public static String escapeBackslashes(String value)
{
StringBuffer buf = new StringBuffer(value);
@@ -177,9 +250,36 @@
return buf.toString();
}
- public static Properties readPropertiesContents(Element element, String tagName) 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.
+ * <p/>
+ * E.g., if you have a {@link Element} which represents the following XML snippet:
+ * <p/>
+ * <pre>
+ * >props<
+ * my.attrib.1 = blah
+ * my.attrib.2 = blahblah
+ * >/props<
+ * <pre>
+ * <p/>
+ * The following results could be expected:
+ * <p/>
+ * <pre>
+ * Properties p = readPropertiesContents(element, "props");
+ * p.getProperty("my.attrib.1"); // blah
+ * p.getProperty("my.attrib.2"); // blahblah
+ * </pre>
+ * None of the parameters should be null - otherwise the method may throw a NullPointerException.
+ *
+ * @param element - element to search through.
+ * @param elementName - name of the element to find within the element passed in
+ * @return a {@link Properties} object, never null.
+ * @throws IOException if unable to parse the contents of the element
+ */
+ public static Properties readPropertiesContents(Element element, String elementName) throws IOException
{
- String stringContents = readStringContents(element, tagName);
+ String stringContents = readStringContents(element, elementName);
if (stringContents == null) return new Properties();
// JBCACHE-531: escape all backslash characters
stringContents = escapeBackslashes(stringContents);
@@ -190,14 +290,29 @@
return properties;
}
- public static boolean readBooleanContents(Element element, String tagName)
+ /**
+ * Similar to {@link #readStringContents(org.w3c.dom.Element,String)} except that it returns a boolean.
+ *
+ * @param element - element to search through.
+ * @param elementName - name of the element to find within the element passed in
+ * @return the contents of the element as a boolean, or false if not found.
+ */
+ public static boolean readBooleanContents(Element element, String elementName)
{
- return readBooleanContents(element, tagName, false);
+ return readBooleanContents(element, elementName, false);
}
- public static boolean readBooleanContents(Element element, String tagName, boolean defaultValue)
+ /**
+ * Similar to {@link #readStringContents(org.w3c.dom.Element,String)} except that it returns a boolean.
+ *
+ * @param element - element to search through.
+ * @param elementName - name of the element to find within the element passed in
+ * @param defaultValue - value to return if the element is not found or cannot be parsed.
+ * @return the contents of the element as a boolean
+ */
+ public static boolean readBooleanContents(Element element, String elementName, boolean defaultValue)
{
- String val = readStringContents(element, tagName);
+ String val = readStringContents(element, elementName);
if (val.equalsIgnoreCase("true") || val.equalsIgnoreCase("false"))
{
// needs to be done this way because of JBBUILD-351
@@ -207,6 +322,13 @@
return defaultValue;
}
+ /**
+ * Converts a String representing an XML snippet into an {@link org.w3c.dom.Element}.
+ *
+ * @param xml snippet as a string
+ * @return a DOM Element
+ * @throws Exception if unable to parse the String or if it doesn't contain valid XML.
+ */
public static Element stringToElement(String xml) throws Exception
{
ByteArrayInputStream bais = new ByteArrayInputStream(xml.getBytes("utf8"));
@@ -216,9 +338,15 @@
return d.getDocumentElement();
}
+ /**
+ * Returns the root element of a given input stream
+ *
+ * @param is stream to parse
+ * @return XML DOM element, or null if unable to parse stream
+ */
public static Element getDocumentRoot(InputStream is)
{
- Document doc = null;
+ Document doc;
try
{
InputSource xmlInp = new InputSource(is);
@@ -246,16 +374,16 @@
}
/**
- * Retrieves the boolean value of a given attribute for the first encountered instance of a tag in an element.
+ * Retrieves the boolean value of a given attribute for the first encountered instance of elementName
*
- * @param elem
- * @param tagName
- * @param attributeName
- * @param defaultValue
+ * @param elem - element to search
+ * @param elementName - name of element to find
+ * @param attributeName - name of attribute to retrieve the value of
+ * @param defaultValue - default value to return if not found
*/
- public static boolean readBooleanAttribute(Element elem, String tagName, String attributeName, boolean defaultValue)
+ public static boolean readBooleanAttribute(Element elem, String elementName, String attributeName, boolean defaultValue)
{
- String val = getAttributeValue(elem, tagName, attributeName);
+ String val = getAttributeValue(elem, elementName, attributeName);
if (val != null)
{
if (val.equalsIgnoreCase("true") || val.equalsIgnoreCase("false"))
More information about the jboss-cvs-commits
mailing list