Package 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 hierarchically 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

    Modifier and Type
    Method
    Description
    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 Details

    • 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:
      element - the element from which the property should be retrieved
      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:
      element - the element to check
      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 attribute 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:
      element - the element to get the properties for
      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 attribute 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:
      element - the element to set the properties on
      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 attribute 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:
      element - the element to get the properties from
      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:
      element - the element to get the properties from
      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:
      element - the element to set the property on
      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 attribute 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:
      element - the element to delete the property from
      name - the property to delete.