com.ibm.di.entry
Class Entry

java.lang.Object
  extended by com.ibm.di.entry.DocImpl
      extended by com.ibm.di.entry.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:


  2. Using the Attribute map:

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 Summary
static char ESCAPE_CHAR
          This is the character used to separate the simple names in a composite name
static char OP_ADD
          The Entry contains an entry which is supposed to be added
static java.lang.String OP_ADD2
          String representation of the OP_ADD field.
static char OP_DEL
          The Entry contains an entry which is supposed to be removed
static java.lang.String OP_DEL2
          String representation of the OP_DEL field.
static char OP_GEN
          The Entry contains an entry with no explicit knowledge of operation
static java.lang.String OP_GEN2
          String representation of the OP_GEN field.
static char OP_MOD
          The Entry contains an entry which is supposed to be modified
static java.lang.String OP_MOD2
          String representation of the OP_MOD field.
static char OP_UNCHANGED
          The Entry contains an entry which is unchanged
static java.lang.String OP_UNCHANGED2
          String representation of the OP_UNCHANGED field.
static char PATH_SEPARATOR_CHAR
          This is the character used to separate the simple names in a composite name
static java.lang.String PATH_SEPARATOR_STR
          This is the string representing the PATH_SEPARATOR_CHAR field.
 
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
 
Constructor Summary
Entry()
          Construct a new generic flat Entry
Entry(boolean domEnabled)
          Creates a new instance.
Entry(java.util.Hashtable table)
          Deprecated. will be remove in a future release.
 
Method Summary
 void addAttributeValue(java.lang.Object name, java.lang.Object value)
          Deprecated. use addAttributeValue(String, Object) instead.
 void addAttributeValue(java.lang.Object name, java.lang.Object value, int op)
          Deprecated. use addAttributeValue(String, Object, int) instead.
 void addAttributeValue(java.lang.String name, java.lang.Object value)
          Adds a value to an attribute.
 void addAttributeValue(java.lang.String name, java.lang.Object value, int op)
          Adds a value to an attribute.
 org.w3c.dom.Node adoptNode(org.w3c.dom.Node source)
          This method adopts the provided as parameter Node by setting its parent to null and setting the document reference to this entry object.
 Attribute appendChild(org.w3c.dom.Node newChild)
          This will add the provided Attribute in the entry using the localName of that Attribute for a key name.
 Entry clone()
          Creates a shallow clone of the receiver.
 Entry clone(Entry entry)
          Deprecated. use the clone() method instead
 Entry cloneNode(boolean deep)
          Clones this entry object
 Property createAttribute(java.lang.String name)
          This method creates a new Property object that represents an element's attribute in terms of DOM concepts.
 Property createAttributeNS(java.lang.String namespaceURI, java.lang.String qualifiedName)
          This method creates new Property object that represents an element's attribute in terms of XML concepts.
 org.w3c.dom.CDATASection createCDATASection(java.lang.String data)
          Creates new AttributeCDATA object that represents a CDATASection in terms of XML concepts.
 Attribute createElement(java.lang.String tagName)
          This method creates new Attribute object that represents an element in terms of XML concepts.
 Attribute createElementNS(java.lang.String namespaceURI, java.lang.String qualifiedName)
          This method creates new Attribute object that represents an element in terms of XML concepts.
 org.w3c.dom.Text createTextNode(java.lang.String data)
          Creates new AttributeText object that represents a Text section in terms of XML concepts.
 void enableDOM()
          This method changes the entry from pre 7.0 flat structure to a hierarchical one.
static Entry fromJSON(java.lang.String string)
          Returns an Entry constructed from a JSON string
static Entry fromXML(java.lang.String string, java.lang.String xPath, java.lang.String entryTag)
          Returns an Entry object constructed from a XML String.
 Attribute get(java.lang.Object p1)
          Deprecated. use getAttribute(String) instead.
 Attribute getAttribute(java.lang.Object p1)
          Deprecated. use getAttribute(String) instead.
 Attribute getAttribute(java.lang.String name)
          Returns the Attribute object for a named attribute.
 java.util.Collection<java.lang.String> getAttributeCollection()
          Returns a java.util.Collection containing attribute names in this entry.
 java.lang.String[] getAttributeNames()
          Returns an array of strings containing attribute names in this entry.
 java.lang.Boolean getBooleanValue(java.lang.String xPath)
          Execute an XPath expression and get the result as an Boolean *
 org.w3c.dom.NodeList getChildNodes()
          Returns list of all children of the specified Node;
 Attribute getDocumentElement()
           
 org.w3c.dom.NodeList getElementsByTagName(java.lang.String tagname)
          Recursively searches for children with the specified tag name.
 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.
 Attribute getFirstAttribute(java.lang.String xPath)
          Execute an XPath expression and get the result as an Attribite *
 Attribute getFirstChild()
          Retrieves the first child, that is, the first Attribute object inserted in the Entry
 Attribute getLastChild()
          Retrieves the last child, that is, the last Attribute object inserted in the Entry
 org.w3c.dom.NodeList getNodeList(java.lang.String xPath)
          Execute an XPath expression and get the result as an NodeList
 java.lang.Number getNumberValue(java.lang.String xPath)
          Execute an XPath expression and get the result as an Number *
 java.lang.Object getObject(java.lang.Object p1)
          Deprecated. use getObject(String) instead.
 java.lang.Object getObject(java.lang.String p1)
          Returns the first value in an attribute as an object.
 char getOp()
          Returns the operation field of this entry.
 java.lang.String getOperation()
          Returns the operation field of this Entry.
 java.lang.Object getProperty(java.lang.Object propertyName)
          Deprecated. use getProperty(String) instead.
 java.lang.Object getProperty(java.lang.String propertyName)
          Returns a property value.
 java.lang.String[] getPropertyNames()
          Returns a string array of the property names contained in this entry.
 java.lang.String getString(java.lang.Object p1)
          Deprecated. use getString(String) instead.
 java.lang.String getString(java.lang.String p1)
          Returns the first value in an attribute as a String.
 java.lang.String getStringValue(java.lang.String xPath)
          Execute an XPath expression and get the result as an String *
 boolean hasChildNodes()
           
 boolean hasProperty(java.lang.String propertyName)
          Returns true if a property named by the propertyName parameter has a value.
 Attribute insertBefore(org.w3c.dom.Node newChild, org.w3c.dom.Node refChild)
          If the refChild is not presented in the entry structure or is null then the newChild will be appended to the end.
protected  void invalidateNamesList()
          Raises the flag that means the tree have been updated to tell the Entry to clear its catches.
 boolean isDOMEnabled()
           
 boolean isEqualNode(org.w3c.dom.Node other)
          
 void merge(Entry e)
          Convenience method that calls merge ( e, false ).
 void merge(Entry e, boolean mergevalues)
          Merges in the attributes and their values from another entry.
 void mergeAttributeValue(Attribute attr)
          Merges in the values from an attribute.
 void mergeAttributeValue(java.lang.Object name, AttributeInterface attr)
          Deprecated. use mergeAttributeValue(String, Attribute) instead.
 void mergeAttributeValue(java.lang.String name, Attribute attr)
          Merges the values in one attribute with the values from another attribute.
 Attribute newAttribute(java.lang.String name)
          This method is used to find/create an Attribute in the entry using the specified name.
 Attribute newAttribute(java.lang.String name, char oper)
          Returns an Attribute object from this entry's list of attributes.
 void removeAllAttributes()
          Removes all attributes from this Entry.
 void removeAttribute(java.lang.Object p1)
          Deprecated. use removeAttribute(String) instead.
 void removeAttribute(java.lang.String name)
          Removes an attribute from this Entry's list of attributes.
 Attribute removeChild(org.w3c.dom.Node oldChild)
          This method will remove the provided Attribute from the Entry.
 org.w3c.dom.Node renameNode(org.w3c.dom.Node n, java.lang.String namespaceURI, java.lang.String qualifiedName)
          Renames the node.
 Attribute replaceChild(org.w3c.dom.Node newChild, org.w3c.dom.Node oldChild)
          This method will search the entry structure for the oldChild and will replace it with the newChild.
 void set(AttributeInterface attr)
          Deprecated. Use setAttribute instead
 void setAttribute(Attribute attr)
          Adds or replaces an attribute in this Entry's list of attributes.
 void setAttribute(AttributeInterface attr)
          Deprecated. will be removed in future releases! Use setAttribute(Attribute) instead.
 void setAttribute(java.lang.Object name, java.lang.Object value)
          Deprecated. use setAttribute(String, Object) instead.
 void setAttribute(java.lang.Object name, java.lang.Object value, boolean protect)
          Deprecated. use setAttribute(String, Object, boolean) instead.
 void setAttribute(java.lang.String name, java.lang.Object value)
          Adds or replaces an attribute in this Entry's list of attributes.
 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.
 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.
 void setOp(char operation)
          Sets the operation code for this Entry.
 void setOperation(java.lang.String operation)
          Sets the operation code for this Entry.
 void setProperty(java.lang.Object propertyName, java.lang.Object propertyValue)
          Deprecated. use setProperty(String, Object) insetad.
 void setProperty(java.lang.String propertyName, java.lang.Object propertyValue)
          Sets/replaces a property.
 int size()
          Returns the number of attributes present in this entry.
 java.lang.String toDeltaString()
          Returns a string representation of this entry, including delta information.
 java.lang.String toJSON()
          Returns a JSON representation of this Entry object.
 java.lang.String toString()
          Returns a string representation of this entry.
 java.lang.String toXML()
          Returns a XML representation of this Entry object.
 
Methods inherited from class com.ibm.di.entry.DocImpl
compareDocumentPosition, createComment, createDocumentFragment, createEntityReference, createProcessingInstruction, getAttributes, getBaseURI, getDoctype, getDocumentURI, getDomConfig, getElementById, getFeature, getImplementation, getInputEncoding, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getStrictErrorChecking, getTextContent, getUserData, getXmlEncoding, getXmlStandalone, getXmlVersion, hasAttributes, importNode, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, normalizeDocument, setDocumentURI, setNodeValue, setPrefix, setStrictErrorChecking, setTextContent, setUserData, setXmlEncoding, setXmlStandalone, setXmlVersion
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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_ADD2

public static final java.lang.String OP_ADD2
String representation of the OP_ADD field.

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_MOD2

public static final java.lang.String OP_MOD2
String representation of the OP_MOD field.

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_DEL2

public static final java.lang.String OP_DEL2
String representation of the OP_DEL field.

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_UNCHANGED2

public static final java.lang.String OP_UNCHANGED2
String representation of the OP_UNCHANGED field.

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

OP_GEN2

public static final java.lang.String OP_GEN2
String representation of the OP_GEN field.

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

PATH_SEPARATOR_STR

public static final java.lang.String PATH_SEPARATOR_STR
This is the string representing the PATH_SEPARATOR_CHAR field.

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.