org.jivesoftware.util
Class ElementUtil

java.lang.Object
  org.jivesoftware.util.ElementUtil

public class ElementUtil
extends Object

We use a simple naming convention of meta-data key names: data is stored heirarchically separated by dots. The last name may contain a colon ':' character that is read as name:attribute. For example setting X.Y.Z to someValue, would map to an XML snippet of:

 <X>
     <Y>
         <Z>someValue</Z>
     </Y>
 </X>
 

And X.Y.Z:key to anotherValue as:

 <X>
     <Y>
         <Z key="anotherValue" />
     </Y>
 </X>
 

Some XML cannot be built or accessed using this naming convention (e.g. a typical Roster reset packet). More complex XML packet should be represented using the XMPPDOMFragment. The Element class is designed to provide 80% of XML manipulation capabilities with the simplest 20% of code and API size making it convenient for meta-data, simple IQ packets, etc.

Method Summary

static void	deleteProperty(org.dom4j.Element element, String name) Deletes the specified property.
static String[]	getChildrenProperties(org.dom4j.Element element, String parent) Return all children property names of a parent property as a String array, or an empty array if the if there are no children.
String[]	getProperties(org.dom4j.Element element, String name) Return all values who's path matches the given property name as a String array, or an empty array if the if there are no children.
static String	getProperty(org.dom4j.Element element, String name) Returns the value of the specified property.
static String[]	getRecursiveChildrenProperties(org.dom4j.Element element, String parent) Returns all recursive children of the given parent property or an empty string array if no children exist.
static boolean	includesProperty(org.dom4j.Element element, String name) Returns true if the specified property is included in the XML hierarchy.
static void	setProperties(org.dom4j.Element element, String name, String[] values) Sets a property to an array of values.
static void	setProperty(org.dom4j.Element element, String name, String value) Sets the value of the specified property.

Methods inherited from class java.lang.Object

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

Method Detail

getProperty

public static String getProperty(org.dom4j.Element element,
                                 String name)

Returns the value of the specified property. A null answer does not necessarily mean that the property does not exist.

Parameters:

name - the name of the property to get.

Returns:

the value of the specified property.

includesProperty

public static boolean includesProperty(org.dom4j.Element element,
                                       String name)

Returns true if the specified property is included in the XML hierarchy. A property could have a value associated or not. If the property has an associated value then

Parameters:

name - the name of the property to find out.

Returns:

true if the specified property is included in the XML hierarchy.

getProperties

public String[] getProperties(org.dom4j.Element element,
                              String name)

Return all values who's path matches the given property name as a String array, or an empty array if the if there are no children. You MAY NOT use the atttribute markup (using a ':' in the last element name) with this call.

getProperties() allows you to retrieve several values with the same property name. For example, consider the XML file entry:

 <foo>
     <bar>
         <prop>some value</prop>
         <prop>other value</prop>
         <prop>last value</prop>
     </bar>
 </foo>
 

If you call getProperties("foo.bar.prop") will return a string array containing {"some value", "other value", "last value"}.

Parameters:

name - the name of the property to retrieve

Returns:

all child property values for the given node name.

setProperties

public static void setProperties(org.dom4j.Element element,
                                 String name,
                                 String[] values)

Sets a property to an array of values. You MAY NOT use the atttribute markup (using a ':' in the last element name) with this call. Multiple values matching the same property is mapped to an XML file as multiple elements containing each value. For example, using the name "foo.bar.prop", and the value string array containing {"some value", "other value", "last value"} would produce the following XML:

 <foo>
     <bar>
         <prop>some value</prop>
         <prop>other value</prop>
         <prop>last value</prop>
     </bar>
 </foo>
 

Parameters:

name - the name of the property.

values - The array of values for the property (can be empty but not null)

getChildrenProperties

public static String[] getChildrenProperties(org.dom4j.Element element,
                                             String parent)

Return all children property names of a parent property as a String array, or an empty array if the if there are no children. You MAY NOT use the atttribute markup (using a ':' in the last element name) with this call. For example, given the properties X.Y.A, X.Y.B, and X.Y.C, then the child properties of X.Y are A, B, and C.

Parameters:

parent - the name of the parent property.

Returns:

all child property values for the given parent.

getRecursiveChildrenProperties

public static String[] getRecursiveChildrenProperties(org.dom4j.Element element,
                                                      String parent)

Returns all recursive children of the given parent property or an empty string array if no children exist. The list of children is depth-first so the array is optimized for easy displaying.

Parameters:

parent - the parent property.

Returns:

all recursive children of the given property in depth-first order or an empty string array if no children exist.

setProperty

public static void setProperty(org.dom4j.Element element,
                               String name,
                               String value)

Sets the value of the specified property. If the property doesn't currently exist, it will be automatically created.

Parameters:

name - the name of the property to set.

value - the new value for the property.

deleteProperty

public static void deleteProperty(org.dom4j.Element element,
                                  String name)

Deletes the specified property.

You MAY NOT use the atttribute markup (using a ':' in the last element name) with this call. deleteProperty() removes both the containing text, and the element itself along with any attributes associated with that element.

Parameters:

name - the property to delete.