Package com.ibm.di.entry

Class Entry

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, org.w3c.dom.Document, org.w3c.dom.Node
    Direct Known Subclasses:
    TaskCallBlock
    public class Entry
extends DocImpl
implements java.io.Serializable, java.lang.Cloneable
    The Entry class is a container for attributes and their values. The Entry class is widely used in the IBM Tivoli Directory Integrator. In the scripting environment you use the Entry and Attribute classes by accessing the object's methods.

    JavaScript Examples 

     
 // List all attributes and their values
 var conn = connector.getNextEntry();
 var attrnames = conn.getAttributeNames();
 for (i = 0; i < attrnames.length; i++) {
        var attr = conn.getAttribute(attrnames[i]);
        task.logmsg("Attribute: name = " + attr.getName() + ", #values = " + attr.size());
        for (j = 0; j < attr.size(); j++) {
                task.logmsg("      Value " + j + ": " + attr.getValue(j));
        }
 }
    The Entry could store date using two approaches:
    1. Using the property map:

      • The property map is a standard structure that uses key/value pair to store user's data.

      • Both the key and the value objects could be of any kind since accepted class type is Object.

      • The user could map his/her data (i.e. any subclass of the Object class and the Object class itself) to a String key using the setProperty(Object, Object) method.
        Note: The key could be an instance of the Object type, but its String representation (i.e. Object.toString()) will be used as a key.

      • In order to access the mapped data the user should use the getProperty(Object) method.
        Note: The key Object should result in a unique String otherwise the object that was already mapped will be replaced by the new data when the setProperty(Object, Object) is called! In order to distinguish and retrieve data by the key name the Object.equals(Object) method of the key is used.

      • To get a list of the keys used in the property map use the getPropertyNames() method.
        Starting from IBM Tivoli Directory Integrator 7.0 the properties could be accessed using the .@ notation.
        Note: To use the .@ notation the properties names must be simple, this means that the names should not contain any symbols that have their own meaning in the script's interpretation. In case the name is a complex one use the getProperty(Object) method instead.

    2. Using the Attribute map:

      • This is the most commonly used in IBM Tivoli Directory Integrator key/value pair structure. Each key maps to a value which could be of type Attribute or any user defined subclasses for example.
        Note: There is the limitation that the keys used for identifying the Attribute objects must be unique strings.

      • Starting from IBM Tivoli Directory Integrator 7.0 additional wrapper objects were introduced to handle XML like hierarchical data structures.
        For this purpose the Entry object now implements the Document interface, the Element interface is implemented by the Attribute class, the org.w3c.Attr interface by the Property class, the Text is implemented by the AttributeText class and the CDATASection interface is implemented by the AttributeCDATA class.
        Check out the JavaDoc for each of these new classes for more details.

      • Since IBM Tivoli Directory Integrator 7.0 it is possible to access Entry's Attributes using the dot notation.
        Note: In order to be able to access the Attribute using the dot notation the key name of the Attribute must be a simple one. This means that no characters that are interpret as operators by the JavasSript engine could be used. In the case where the name is a complex one use the old approach - access the Attribute providing the name to the getAttribute(String) method.
    Note: The names of the attributes does not contain namespace information and no such information is interpreted or expected by any of the getAttribute(String), setAttribute(String, Object), getAttributeNames() and getAttributeCollection() methods or any of the other methods using these ones.

    Script Example 

     
   // Access any property using the .@ notation
   var prop = work.@propertyName;
   // here the prop variable will have the value of the property with name propertyName
   
   // Note that properties with names "1propName", "prop#Name", "prop!Name" and so on, could not be accessed using that notation.
   // All of the following will result in an Exception being thrown by the Script Engine.
   var prop = work.@prop.Name;
   var prop = work.@prop!Name;
   // the names shouldn't start with a number either.
   var prop = work.@32443Prop;
   
   // use this approach to get the desired properties
   var prop = work.getProperty("prop.Name");
   prop = work.getProperty("prop!Name");
   prop = work.getProperty("32443Prop");
   
   // You could also create/replace properties like this
   work.@newPropertyName = new java.lang.Object();
   // If there were a property with the name newPropertyName then its value will be replaced.
      
   // Access any Attribute just refer to it using the local name it was mapped under
   var attr = work.attributeName;
   // here the attr variable will point to the Attribute object that was mapped to the key name "attributeName".
   
   // Note that the name after the . should be a simple one in order to access it.
   // Names that have special characters like: attribute-Name or !attribute*Name or 342AttrName are not resolvable.
   // For those kind of names use the entry.getAttribute("complexName"); approach.
    var attr = work.getAttriubte("@Complex346##.Name6");
    
   // You could create/replace Attributes like this:
   work.elementsLocalName = work.createElement("elementsLocalName");
   // This will create new Attribute with local name "elementsLocalName" and will map it under the key name "elementsLocalName".
   
   // Note: if you specify a different name on the left then that name will override the one of the element in the right.
   work.otherName = work.createElement("elementLocalName");
   // You could think of this operation as if this was executed:
   work.setAttribute("otherName", work.createElement("elementsLocalName"));
   // Here the name on the left is set on the Attribute on the right.
   
   // cycle through the Entry's attributes using the for/in loop
   for (var v in work) {
   main.logmsg(v.getName());
   }

    See Also:
    Serialized Form

    • Field Detail

      • OP_ADD

        public static final char OP_ADD
        The Entry contains an entry which is supposed to be added
        See Also:
        Constant Field Values

      • OP_MOD

        public static final char OP_MOD
        The Entry contains an entry which is supposed to be modified
        See Also:
        Constant Field Values

      • OP_DEL

        public static final char OP_DEL
        The Entry contains an entry which is supposed to be removed
        See Also:
        Constant Field Values

      • OP_UNCHANGED

        public static final char OP_UNCHANGED
        The Entry contains an entry which is unchanged
        See Also:
        Constant Field Values

      • OP_GEN

        public static final char OP_GEN
        The Entry contains an entry with no explicit knowledge of operation
        See Also:
        Constant Field Values

      • PATH_SEPARATOR_CHAR

        public static final char PATH_SEPARATOR_CHAR
        This is the character used to separate the simple names in a composite name
        See Also:
        Constant Field Values

      • ESCAPE_CHAR

        public static final char ESCAPE_CHAR
        This is the character used to separate the simple names in a composite name
        See Also:
        Constant Field Values

    • Constructor Detail

      • Entry

        public Entry()
        Construct a new generic flat Entry

      • Entry

        public Entry​(boolean domEnabled)
        Creates a new instance.
        Parameters:
        domEnabled - specifies whether the created entry will be hierarchical or a flat one. If the entry is not required to be hierarchical use false here and it will be made hierarchical on demand if a method from the DOM API is called.

      • Entry

        @Deprecated
public Entry​(java.util.Hashtable table)
        Deprecated.
        will be remove in a future release.
        Construct a new generic Entry, with data given by the provided Hashtable. This is used for internal purposes.
        Parameters:
        table - - a Hashtable representation of the

    • Method Detail

      • clone

        @Deprecated
public Entry clone​(Entry entry)
        Deprecated.
        use the clone() method instead
        Returns an Entry object which is a clone of the Entry parameter. The cloning is shallow which means that only first-level cloning of data values is performed.
        Parameters:
        entry - The Entry object to clone
        Returns:
        The cloned entry

      • clone

        public Entry clone()
        Creates a shallow clone of the receiver. The Hierarchical Attributes contained in the data structures however are complete clones.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a clone of the receiver.
        Since:
        7.0

      • getOp

        public char getOp()
        Returns the operation field of this entry. The operation field signals what should be done with this Entry. See the OP_* codes for possible return values. The field is only set to a meaningful value if the Entry comes from an Iterator with delta enabled.
        Returns:
        This Entry's operation code

      • setOp

        public void setOp​(char operation)
        Sets the operation code for this Entry.
        Parameters:
        operation - The operation code

      • getOperation

        public java.lang.String getOperation()
        Returns the operation field of this Entry. The operation field signals what should be done with this Entry. The method returns either
        OP_ADD2 = "add"; The entry contains an entry which is supposed to be added
        OP_MOD2 = "modify"; The entry contains an entry which is supposed to be modified
        OP_DEL2 = "delete"; The entry contains an entry which is supposed to be removed
        OP_UNCHANGED2 = "unchanged"; The entry contains an entry which is unchanged
        OP_GEN2 = "generic"; The entry contains an entry with no explicit knowledge of operation
        The field is only set to a meaningful value if the entry comes from an Iterator with delta enabled.
        Returns:
        This Entry's operation code as a String

      • setOperation

        public void setOperation​(java.lang.String operation)
        Sets the operation code for this Entry.
        Parameters:
        operation - The operation code as a String

      • set

        public void set​(AttributeInterface attr)
        Deprecated.
        Use setAttribute instead
        Adds or replaces an attribute in this Entry's list of attributes.
        Parameters:
        attr - An Attribute object

      • setAttribute

        @Deprecated
public void setAttribute​(AttributeInterface attr)
        Deprecated.
        will be removed in future releases! Use setAttribute(Attribute) instead.
        Adds or replaces an attribute in this Entry's list of attributes.
        Parameters:
        attr - An Attribute object

      • setAttribute

        public void setAttribute​(Attribute attr)
        Adds or replaces an attribute in this Entry's list of attributes.

        This will replace the attribute already mapped with the same key name (if any).

        Here are examples setting "plain" attributes.

        Example with "plain" attributes: 

         ocAttr = system.newAttribute("objectClass");
 ocAttr.addValue("top");
 ocAttr.addValue("person");
 ocAttr.addValue("organizationalPerson");
 ocAttr.addValue("inetOrgPerson");
 
 modentry.setAttribute(ocAttr);
        If there was an attribute named "objectClass" in the modentry then it would have been replaced by the newly created one.
        Parameters:
        attr - An Attribute object if this parameter is null then the call is ignored.
        Since:
        7.0

      • setAttribute

        @Deprecated
public void setAttribute​(java.lang.Object name,
                         java.lang.Object value)
        Deprecated.
        use setAttribute(String, Object) instead.
        Adds or replaces an attribute in this Entry's list of attributes.
        Parameters:
        name - The attribute name
        value - The attribute value. If this parameter is null, then the attribute is removed.

      • setAttribute

        public void setAttribute​(java.lang.String name,
                         java.lang.Object value)
        Adds or replaces an attribute in this Entry's list of attributes.
        Note: This method will set/override the name of the Attribute to the name.toString() value in the cases when the second argument is an Attribute object.
        Parameters:
        name - The name of the Attribute to use as a key name for the mapping. If null the call is ignored.
        value - The attribute value. If this parameter is null, then the attribute is removed.
        Since:
        7.0
        See Also:
        setAttribute(Attribute)

      • setAttribute

        @Deprecated
public void setAttribute​(java.lang.Object name,
                         java.lang.Object value,
                         boolean protect)
        Deprecated.
        use setAttribute(String, Object, boolean) instead.
        Adds or replaces an attribute in this Entry's list of attributes.
        Parameters:
        name - The attribute name
        value - The attribute value. If this parameter is null, then the attribute is removed.
        protect - If this parameter is true, do not dump the Attribute values in log files

      • setAttribute

        public void setAttribute​(java.lang.String name,
                         java.lang.Object value,
                         boolean protect)
        Calls setAttribute(String, Object) but additionally uses the protect argument to set the attribute as protected or not. Note that the protection is set only on the attribute's level for a deep protection use: 
         work.getAttribute(name).setProtected(true, true);
        Parameters:
        name - The name of the Attribute to use as a key name for the mapping.
        value - The attribute value. If this parameter is null, then the attribute is removed.
        protect - If this parameter is true, do not dump the Attribute's values in the log files.
        Since:
        7.0
        See Also:
        setAttribute(String, Object)

      • setAttributeValues

        public void setAttributeValues​(java.lang.String name,
                               java.lang.Object values)
        This method creates a new attribute with the specified name and values and add it to the entry. If the values parameter is an Attribute then that Attribute's values are added to the new Attribute. If the values parameter is a List then its elements are added as values to the new Attribute. If any of the elements are Attributes then the values of those attributes are also added to the new Attribute, the element attributes however are not.
        Parameters:
        name - The name of the Attribute to use as a key name for the mapping.
        values - The attribute values. If this parameter is null, then the attribute is removed.
        Since:
        7.0
        See Also:
        setAttribute(Attribute)

      • newAttribute

        public Attribute newAttribute​(java.lang.String name)
        This method is used to find/create an Attribute in the entry using the specified name.

        This method accepts a name in the form "a.b.c.d" and tries to resolve this composite name in the receiver's tree. The composite name is broken down to pieces which tells the method how to navigate the hierarchy.

        For example if we have the following hierarchy: 
         Entry
  |---a
      |---b
      |   |---c
      |
      |---b
          |---c
              |---d
        Then the method will start from the root (the Entry) and will firstly search for an Attribute called a. If the Attribute on the entry level does not exists it is automatically created and added to the entry. Then a search for a child of a with the name b is made. If that child is not found then it is created as well. In our case the first c is found on the next step and then searched for a child named d. No such child is found and therefore it is created.

        Once all the paths are resolved the method will return the last Attribute resolved/created. To navigate to the top you could use the NodeImpl.getParentNode().

        The method is able to work with single names e.g. "a" or "pref:a" which will be looked up in the entry and if not found will be automatically created.

        Note: The character "." is used as a separator. To escape it use "\.". To escape the escape char - "\" - use "\\".

        Parameters:
        name - the composite of names to use when creating/navigating the Attributes chain.
        Returns:
        a reference to the last Attribute retrieved/created in the process of resolving the specified name.
        Since:
        7.0

      • newAttribute

        public Attribute newAttribute​(java.lang.String name,
                              char oper)
        Returns an Attribute object from this entry's list of attributes. If the attribute does not exist, a new one is created with no values.
        Parameters:
        name - The attribute name to create/return
        oper - The new Attribute's operation code. Only used if creating a new Attribute.
        Returns:
        The Attribute object

      • addAttributeValue

        @Deprecated
public void addAttributeValue​(java.lang.Object name,
                              java.lang.Object value)
        Deprecated.
        use addAttributeValue(String, Object) instead.
        Adds a value to an attribute. If the attribute does not exist it is created with the new value. If the attribute exists, the value is appended to the attribute's list of values. If the value Object is an Attribute, you may wish to use mergeAttributeValue instead, to get the values of the Attribute added instead of the Attribute itself as a value.
        Parameters:
        name - The attribute name
        value - The value to append

      • addAttributeValue

        public void addAttributeValue​(java.lang.String name,
                              java.lang.Object value)
        Adds a value to an attribute. If the attribute does not exist it is created with the new value. If the attribute exists, the value is appended to the attribute's list of values. If the value Object is an Attribute, you may wish to use mergeAttributeValue instead, to get the values of the Attribute added instead of the Attribute itself as a value.
        Parameters:
        name - The attribute name
        value - The value to append
        Since:
        7.0

      • addAttributeValue

        @Deprecated
public void addAttributeValue​(java.lang.Object name,
                              java.lang.Object value,
                              int op)
        Deprecated.
        use addAttributeValue(String, Object, int) instead.
        Adds a value to an attribute. If the attribute does not exist it is created with the new value. If the attribute exists, the value is appended to the attribute's list of values.
        Parameters:
        name - The attribute name
        value - The value to append
        op - The attribute value operation, AV_UNCHANGED = 0, AV_ADD = 1, AV_DELETE = 2

      • addAttributeValue

        public void addAttributeValue​(java.lang.String name,
                              java.lang.Object value,
                              int op)
        Adds a value to an attribute. If the attribute does not exist it is created with the new value. If the attribute exists, the value is appended to the attribute's list of values.
        Parameters:
        name - The attribute name
        value - The value to append
        op - The attribute value operation, AV_UNCHANGED = 0, AV_ADD = 1, AV_DELETE = 2
        Since:
        7.0

      • mergeAttributeValue

        @Deprecated
public void mergeAttributeValue​(java.lang.Object name,
                                AttributeInterface attr)
        Deprecated.
        use mergeAttributeValue(String, Attribute) instead.
        Merges the values in one attribute with the values from another attribute. All values from attr are added, even if they already exist.
        Parameters:
        name - The name of the attribute into which values are merged
        attr - The attribute (e.g. entry.getAttribute("xxx")) from which values are collected

      • mergeAttributeValue

        public void mergeAttributeValue​(java.lang.String name,
                                Attribute attr)
        Merges the values in one attribute with the values from another attribute. All values from attr are added, even if they already exist.
        If the given Attribute is marked as protected then the result Attribute will be protected as well.
        Parameters:
        name - The name of the attribute into which values are merged. If this parameter is null the call is ignored.
        attr - The attribute (e.g. entry.getAttribute("xxx")) from which values are collected.
        Since:
        7.0

      • mergeAttributeValue

        public void mergeAttributeValue​(Attribute attr)
        Merges in the values from an attribute. All values from attr are added, even if they already exist. The name of attr will be used to determine which Attribute should get the new values.
        Parameters:
        attr - The attribute (e.g. entry.getAttribute("xxx")) from which we get the name and values

      • get

        @Deprecated
public Attribute get​(java.lang.Object p1)
        Deprecated.
        use getAttribute(String) instead.
        Returns the Attribute object for a named attribute.
        Parameters:
        p1 - The attribute name
        Returns:
        The Attribute object or null if the attribute does not exist

      • getAttribute

        @Deprecated
public Attribute getAttribute​(java.lang.Object p1)
        Deprecated.
        use getAttribute(String) instead.
        Returns the Attribute object for a named attribute.
        Parameters:
        p1 - The attribute name
        Returns:
        The Attribute object or null if the attribute does not exist

      • getAttribute

        public Attribute getAttribute​(java.lang.String name)
        Returns the Attribute object for a named attribute.
        Parameters:
        name - The attribute name
        Returns:
        The Attribute object or null if the attribute does not exist
        Since:
        7.0

      • getAttributeNames

        public java.lang.String[] getAttributeNames()
        Returns an array of strings containing attribute names in this entry.
        Returns:
        The attribute names in this entry as an array

      • getAttributeCollection

        public java.util.Collection<java.lang.String> getAttributeCollection()
        Returns a java.util.Collection containing attribute names in this entry.
        Returns:
        The attribute names in this entry as a java.util.Collection object

      • getString

        @Deprecated
public java.lang.String getString​(java.lang.Object p1)
        Deprecated.
        use getString(String) instead.
        Returns the first value in an attribute as a String. If the attribute does not exist or the attribute does not have any values then null is returned.
        Parameters:
        p1 - The attribute name
        Returns:
        The string value or null

      • getString

        public java.lang.String getString​(java.lang.String p1)
        Returns the first value in an attribute as a String. If the attribute does not exist or the attribute does not have any values then null is returned.
        Parameters:
        p1 - The attribute name
        Returns:
        The string value or null
        Since:
        7.0

      • getObject

        @Deprecated
public java.lang.Object getObject​(java.lang.Object p1)
        Deprecated.
        use getObject(String) instead.
        Returns the first value in an attribute as an object. If the attribute does not exist or the attribute does not have any values then null is returned.
        Parameters:
        p1 - The attribute name
        Returns:
        The object value or null

      • getObject

        public java.lang.Object getObject​(java.lang.String p1)
        Returns the first value in an attribute as an object. If the attribute does not exist or the attribute does not have any values then null is returned.
        Parameters:
        p1 - The attribute name
        Returns:
        The object value or null
        Since:
        7.0

      • removeAttribute

        @Deprecated
public void removeAttribute​(java.lang.Object p1)
        Deprecated.
        use removeAttribute(String) instead.
        Removes an attribute from this Entry's list of attribute.
        Parameters:
        p1 - The name of the attribute to remove

      • removeAttribute

        public void removeAttribute​(java.lang.String name)
        Removes an attribute from this Entry's list of attributes.
        This method removes only the first attribute that could be accessed by the getAttribute(String) method. If there is another attribute which is not mapped to this Entry it will not be removed by a subsequent call. To remove such Attributes use the provided DOM API.

        Note: When this entry is using a DOM tree the removal of a value which is a parent of another attribute (e.g. calling entry.removeAttribute("first.second"); when there is an attribute called "first.second.third") will not really remove that attribute from the tree. That attribute will only be cleared. This is done for optimization reasons. Once removed that attribute will not show in the array returned by getAttributeNames() method. However that Attribute will still be accessible through the DOM API.
        Parameters:
        name - The name of the attribute to remove

      • removeAllAttributes

        public void removeAllAttributes()
        Removes all attributes from this Entry.

      • size

        public int size()
        Returns the number of attributes present in this entry.
        Returns:
        Number of attributes contained in this entry

      • toString

        public java.lang.String toString()
        Returns a string representation of this entry.
        Overrides:
        toString in class java.lang.Object
        Returns:
        All attribute names and values as a structured string

      • toDeltaString

        public java.lang.String toDeltaString()
        Returns a string representation of this entry, including delta information.
        Returns:
        All attribute names and values as a structured string, and also delta information if present.

      • getProperty

        @Deprecated
public java.lang.Object getProperty​(java.lang.Object propertyName)
        Deprecated.
        use getProperty(String) instead.
        Returns a property value.
        Parameters:
        propertyName - The name of the property
        Returns:
        The property's value or null if no such property exists

      • getProperty

        public java.lang.Object getProperty​(java.lang.String propertyName)
        Returns a property value.
        Parameters:
        propertyName - The name of the property
        Returns:
        The property's value or null if no such property exists
        Since:
        7.0

      • setProperty

        @Deprecated
public void setProperty​(java.lang.Object propertyName,
                        java.lang.Object propertyValue)
        Deprecated.
        use setProperty(String, Object) insetad.
        Sets/replaces a property.
        Parameters:
        propertyName - The name of the property
        propertyValue - The named property's value

      • setProperty

        public void setProperty​(java.lang.String propertyName,
                        java.lang.Object propertyValue)
        Sets/replaces a property.
        Parameters:
        propertyName - The name of the property
        propertyValue - The named property's value
        Since:
        7.0

      • hasProperty

        public boolean hasProperty​(java.lang.String propertyName)
        Returns true if a property named by the propertyName parameter has a value.
        Returns:
        True if such property exists

      • getPropertyNames

        public java.lang.String[] getPropertyNames()
        Returns a string array of the property names contained in this entry.
        Returns:
        Array of strings with property names

      • merge

        public void merge​(Entry e)
        Convenience method that calls merge ( e, false ).
        Parameters:
        e - The entry from which attributes are collected

      • merge

        public void merge​(Entry e,
                  boolean mergevalues)
        Merges in the attributes and their values from another entry. After the operation this entry contains all the attributes combined. For attributes with the same name, the result will be the attributes from the other entry if mergevalues is false. Properties are copied from the e entry and overwrite any existing properties.

        Example: This entry contains these attributes Name Values a 1 b 1, 2 The other entry contains these attributes Name Values b 3 c 4 After the merge, mergevalues=FALSE, this entry will contain Name Values a 1 b 3 c 4 After the merge, mergevalues=TRUE, this entry will contain Name Values a 1 b 1, 2, 3 c 4

        Parameters:
        e - The entry from which attributes are collected
        mergevalues - if false replace values, if true add values

      • invalidateNamesList

        protected void invalidateNamesList()
        Raises the flag that means the tree have been updated to tell the Entry to clear its catches.
        Since:
        7.0

      • isDOMEnabled

        public boolean isDOMEnabled()
        Returns:
        true if this entry is storing the information as DOM tree. If the entry has a pre 7.0 flat structure this method returns false.

      • enableDOM

        public void enableDOM()
        This method changes the entry from pre 7.0 flat structure to a hierarchical one. This method could only be called once, after that calling this method will have no impact on the entry's structure. This method is called implicitly when one of the tree/hierarchy related DOM APIs are called (e.g. getChildNodes().

      • getNodeList

        public org.w3c.dom.NodeList getNodeList​(java.lang.String xPath)
                                 throws javax.xml.xpath.XPathExpressionException
        Execute an XPath expression and get the result as an NodeList
        Parameters:
        xPath - the XPath expression
        Returns:
        All the nodes found by the XPath engine.
        Throws:
        javax.xml.xpath.XPathExpressionException - in case an invalid expression is passed
        Since:
        7.0

      • getFirstAttribute

        public Attribute getFirstAttribute​(java.lang.String xPath)
                            throws javax.xml.xpath.XPathExpressionException
        Execute an XPath expression and get the result as an Attribite *
        Parameters:
        xPath - the XPath expression
        Returns:
        the first Node out of all the nodes found
        Throws:
        javax.xml.xpath.XPathExpressionException - in case an invalid expression is passed
        Since:
        7.0

      • getStringValue

        public java.lang.String getStringValue​(java.lang.String xPath)
                                throws javax.xml.xpath.XPathExpressionException
        Execute an XPath expression and get the result as an String *
        Parameters:
        xPath - the XPath expression
        Returns:
        The result as String
        Throws:
        javax.xml.xpath.XPathExpressionException - in case an invalid expression is passed
        Since:
        7.0

      • getNumberValue

        public java.lang.Number getNumberValue​(java.lang.String xPath)
                                throws javax.xml.xpath.XPathExpressionException
        Execute an XPath expression and get the result as an Number *
        Parameters:
        xPath - the XPath expression
        Returns:
        The result as Number
        Throws:
        javax.xml.xpath.XPathExpressionException - in case an invalid expression is passed
        Since:
        7.0

      • getBooleanValue

        public java.lang.Boolean getBooleanValue​(java.lang.String xPath)
                                  throws javax.xml.xpath.XPathExpressionException
        Execute an XPath expression and get the result as an Boolean *
        Parameters:
        xPath - the XPath expression
        Returns:
        The result as Boolean
        Throws:
        javax.xml.xpath.XPathExpressionException - in case an invalid expression is passed
        Since:
        7.0

      • toXML

        public java.lang.String toXML()
                       throws java.lang.Exception
        Returns a XML representation of this Entry object. Note: if the Entry contains multiple attributes then the resultant XML will be multi-rooted.
        Returns:
        the XML String.
        Throws:
        java.lang.Exception - if an error occurs
        Since:
        7.0

      • fromXML

        public static Entry fromXML​(java.lang.String string,
                            java.lang.String xPath,
                            java.lang.String entryTag)
                     throws java.lang.Exception
        Returns an Entry object constructed from a XML String.
        Parameters:
        string - The XML String used to construct the new Entry
        xPath - Sets the simple XPath expression used to find entries.
        entryTag - The name of the element which wraps each Entry.
        Returns:
        the new Entry.
        Throws:
        java.lang.Exception - if an error occurs during parsing
        Since:
        7.2

      • toJSON

        public java.lang.String toJSON()
                        throws java.lang.Exception
        Returns a JSON representation of this Entry object.
        Returns:
        the JSON String.
        Throws:
        java.lang.Exception - if an error occur
        Since:
        7.2

      • fromJSON

        public static Entry fromJSON​(java.lang.String string)
                      throws java.lang.Exception
        Returns an Entry constructed from a JSON string
        Parameters:
        string - The JSON string used to set values in the new Entry.
        Returns:
        The new Entry
        Throws:
        java.lang.Exception - if an error occurs during parsing
        Since:
        7.2

      • adoptNode

        public org.w3c.dom.Node adoptNode​(org.w3c.dom.Node source)
                           throws DOMException
        This method adopts the provided as parameter Node by setting its parent to null and setting the document reference to this entry object. When this method is called the Node is not being added to the Entry, it will only point to the Entry as its Document. The node will be detached by its parent before this method completes. Does not make the Entry hierarchical.
        Specified by:
        adoptNode in interface org.w3c.dom.Document
        Parameters:
        source - the Node which parents to change.
        Returns:
        The same Node but with changed parent and document references.
        Throws:
        DOMException - in case the Node is not an instance of the NodeImpl class.
        Since:
        7.0

      • createAttribute

        public Property createAttribute​(java.lang.String name)
                         throws DOMException
        This method creates a new Property object that represents an element's attribute in terms of DOM concepts. The namespace of that property will be set to null.

        This method implements org.w3c.dom.Document's createAttribute method and only creates a new Property but not set it on an Attribute object. This means that until you call Attribute.setAttributeNode(Attr) with the newly created Property object it will not be visible trough Attribute's methods like getAttribute(String), getAttributes(), etc.

        Example: 

         var entry = system.newEntry();
 var hattr1 = entry.createElement("mother");
 entry.appendChild(hattr1);
 
 var attr = entry.createAttribute("name");
 var attr1 = entry.createAttribute("age");
 var attr2 = entry.createAttribute("work");
 
 attr1.setValue("33");
 attr2.setValue("IBM Corporation");
 attr.setValue("Marina");
 
 hattr1.setAttributeNode(attr1);
 hattr1.setAttributeNode(attr2);
 
 //if we call hattr1.toString(); attribute 'name' will not be displayed
        Does not make the Entry hierarchical.
        Specified by:
        createAttribute in interface org.w3c.dom.Document
        Parameters:
        name - - the name of the new Property
        Returns:
        the new Property object
        Throws:
        DOMException - - in case an error occurs while creating the Property
        Since:
        7.0
        See Also:
        createAttributeNS(String, String)

      • createAttributeNS

        public Property createAttributeNS​(java.lang.String namespaceURI,
                                  java.lang.String qualifiedName)
                           throws DOMException
        This method creates new Property object that represents an element's attribute in terms of XML concepts. The created Property object has the following attributes: nodeName: qualifiedName, namespaceURI: namespaceURI and nodeValue: null.

        This method implements org.w3c.dom.Document's createAttributeNS method and only creates a new Property but not set it on Attribute object. This means that until you call Attribute.setAttributeNode(Attr) with the newly created Property object it will not be visible trough the Attribute's methods like getAttribute(String), getAttributes(), etc.

        Example: 

         
 var entry = system.newEntry();
 var hattr1 = entry.createElement("mother");
 var hattr2 = entry.createElement("son");
 entry.appendChild(hattr1);
 entry.appendChild(hattr2);
 
 var attr = entry.createAttribute("general", "name");
 var attr1 = entry.createAttribute("personal", "age");
 var attr2 = entry.createAttributeNS("occupation", "work");
 
 attr.setValue("Marina");
 attr1.setValue("33");
 attr2.setValue("IBM Corporation");
 
 hattr1.setAttributeNode(attr1);
 hattr1.setAttributeNode(attr2);
 
 //if we call hattr1.toString() attribute 'name' will not be displayed
        Does not make the Entry hierarchical.
        Specified by:
        createAttributeNS in interface org.w3c.dom.Document
        Parameters:
        namespaceURI - - the namespace this Property belongs to
        qualifiedName - - the name of the new Property, this could be in the format prefix:localName
        Returns:
        the new Property object
        Throws:
        DOMException - - in case an error occurs while creating the Property
        Since:
        7.0

      • createElement

        public Attribute createElement​(java.lang.String tagName)
                        throws DOMException
        This method creates new Attribute object that represents an element in terms of XML concepts. The namespace of this Attribute will be set to null.

        Example: 

         
 var entry = system.newEntry();
 entry.setAttribute("type", "family");
 
 var hattr1 = entry.createElement("mother");
 var hattr2 = entry.createElement("daughter");
 var hattr3 = entry.createElement("son");
 
 hattr1.appendChild(hattr2);
 hattr1.appendChild(hattr3);
 
 entry.appendChild(hattr1);
 task.dumpEntry(entry);
        Does not make the Entry hierarchical.
        Specified by:
        createElement in interface org.w3c.dom.Document
        Parameters:
        tagName - - the name this Attribute will have, any special characters will be escaped prior to creating the Attribute.
        Returns:
        the new Attribute object
        Throws:
        DOMException - - in case an error occurs while creating the Attribute
        Since:
        7.0

      • createElementNS

        public Attribute createElementNS​(java.lang.String namespaceURI,
                                 java.lang.String qualifiedName)
                          throws DOMException
        This method creates new Attribute object that represents an element in terms of XML concepts.

        Here is an example of how to create elements with specified namespace, add them to some entry as children and print the results.

        Example: 

         
 var entry = system.newEntry();
 
 var hattr1 = entry.createElementNS("adult",
 "mother"); var hattr2 =
 entry.createElementNS("youth", "daughter"); var
 hattr3 = entry.createElementNS("youth", "son");
 
 entry.appendChild(hattr1); entry.appendChild(hattr2);
 entry.appendChild(hattr3);
 
 var list = entry.getChildNodes();
 
 for (i = 0; i < list.getLength(); i++) { task.logmsg("\tName:
 " + list.item(i).getNodeName()); task.logmsg("\tNS: " +
 list.item(i).getNamespaceURI()); }
        Does not make the Entry hierarchical.
        Specified by:
        createElementNS in interface org.w3c.dom.Document
        Parameters:
        namespaceURI - - the namespace this element will belong to
        qualifiedName - - the name of the new Attribute, this could be in the format prefix:localName. Any special characters will be escaped prior to creating the Attribute.
        Returns:
        the new Attribute object
        Throws:
        DOMException - - in case an error occurs while creating the Attribute
        Since:
        7.0

      • createCDATASection

        public org.w3c.dom.CDATASection createCDATASection​(java.lang.String data)
                                            throws DOMException
        Creates new AttributeCDATA object that represents a CDATASection in terms of XML concepts. Does not make the Entry hierarchical.
        Specified by:
        createCDATASection in interface org.w3c.dom.Document
        Parameters:
        data - - the data this AttributeCDATA will contain
        Returns:
        the new AttributeCDATA object
        Throws:
        DOMException - - in case an error occurs while creating the AttributeCDATA
        Since:
        7.0

      • createTextNode

        public org.w3c.dom.Text createTextNode​(java.lang.String data)
        Creates new AttributeText object that represents a Text section in terms of XML concepts. Does not make the Entry hierarchical.
        Specified by:
        createTextNode in interface org.w3c.dom.Document
        Parameters:
        data - - the data this AttributeText will contain
        Returns:
        the new AttributeText object
        Since:
        7.0

      • getDocumentElement

        public Attribute getDocumentElement()
        Specified by:
        getDocumentElement in interface org.w3c.dom.Document
        Returns:
        The first (by the order the attributes were entered) Attribute in the entry (if any, otherwise null)
        Since:
        7.0

      • getElementsByTagName

        public org.w3c.dom.NodeList getElementsByTagName​(java.lang.String tagname)
        Recursively searches for children with the specified tag name.
        Specified by:
        getElementsByTagName in interface org.w3c.dom.Document
        Parameters:
        tagname - - the search criteria
        Returns:
        NodeList object which holds all the matching children
        Since:
        7.0

      • getElementsByTagNameNS

        public org.w3c.dom.NodeList getElementsByTagNameNS​(java.lang.String namespaceURI,
                                                   java.lang.String localName)
        Recursively searches for children that belong to the specified namespaceURI and have the specific localName.
        Specified by:
        getElementsByTagNameNS in interface org.w3c.dom.Document
        Parameters:
        namespaceURI - - the namespace the child should belong to
        localName - - the name the child should have
        Returns:
        NodeList object which holds all the matching children
        Since:
        7.0

      • renameNode

        public org.w3c.dom.Node renameNode​(org.w3c.dom.Node n,
                                   java.lang.String namespaceURI,
                                   java.lang.String qualifiedName)
                            throws DOMException
        Renames the node. If the passed Attribute is already added to this entry a check for another Attribute with the specified qualifiedName will be made. If such an Attribute is found it will be replace by the renamed Attribute. Note that the renamed Attribute will be accessible from the entry by the localName passed as parameter of this method.
        If a Property is passed then a check for an existing Property is done. If one is found then it is replaced otherwise the property is just renamed. The namespaceURI parameter is not considered when passing a Property. To change the namespace of this Property you must use the qualifiedName and set the appropriate prefix. Note that the prefix must be already defined either implicitly on an Attribute level or explicitly as another Property.
        Specified by:
        renameNode in interface org.w3c.dom.Document
        Parameters:
        n - - this methods accepts objects of type Attribute or type Property
        namespaceURI - - the new namespace that should be set
        qualifiedName - - the new name this node should have, this name is the one that later will be returned by Node.getNodeName()
        Returns:
        the same node with changed namespace and qualifiedName
        Throws:
        DOMException - if the n object is not of type Attribute or Property. If the n object is a Property but the specified prefix has not been declared previously.
        Since:
        7.0

      • appendChild

        public Attribute appendChild​(org.w3c.dom.Node newChild)
                      throws DOMException
        This will add the provided Attribute in the entry using the localName of that Attribute for a key name. If that key name already exists in the map then an exception will be thrown.
        Use the setAttribute(String, Object) method instead if you want to force a replacement of the existing Attribute. Example: 
         
 var entry = system.newEntry();
 entry.setAttribute("type", "family");
 
 var hattr1 = entry.createElement("mother");
 var hattr2 = entry.createElement("daughter");
 var hattr3 = entry.createElement("son");
 
 hattr1.appendChild(hattr1);
 hattr1.appendChild(hattr2);
 hattr1.appendChild(hattr3);
 
 entry.appendChild(hattr1);
 
 task.dumpEntry(entry);
        Specified by:
        appendChild in interface org.w3c.dom.Node
        Parameters:
        newChild - - Object that is an instance of the Attribute class. This object will be added in the Entry if its local name does not already exist in the key names set.
        Returns:
        the appended Attribute
        Throws:
        DOMException - - in case the newChild parameter is not an instance of the Attribute class or if an Attribute is already mapped with that key name.
        Since:
        7.0

      • getChildNodes

        public org.w3c.dom.NodeList getChildNodes()
        Returns list of all children of the specified Node;

        Here is an example of how to print entry's all children name and NS.

        Example: 

         
 var list = entry.getChildNodes();
 
 for (i = 0; i < list.getLength(); i++) {
        task.logmsg("\tName: " + list.item(i).getNodeName());
        task.logmsg("\tNS: " + list.item(i).getNamespaceURI());
 }
 
 task.dumpEntry(entry);
        Specified by:
        getChildNodes in interface org.w3c.dom.Node
        Returns:
        an immutable NodeList object. Adding an element to the list will not make the element a child of the current Document.
        Since:
        7.0

      • getFirstChild

        public Attribute getFirstChild()
        Retrieves the first child, that is, the first Attribute object inserted in the Entry
        Specified by:
        getFirstChild in interface org.w3c.dom.Node
        Returns:
        the first child.
        Since:
        7.0

      • getLastChild

        public Attribute getLastChild()
        Retrieves the last child, that is, the last Attribute object inserted in the Entry
        Specified by:
        getLastChild in interface org.w3c.dom.Node
        Returns:
        the last child
        Since:
        7.0

      • hasChildNodes

        public boolean hasChildNodes()
        Specified by:
        hasChildNodes in interface org.w3c.dom.Node
        Returns:
        true if the Entry has Attribute children, false otherwise
        Since:
        7.0

      • insertBefore

        public Attribute insertBefore​(org.w3c.dom.Node newChild,
                              org.w3c.dom.Node refChild)
                       throws DOMException
        If the refChild is not presented in the entry structure or is null then the newChild will be appended to the end. This method will replace any existing Attribute that are already mapped under a name which is equal to newChild's localName.
        Specified by:
        insertBefore in interface org.w3c.dom.Node
        Parameters:
        newChild - the Attribute that is going to be inserted
        refChild - the Attribute which position will shift down
        Returns:
        the Attribute which was just added before the refChild
        Throws:
        DOMException - if the newChild and the refChild are not Attribute instances
        Since:
        7.0

      • removeChild

        public Attribute removeChild​(org.w3c.dom.Node oldChild)
                      throws DOMException
        This method will remove the provided Attribute from the Entry.
        Specified by:
        removeChild in interface org.w3c.dom.Node
        Parameters:
        oldChild - - the Attribute that should be removed from the entry object
        Returns:
        - the same Attribute passed as parameter if it was found in the Entry or null if that Attribute could not be found.
        Throws:
        DOMException - if the oldChild is not an instance of Attribute
        Since:
        7.0
        See Also:
        #removeAttribute(boolean, String)

      • replaceChild

        public Attribute replaceChild​(org.w3c.dom.Node newChild,
                              org.w3c.dom.Node oldChild)
                       throws DOMException
        This method will search the entry structure for the oldChild and will replace it with the newChild.
        Specified by:
        replaceChild in interface org.w3c.dom.Node
        Parameters:
        newChild - the Attribute that is going to be added
        oldChild - the Attribute which will be removed
        Returns:
        the oldChild that was successfully removed or null if that child was not found.
        Throws:
        DOMException - if both of the parameters are not instances of the Attribute class
        Since:
        7.0

      • isEqualNode

        public boolean isEqualNode​(org.w3c.dom.Node other)
        Specified by:
        isEqualNode in interface org.w3c.dom.Node

      • cloneNode

        public Entry cloneNode​(boolean deep)
        Clones this entry object
        Specified by:
        cloneNode in interface org.w3c.dom.Node
        Parameters:
        deep - if true a complete clone of the tree will be created (the values are not cloned!). If false is specified the Attributes of this entry are not cloned.
        Returns:
        the clone object.