Package org.jivesoftware.util

Class 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 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:
        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 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:
        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 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:
        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 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:
        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 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:
        element - the element to delete the property from
        name - the property to delete.