com.ibm.di.entry
Class Attribute

java.lang.Object
  extended by com.ibm.di.entry.NodeImpl
      extended by com.ibm.di.entry.Attribute
All Implemented Interfaces:
Serializable, Cloneable, Element, Node

public class Attribute
extends NodeImpl
implements Cloneable, Element

The Attribute class is used in conjunction with the Entry object to store information about an attribute. The attribute has a name and a list of zero or more values. Each value can be any type of Java object so you can add values of any kind to the attribute.

This class has various methods which manipulates wrapped or unwrapped values. In this context 'unwrap' means to get an Object value at specified position, cast it to AttributeValue object, and call getValue() method on it. 'Wrapped' value simply means that the object is used as it is - an AttributeValue object.

Since IBM Tivoli Directory Integrator 7.0 an Attribute object could be treated as an array of objects (Object[]), the following script illustrates this:

 // let's say that the work entry have an Attribute called "demo" defined like this:
 
 // create the Attribute;
 work.demo = new com.ibm.di.entry.Attribute();
 
 // add values to the attribute;  
 work.demo[0] = "val1";
 work.demo[1] = new java.lang.Integer("5");
 work.demo[2] = "thirdValue";  
  
 // From a performance point of view it is better to get a reference to the Attribute if we are going to use that object multiple times.
 // This will not make the Script Engine look up the "demo" attribute each time from the work entry.
 // The above lines "work.demo[x]" are not a good practice, this one is better:
 var attr = work.demo;
 
 // now the "demo" attribute have 3 values and we need to use each one of them. We could do that by using the [] notation just like we would do with an array.
 var val1 = attr[0];
 var val2 = attr[1];
 var val3 = attr[2];
 
 // or we could cycle through each of the Attribute's values like this:
 
 for (val in attr.getValues())
                main.logmsg(val);
 
 // The result of this is that each value is being printed in the log. 
 // something like this: 
 // val1
 // 5.0
 // thirdValue
 
 // Note that we use the getValues() method.
 
 // If we have done this:
 
 for (val in attr)
                main.logmsg(val);
 
 // Then the val variable would have a reference to the "demo" Attribute,
 // thus the log would contain a single line that is the string representation of the "demo" Attribute.
 // something like this:
 // demo:val1|5.0|thirdValue
 
 // This is because the toString() method of that Attribute is used implicitly.
 

See Also:
Serialized Form

Field Summary
static char ATTRIBUTE_ADD
          Add value
static char ATTRIBUTE_DELETE
          Delete value
static char ATTRIBUTE_MOD
          Values modified
static char ATTRIBUTE_REPLACE
          Replace value
static char ATTRIBUTE_UNCHANGED
          Unchanged
static String[] OPER
          Array holding the string representation of the character fields:
[0] = ATTRIBUTE_REPLACE
[1] = ATTRIBUTE_ADD
[2] = ATTRIBUTE_DELETE
[3] = ATTRIBUTE_UNCHANGED
[4] = ATTRIBUTE_MOD
 
Fields inherited from class com.ibm.di.entry.NodeImpl
parent
 
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
Attribute()
          Initialize this attribute with no name, no values and the operation code set to ATTRIBUTE_REPLACE.
Attribute(String name)
          Initializes this attribute with no values and the operation code set to ATTRIBUTE_REPLACE, the name is set to name.
Attribute(String name, Object value)
          Initializes this attribute with operation code set to ATTRIBUTE_REPLACE, the name is set to name and the value value is added to the list of values.
Attribute(String qualifiedName, String namespaceURI, boolean protect)
          Initializes this attribute with operation code set to ATTRIBUTE_REPLACE, the name is set to the provided name and is marked to belong to the provided namespace URI.
 
Method Summary
 void addValue(int position, Object val)
          Adds the specified object as Attribute's value at the specified position.
 void addValue(int position, Object p1, int valueOper)
          Adds the specified object into this Attribute at the specified location.
 void addValue(Object val)
          Adds a value to the attribute's list of values.
 void addValue(Object p1, int valueOper)
          Adds a value to this Attribute's list of values.
 Attribute addValues(Attribute attr)
          Add the values in another Attribute to this Attribute.
 Node appendChild(Node newChild)
          Appends the new child to the end of the list of values.
 void clear()
          Removes all values from this attribute and sets the operation to ATTRIBUTE_REPLACE.
 Attribute clone()
          Returns a clone of this object.
 Attribute cloneNode(boolean deep)
          This method clones the Attribute object receiving the call.
 boolean contains(Object value)
          Checks if a value is contained in this Attribute.
static String escapeName(String name)
          Scans for characters that need to be escaped and returns a string with those characters escaped.
 String getAttribute(String name)
          
 Property getAttributeNode(String name)
          
 Property getAttributeNodeNS(String namespaceURI, String localName)
          
 String getAttributeNS(String namespaceURI, String localName)
          
 NamedNodeMap getAttributes()
           
 NodeList getCDATASections()
          This is a convenient method that will gather all the CDATASection children and will return them as a NodeList object.
 NodeList getChildNodes()
          This is the internal list of DOM children this Attribute have.
 NodeList getElementsByTagName(String tagname)
          
 NodeList getElementsByTagNameNS(String namespaceURI, String localName)
          
 Node getFirstChild()
          
 Node getLastChild()
          
 String getLocalName()
           
 String getName()
          Returns this Attribute's name without stripping it off the escape characters the name might has.
 String getNamespaceURI()
          
 String getNodeName()
           
 short getNodeType()
           
 String getNodeValue()
          This method will return the result of concatenation of all the AttributeText nodes this Attribute have.
 char getOper()
          Returns the operation type of this Attribute.
 String getOperation()
          Returns the operation type of this Attribute as a String.
 Entry getOwnerDocument()
           
 String getPrefix()
           
 boolean getProtected()
          Returns the protected value of this Attribute
 TypeInfo getSchemaTypeInfo()
          Not implemented!
 String getTagName()
           
 NodeList getTextSections()
          This is a convenient method that will gather all the Text children and will return them as a NodeList object.
 String getValue()
          Returns the first value, if any, as a String object.
 Object getValue(int index)
          Returns the value at the position given by index.
 Object getValueAV(int index)
          Returns the object at the given index.
 int getValueOper(int index)
          Returns the value operation code at a specified index as an integer.
 String getValueOperation(int index)
          Returns the operation code as a string (add, delete, unchanged) for a given index.
 Object[] getValues()
          Returns this attribute's values as an array of objects.
 Object[] getValuesAV()
          Returns this Attribute's values as an array of objects.
 Vector getValuesVector()
          Returns this Attribute's values as a Vector.
 boolean hasAttribute(String name)
           
 boolean hasAttributeNS(String namespaceURI, String localName)
          Checks to see if a property with the specified localName and Attribute exists.
 boolean hasAttributes()
          
 boolean hasChildNodes()
          
 boolean hasValue(Object value)
          Checks if a value is contained in this Attribute.
 boolean hasValueIC(String value)
          Checks if a string value is contained in this attribute.
 Node insertBefore(Node newChild, Node refChild)
          Inserts the new child before the reference child.
 void internalGetElementsByTagName(String tagname, List<NodeImpl> attList)
           
 void internalGetElementsByTagNameNS(String namespaceURI, String localName, List<NodeImpl> attList)
           
protected  String internalLookupPrefix(String namespaceURI)
          Searches for the first prefix that is matched to the provided namespaceURI.
protected  String internalNSLookup(String prefix)
          Contains Attribute specific logic for looking up a NameSpace using the provided prefix.
 boolean isDOMEnabled()
           
 boolean isEqualNode(Node other)
          First calls superisEqualNode(Node) and if it returns true then the following checks are done:
checks whether the other object is instance of the Attribute class compares each Properties both Attributes have compares the operations of both Attributes If at least one of the above checks do not pass then the two Attributes are considered different.
protected  void merge(Attribute a)
          Merges the children/properties of another attribute to this attribute.
static String normalizeName(String name)
          Strips down the escape characters from the provided String.
 void removeAttribute(String name)
          Removes the Property found by the specified name (e.g.
 Attr removeAttributeNode(Attr oldAttr)
          Removes the specified Property from this Attribute node.
 void removeAttributeNS(String namespaceURI, String localName)
          Removes the Property found by the specified local name and namespace.
 Node removeChild(Node oldChild)
          Removes the specified Node from this Attribute.
 boolean removeValue(Object p1)
          Removes all instances of a value from the attribute's list of values.
 Object removeValueAt(int index)
          Removes a value at a given index.
 Node replaceChild(Node newChild, Node oldChild)
          Replaces an existing node with a new node.
 void setAttribute(String name, String value)
          
 Attr setAttributeNode(Attr newAttr)
          
 Attr setAttributeNodeNS(Attr newAttr)
          
 void setAttributeNS(String namespaceURI, String qualifiedName, String value)
          
 void setIdAttribute(String name, boolean isId)
          IDs are not supported!
 void setIdAttributeNode(Attr idAttr, boolean isId)
          IDs are not supported!
 void setIdAttributeNS(String namespaceURI, String localName, boolean isId)
          IDs are not supported!
 void setName(String name)
          Sets this Attribute's name.
 void setNodeValue(String nodeValue)
          This method will remove all the child nodes of type Text this Attribute might have.
 void setOper(char operation)
          Sets the operation type of this Attribute.
 void setOperation(String operation)
          Sets the operation type of this Attribute.
 void setPrefix(String prefix)
           
 Attribute setProtected(boolean protect)
          Deprecated. use setProtected(boolean, boolean) instead.
 void setProtected(boolean protect, boolean deep)
          Marks this Attribute as protected and prevents its String values to be written when toString() or toDeltaString() are called.
 void setValue(int index, Object val)
          Sets the attribute's value at a specific position to the value specified.
 void setValue(int position, Object p2, int valueOper)
          Sets the attribute's value at a specific position to the value specified.
 void setValue(Object val)
          Sets this Attribute's value at position 0 to the value specified.
 void setValue(Object p1, int valueOper)
          Sets this Attribute's value at position 0 to the value specified.
 void setValueOper(int index, int valueOper)
          Sets the value operation code.
 void setValueOperation(int index, String valueOper)
          Sets the value operation code for a specified index.
 void setValues(List<? extends Object> values)
          Sets this Attribute's values using the List passed to it.
 void setValues(Object[] values)
          Sets the Attribute's values to the array of objects provided by values.
 int size()
          Returns the number of values contained in this Attribute.
 String toDeltaString()
          Returns the Delta string representation of this Attribute.
 Element toDOM(Document doc)
          Converts an Attribute to a custom DOM implementation.
 String toString()
          Returns the string representation of this attribute.
 
Methods inherited from class com.ibm.di.entry.NodeImpl
compareDocumentPosition, getBaseURI, getFeature, getNextSibling, getParentNode, getPreviousSibling, getTextContent, getUserData, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, setTextContent, setUserData
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.w3c.dom.Node
compareDocumentPosition, getBaseURI, getFeature, getNextSibling, getParentNode, getPreviousSibling, getTextContent, getUserData, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, setTextContent, setUserData
 

Field Detail

ATTRIBUTE_REPLACE

public static final char ATTRIBUTE_REPLACE
Replace value

See Also:
Constant Field Values

ATTRIBUTE_ADD

public static final char ATTRIBUTE_ADD
Add value

See Also:
Constant Field Values

ATTRIBUTE_DELETE

public static final char ATTRIBUTE_DELETE
Delete value

See Also:
Constant Field Values

ATTRIBUTE_UNCHANGED

public static final char ATTRIBUTE_UNCHANGED
Unchanged

See Also:
Constant Field Values

ATTRIBUTE_MOD

public static final char ATTRIBUTE_MOD
Values modified

See Also:
Constant Field Values

OPER

public static final String[] OPER
Array holding the string representation of the character fields:
[0] = ATTRIBUTE_REPLACE
[1] = ATTRIBUTE_ADD
[2] = ATTRIBUTE_DELETE
[3] = ATTRIBUTE_UNCHANGED
[4] = ATTRIBUTE_MOD

Constructor Detail

Attribute

public Attribute()
Initialize this attribute with no name, no values and the operation code set to ATTRIBUTE_REPLACE.


Attribute

public Attribute(String name)
Initializes this attribute with no values and the operation code set to ATTRIBUTE_REPLACE, the name is set to name.

Parameters:
name - The attribute name

Attribute

public Attribute(String name,
                 Object value)
Initializes this attribute with operation code set to ATTRIBUTE_REPLACE, the name is set to name and the value value is added to the list of values.

Parameters:
name - The attribute name
value - The attribute value

Attribute

public Attribute(String qualifiedName,
                 String namespaceURI,
                 boolean protect)
Initializes this attribute with operation code set to ATTRIBUTE_REPLACE, the name is set to the provided name and is marked to belong to the provided namespace URI.

Parameters:
qualifiedName - this is the raw name (escaped appropriately) to set to the attribute the.
namespaceURI - the namespace this Attribute belongs to
protect - marks the Attribute as protected, by default is false
Since:
7.0
Method Detail

clone

public Attribute clone()
Returns a clone of this object. The cloning is shallow and does not clone attribute values. If for some reason the cloning does not succeed a constructor of the Attribute class will be explicitly called. Each descendant should check for this.

The child nodes of the receiver object are cloned completely. The clone process is always deep.

The returned clone has no parent and no document. They will be set when the object is set to an Entry or appended as a child of another Attribute.

Overrides:
clone in class Object
Returns:
the cloned attribute if the cloning process succeeds or a new object - copy of this one.
See Also:
cloneNode(boolean)

clear

public void clear()
Removes all values from this attribute and sets the operation to ATTRIBUTE_REPLACE.

Example:

 var entry = input.getConnector.getNextEntry();
 var attrlist = entry.getAttributeNames();
 
 for (i = 0; i < attrlist.length; i++) {
        var attr = entry.getAttribute(attrlist[i]);
        if (system.startsWithIC(attrlist[i], "del")) {
                attr.clear();
        }
 }
 // print the results where all attributes with names starting 
 // with 'del' are cleared   
 task.dumpEntry(entry);
 
The Properties of the Attribute are not changed.


hasValue

public boolean hasValue(Object value)
Checks if a value is contained in this Attribute.

Parameters:
value - The value to check for
Returns:
true if this Attribute contains the value, false if not
See Also:
contains(java.lang.Object)

hasValueIC

public boolean hasValueIC(String value)
Checks if a string value is contained in this attribute. The method converts values to their string representation before doing a case-insensitive comparison.

Example:

 if (conn.hasValueIC("this value")) {
        task.logmsg("It is there");
 }
 

Parameters:
value - The string value to check for
Returns:
true if attribute contains the value, false if not

contains

public boolean contains(Object value)
Checks if a value is contained in this Attribute.

Example:

 var entry = input.getConnector().getNextEntry();
 var attrlist = entry.getAttributeNames();
 
 for (i = 0; i < attrlist.length; i++) {
        var attr = entry.getAttribute(attrlist[i]);
        if (attrlist[i].equals("name") && attr.contains("John") && attr.contains("Smith")) {
                task.logmsg("Another John Smith coming...");
        }
 }
 

Parameters:
value - The value to check for
Returns:
true if this Attribute contains the value, false if not

getValue

public String getValue()
Returns the first value, if any, as a String object.

Returns:
The object as a String or null if attribute has no values

getValue

public Object getValue(int index)
Returns the value at the position given by index. The value is unwrapped if it is an AttributeValue object.

Example:

    var v = conn.getAttribute("attrname").getValue ( 0 );
    task.logmsg( "Java class of v is: " + v.getClass().getName() );
    task.logmsg( "String representation: " + v.toString() );
    if ( v.getClass().getName() == "java.util.Date" ) {
      task.logmsg("Date object: " + v.getMonth();
    }
 

Parameters:
index - The position
Returns:
The Object or null if index is out of range
See Also:
size()

getValueAV

public Object getValueAV(int index)
Returns the object at the given index. This method unwraps the AttributeValue, if its operation code is AttributeValue.AV_REPLACE. In this case the actual value of the attribute is returned. If the AttributeValue's operation code is different from the above, the whole AttributeValue object is returned instead of the actual value. Note: if you want to access each value as an AttributeValue object (disregarding the operation code), use the DOM API.
For example:
Lets say you want to access the wrapped value of an attribute (an AttributeValue object). The name of the attribute is myAttr and the index of the value is 2. Use this script:
 task.logmsg("Attribute: " + myAttr); //attribute
 var index = 2; //value's index
 var nodeList = work.getAttribute(attr).getChildNodes();
 var internalIndex = 0; 
 var value = null;
 for(node in nodeList) {
 // The nodeList may contain Attribute objects. In order to get the correct 
 // index of the value we need to increase the internalIndex only when an 
 // AttributeValue is found. 
        if(!(node instanceof com.ibm.di.entry.Attribute) 
                        && internalIndex++ == index) {
                value = node;
                break;
 }
 task.logmsg("Value(" + index + ")= " + value);
 
 

Parameters:
index - the position
Returns:
The Object at the position, or null if index too high

getValues

public Object[] getValues()
Returns this attribute's values as an array of objects. This method unwraps AttributeValue objects. The array may be empty if attribute has no values (e.g. arr.length == 0).

Example:

 // get values of attribute of conn object;
 var vallist = conn.getAttribute("name").getValues();
 
 // cycle through each of the Attribute's values and print them
 for (val in vallist)
        main.logmsg(val);
 
 // or you could print them like this
 for (i = 0; i < vallist.length; i++) {
        main.logmsg(vallist[i]);
 }
 

Returns:
An array of objects.

getValuesVector

public Vector getValuesVector()
Returns this Attribute's values as a Vector. This method unwraps AttributeValue objects.

Example:

 // get values of attribute of conn object;
 var vallist = conn.getAttribute("name").getValuesVector();
 
 // cycle through each of the Attribute's values and print them
 for (i = 0; i < vallist.size(); i++) {
        main.logmsg(vallist.get(i));
 }
 

Returns:
An array of objects.
See Also:
getValues()

getValuesAV

public Object[] getValuesAV()
Returns this Attribute's values as an array of objects. This method unwraps AttributeValue objects only if their operation code is AttributeValue.AV_REPLACE. Otherwise no unwrapping is performed and the AttributeValue objects are returned. The array may be empty if the attribute has no values (e.g. arr.length == 0).Note: if you need an array where all the values are wrapped (as AttributeValue objects) you must use the DOM API instead.
Example:
This script shows how to retrieve all the values of the attribute(myAttr) without unwrapping any of them.
 task.logmsg("Attribute: " + myAttr); //attribute
 var nodeList = work.getAttribute(attr).getChildNodes();
 var array = new Array();
 var i = 0;
 for(node in nodeList) {
        if(!(node instanceof com.ibm.di.entry.Attribute))
                array[i++] = node;
 }
 //the 'array' holds AttributeValue objects only
 

Returns:
An array of objects.
See Also:
getValues()

setValues

public void setValues(List<? extends Object> values)
Sets this Attribute's values using the List passed to it.

Parameters:
values - The new values list

setValues

public void setValues(Object[] values)
Sets the Attribute's values to the array of objects provided by values.

Example:

 // suppose work entry has attribute 'changenumbers' 
 // with int values we want to sort
 var attr = work.getAttribute("changenumbers");
 var vlist = attr.getValues();
 
 // sort values of attribute 'changenumbers'
 java.util.Arrays.sort(vlist);
 
 // update sorted values to entry attribute
 attr.setValues(vlist);
 

Parameters:
values - The new value array

setValue

public void setValue(Object val)
Sets this Attribute's value at position 0 to the value specified. If the attribute has no values the value is inserted, otherwise the value at position 0 is replaced.

Example:

 var entry = input.getConnector.getNextEntry();
 var attrlist = entry.getAttributeNames();
 
 for (i = 0; i < attrlist.length; i++) {
        var attr = entry.getAttribute(attrlist[i]);
        attr.setValue("firstValue")
 }
 

Parameters:
val - The new value

addValue

public void addValue(Object val)
Adds a value to the attribute's list of values.

Example:

 // create the Attribute;
 var attr = new com.ibm.di.entry.Attribute();
 
 // add values to the attribute;  
 attr.addValue("one");
 attr.addValue(2);
 attr.addValue('3');
 
 // cycle through each of the Attribute's values and print them
 for (val in attr.getValues())
                main.logmsg(val);
 
 // The result is: 
 // one
 // 2.0
 // 3
 

Parameters:
val - The new value

setValue

public void setValue(int index,
                     Object val)
Sets the attribute's value at a specific position to the value specified. If the position (index) is out of range an exception is thrown.

Parameters:
index - The position
val - The value
Throws:
ArrayIndexOutOfBoundsException - if the index was invalid.

removeValue

public boolean removeValue(Object p1)
Removes all instances of a value from the attribute's list of values. Any Node values will be automatically detached from this parent and from the document they were previously attached to.

Parameters:
p1 - The value to remove
Returns:
true if this Attribute contained the value, false if no change.

removeValueAt

public Object removeValueAt(int index)
Removes a value at a given index. Node values will be automatically detached from this parent and from the document they were attached to previously.

Parameters:
index - The index of the value to remove
Returns:
The value at the given index, or null if index is out of bounds

getName

public String getName()
Returns this Attribute's name without stripping it off the escape characters the name might has. To get the plain name without the escape characters use the getNodeName() instead.

Returns:
the Attribute's name

setName

public void setName(String name)
Sets this Attribute's name.

Parameters:
name - The new name of this Attribute

getOper

public char getOper()
Returns the operation type of this Attribute.

Returns:
The operation type as a char

getOperation

public String getOperation()
Returns the operation type of this Attribute as a String. The operation has only been set to a meaningful value if this Attribute is part of an Entry that comes from an Iterator with Delta enabled.

Returns:
The operation type as a string. Possible values are "replace", "add", "delete", "unchanged" or "modify"

setOper

public void setOper(char operation)
Sets the operation type of this Attribute.

Parameters:
operation - The operation type as a char

setOperation

public void setOperation(String operation)
Sets the operation type of this Attribute.

Parameters:
operation - The operation type as a string. If this is null or empty string the ATTRIBUTE_REPLACE operation is set.

size

public int size()
Returns the number of values contained in this Attribute.

Returns:
The number of values

toString

public String toString()
Returns the string representation of this attribute.

Overrides:
toString in class Object
Returns:
The name and values as a structured String

toDeltaString

public String toDeltaString()
Returns the Delta string representation of this Attribute. This string representation also contains delta information, if present.

Returns:
The name and values as a structured string

setValue

public void setValue(Object p1,
                     int valueOper)
Sets this Attribute's value at position 0 to the value specified. If the attribute has no values the value is inserted, otherwise the value at position 0 is replaced.

Parameters:
p1 - The new value
valueOper - The value operation code
See Also:
setValue(Object)

setValue

public void setValue(int position,
                     Object p2,
                     int valueOper)
Sets the attribute's value at a specific position to the value specified. If the position is out of range an exception is thrown.

Parameters:
position - The position
p2 - The value
valueOper - The value operation code
Throws:
ArrayIndexOutOfBoundsException - if the position was invalid.

addValue

public void addValue(Object p1,
                     int valueOper)
Adds a value to this Attribute's list of values.

Example:

 // suppose work entry has 'lowercasestring' attribute with some string values
 var attr = work.newAttribute("lowercasestring");
 
 // add new values to the attribute
 attr.addValue("Mamut", com.ibm.di.entry.AttributeValue.AV_ADD);
 attr.addValue("APPC", com.ibm.di.entry.AttributeValue.AV_ADD);
 
 main.logmsg("Before validation:");
 task.dumpEntry(work);
 
 // find all newly added values and make them lowercase 
 for (i = 0; i < attr.size(); i++) {
        if (attr.getValueOper(i) == com.ibm.di.entry.AttributeValue.AV_ADD) {
                var str = attr.getValue(i).toLowerCase();
                attr.setValue(i, str);
        }
 }
 
 // print result
 main.logmsg("After validation:");
 task.dumpEntry(work);
 

Parameters:
p1 - The new value
valueOper - The value operation code

addValue

public void addValue(int position,
                     Object val)
Adds the specified object as Attribute's value at the specified position. The object is inserted before any previous value at the specified location. If the location is equal to the size of this Vector, the object is added at the end.

Example:

 // suppose work entry has attribute 'changenumbers' 
 // with int values in ascending order which we want to keep
 
 var vlist = attr.getValues();
 
 // value we want to insert into 'changenumbers' attribute
 var insertval = 5;
 
 //insert value keeping ascending order of attribute's values
 for (i = 0; i < vlist.length; i++) {
        main.logmsg(vlist[i]);
        if (insertval >= vlist[i] && insertval <= vlist[i + 1]) {
                main.logmsg("Found place to insert ");
                attr.addValue(i + 1, insertval);
                break;
        }
 }
 main.dumpEntry(work);
 

Parameters:
position - the index at which to insert the element
val - the object to insert in this Vector
Throws:
ArrayIndexOutOfBoundsException - when location < 0 || > size()

addValue

public void addValue(int position,
                     Object p1,
                     int valueOper)
Adds the specified object into this Attribute at the specified location. The object is inserted before any previous value at the specified location. If the location is equal to the size of this Vector, the object is added at the end.

Parameters:
position - the index at which to insert the element
p1 - the object to insert in this Vector
valueOper - The value operation code
Throws:
ArrayIndexOutOfBoundsException - when location < 0 || > size()
See Also:
addValue(Object, int)

setValueOper

public void setValueOper(int index,
                         int valueOper)
Sets the value operation code. If the value is a non-AV object, a new AttributeValue object is created to hold the current value.

Parameters:
index - The value index
valueOper - The value operation code

getValueOper

public int getValueOper(int index)
Returns the value operation code at a specified index as an integer.

Example:

 // suppose work entry has 'lowercasestring' attribute with some values
 var attr = work.newAttribute("lowercasestring");
 
 // add new values to the attribute
 attr.addValue("Mamut", com.ibm.di.entry.AttributeValue.AV_ADD);
 attr.addValue("APPC", com.ibm.di.entry.AttributeValue.AV_ADD);
 
 main.logmsg("Before validation:");
 task.dumpEntry(work);
 
 // find all newly added values and make them lowercase 
 for (i = 0; i < attr.size(); i++) {
        if (attr.getValueOper(i) == com.ibm.di.entry.AttributeValue.AV_ADD) {
                var str = attr.getValue(i).toLowerCase();
                attr.setValue(i, str);
        }
 }
 
 // print result
 main.logmsg("After validation:");
 task.dumpEntry(work);
 

Parameters:
index - The value index
Returns:
The value operation code ( -1 indicates no operation code )

setValueOperation

public void setValueOperation(int index,
                              String valueOper)
Sets the value operation code for a specified index. If the value is a non-AV object, a new AttributeValue object is created to hold the current value.

Parameters:
index - The new value
valueOper - The string-version operation code

getValueOperation

public String getValueOperation(int index)
Returns the operation code as a string (add, delete, unchanged) for a given index. If the value at the index is not a delta value (e.g. AttributeValue object) then a blank string is returned.

Parameters:
index - The index

setProtected

@Deprecated
public Attribute setProtected(boolean protect)
Deprecated. use setProtected(boolean, boolean) instead.

Sets the protected value of this Attribute

Parameters:
protect - - If true, try to protect the Attribute values by not dumping them in log files
Returns:
this Attribute

setProtected

public void setProtected(boolean protect,
                         boolean deep)
Marks this Attribute as protected and prevents its String values to be written when toString() or toDeltaString() are called.

Parameters:
protect - specify the state of the flag.
deep - specify whether the provided state of the flag will be applied for all the children in the sub-tree.
Since:
7.0

getProtected

public boolean getProtected()
Returns the protected value of this Attribute

Returns:
true if the values should not be dumped in log files

addValues

public Attribute addValues(Attribute attr)
Add the values in another Attribute to this Attribute. All values are added, even if they already exist.

Example:

 // create one Attribute;
 var attr1 = new com.ibm.di.entry.Attribute();
 
 // add values to the attribute;  
 attr1.addValue("one");
 attr1.addValue('2');
 attr1.addValue(3);
 
 var attr2 = work.attr2.addValues(attr1);
 //the result is that attr2 now have 3 values: 'one'    '2'     '3.0'
 

Parameters:
attr - The Attribute from which values are collected
Returns:
this Attribute

isDOMEnabled

public boolean isDOMEnabled()

normalizeName

public static final String normalizeName(String name)
Strips down the escape characters from the provided String.

Parameters:
name - the name to remove the escape characters from.
Returns:
the escaped String.

escapeName

public static final String escapeName(String name)
Scans for characters that need to be escaped and returns a string with those characters escaped.

Parameters:
name - the name to escape.
Returns:
the escaped string.

toDOM

public Element toDOM(Document doc)
              throws ParserConfigurationException
Converts an Attribute to a custom DOM implementation. If a Document is passed then the method will use that document as the container for the Attribute's data. If no Document is passed then the default Java implementation will be used. Note: only the children of this Attribute are considered (those of type AttributeCDATA and AttributeText), the rest are ignored.
This method is useful when you need to easily convert to a DOM from a TDI's Entry/Attribute structure. The returned DOM could then be validated against a XMLSchema.

Note: This call will convert the flat Attribute to a hierarchical one!

Parameters:
doc - - the document implementation to use
Returns:
the root element of the resultant DOM structure, representing this Attribute.
Throws:
ParserConfigurationException

merge

protected void merge(Attribute a)
Merges the children/properties of another attribute to this attribute. If a value is not in the current list it is added. Each child Attribute from the foreign Attribute is accordingly merged with the child attributes of this Attribute.

The Properties of the foreign attribute always replace this attribute's properties.

Parameters:
a - the Attribute to merge values from
Since:
7.0

getTextSections

public NodeList getTextSections()
This is a convenient method that will gather all the Text children and will return them as a NodeList object.

Returns:
NodeList object that hold all the children of this Attribute that are of type Text
Since:
7.0

getCDATASections

public NodeList getCDATASections()
This is a convenient method that will gather all the CDATASection children and will return them as a NodeList object.

Returns:
NodeList object that hold all the children of this Attribute that are of type CDATASection
Since:
7.0

getOwnerDocument

public Entry getOwnerDocument()
Specified by:
getOwnerDocument in interface Node
Overrides:
getOwnerDocument in class NodeImpl

cloneNode

public Attribute cloneNode(boolean deep)
This method clones the Attribute object receiving the call. Depending on the passed parameter the cloning will be either deep or not.

If the cloning is deep then the method clone() is called.

If the cloning is not deep then a new Attribute object is returned with no parent and no document set. The object also has no children/values. The properties however are complete clones of the original objects.

Specified by:
cloneNode in interface Node
Parameters:
deep - specifies whether a deep clone should be done or not.
Returns:
the cloned object.
Since:
7.0

getLocalName

public String getLocalName()
Specified by:
getLocalName in interface Node
Returns:
the local name of the Attribute/Node
Since:
7.0

getNodeType

public short getNodeType()
Specified by:
getNodeType in interface Node
Returns:
the Node's type.
Since:
7.0
See Also:
Node.ELEMENT_NODE

getNodeValue

public String getNodeValue()
This method will return the result of concatenation of all the AttributeText nodes this Attribute have. The different values are separated by space. An empty string is returned if no AttributeText objects are available.

Specified by:
getNodeValue in interface Node
Returns:
the value of the Attribute.
Since:
7.0

setNodeValue

public void setNodeValue(String nodeValue)
This method will remove all the child nodes of type Text this Attribute might have. A new child node will be created of type Text and added to the children list.

Specified by:
setNodeValue in interface Node
Parameters:
nodeValue - the text of the text node that will be appended to the values list.
Throws:
DOMException - if an error occurs while removing Text nodes.
Since:
7.0

getNamespaceURI

public String getNamespaceURI()

Specified by:
getNamespaceURI in interface Node

getAttribute

public String getAttribute(String name)

Specified by:
getAttribute in interface Element

getAttributeNS

public String getAttributeNS(String namespaceURI,
                             String localName)

Specified by:
getAttributeNS in interface Element

getAttributeNode

public Property getAttributeNode(String name)

Specified by:
getAttributeNode in interface Element

getAttributeNodeNS

public Property getAttributeNodeNS(String namespaceURI,
                                   String localName)

Specified by:
getAttributeNodeNS in interface Element

getElementsByTagName

public NodeList getElementsByTagName(String tagname)

Specified by:
getElementsByTagName in interface Element

internalGetElementsByTagName

public void internalGetElementsByTagName(String tagname,
                                         List<NodeImpl> attList)

getElementsByTagNameNS

public NodeList getElementsByTagNameNS(String namespaceURI,
                                       String localName)

Specified by:
getElementsByTagNameNS in interface Element

internalGetElementsByTagNameNS

public void internalGetElementsByTagNameNS(String namespaceURI,
                                           String localName,
                                           List<NodeImpl> attList)

getSchemaTypeInfo

public TypeInfo getSchemaTypeInfo()
Not implemented!

Specified by:
getSchemaTypeInfo in interface Element
Returns:
null;

getTagName

public String getTagName()
Specified by:
getTagName in interface Element
Returns:
the tag name of the Attribute e.g. "prefix:localName"

hasAttributes

public boolean hasAttributes()

Specified by:
hasAttributes in interface Node
Overrides:
hasAttributes in class NodeImpl

hasAttribute

public boolean hasAttribute(String name)
Specified by:
hasAttribute in interface Element
Returns:
true if this Attribute has any Properties, false otherwise
Since:
7.0

hasAttributeNS

public boolean hasAttributeNS(String namespaceURI,
                              String localName)
                       throws DOMException
Checks to see if a property with the specified localName and Attribute exists.

Specified by:
hasAttributeNS in interface Element
Parameters:
localName - the local name of the Property
namespaceURI - the namespace of the Property
Returns:
true if this Attribute has such a Property, false otherwise.
Throws:
DOMException
Since:
7.0

removeAttribute

public void removeAttribute(String name)
Removes the Property found by the specified name (e.g. "pref:prop" or just "prop" if the property has no prefix). If no such property is found then the call is ignored.

Specified by:
removeAttribute in interface Element
Parameters:
name - the name of the property to look for.
Since:
7.0

removeAttributeNS

public void removeAttributeNS(String namespaceURI,
                              String localName)
Removes the Property found by the specified local name and namespace. If no such property is found then the call is ignored.

Specified by:
removeAttributeNS in interface Element
Parameters:
namespaceURI - the namespace the property to remove belongs to
localName - the local name of the property to be removed
Since:
7.0

removeAttributeNode

public Attr removeAttributeNode(Attr oldAttr)
Removes the specified Property from this Attribute node. If the provided Property has no parent (i.e. parent == null) then this method returns null. If the Property has a parent but it is different than this Attribute then a DOMException is thrown.
The method will then search the Property in the Attribute and if found it will be removed and returned as a result. If could not be found a null will be returned.

Specified by:
removeAttributeNode in interface Element
Parameters:
oldAttr - the property to remove from this attribute.
Returns:
either the removed property or null stating that something in the removing process went wrong.
Since:
7.0

setAttribute

public void setAttribute(String name,
                         String value)

Specified by:
setAttribute in interface Element

setAttributeNS

public void setAttributeNS(String namespaceURI,
                           String qualifiedName,
                           String value)

Specified by:
setAttributeNS in interface Element

setAttributeNode

public Attr setAttributeNode(Attr newAttr)

Specified by:
setAttributeNode in interface Element

setAttributeNodeNS

public Attr setAttributeNodeNS(Attr newAttr)

Specified by:
setAttributeNodeNS in interface Element

setIdAttribute

public void setIdAttribute(String name,
                           boolean isId)
IDs are not supported!

Specified by:
setIdAttribute in interface Element
Parameters:
name -
isId -
Throws:
DOMException - - never

setIdAttributeNS

public void setIdAttributeNS(String namespaceURI,
                             String localName,
                             boolean isId)
IDs are not supported!

Specified by:
setIdAttributeNS in interface Element
Parameters:
namespaceURI -
localName -
isId -
Throws:
DOMException - - never

setIdAttributeNode

public void setIdAttributeNode(Attr idAttr,
                               boolean isId)
IDs are not supported!

Specified by:
setIdAttributeNode in interface Element
Parameters:
idAttr -
isId -
Throws:
DOMException - - never

isEqualNode

public boolean isEqualNode(Node other)
First calls superisEqualNode(Node) and if it returns true then the following checks are done:
If at least one of the above checks do not pass then the two Attributes are considered different.

Specified by:
isEqualNode in interface Node
Overrides:
isEqualNode in class NodeImpl
Parameters:
other - the node to compare this Attribute to
Returns:
true if both Attributes are the same based on the checks above, false otherwise.
Since:
7.0

internalNSLookup

protected String internalNSLookup(String prefix)
Contains Attribute specific logic for looking up a NameSpace using the provided prefix.

Overrides:
internalNSLookup in class NodeImpl
Parameters:
prefix - the prefix mapped to the namespace.
Returns:
the namespace if found otherwise null.
Since:
7.0

internalLookupPrefix

protected String internalLookupPrefix(String namespaceURI)
Searches for the first prefix that is matched to the provided namespaceURI.

Overrides:
internalLookupPrefix in class NodeImpl
Parameters:
namespaceURI - specifies the namespace to look for.
Returns:
the first prefix that is mapped to this namespaceURI or null if not found.
Since:
7.0

appendChild

public Node appendChild(Node newChild)
Appends the new child to the end of the list of values. If that child is already in the tree it is just moved. If this child belongs to another entry it is first cloned and then appended.

Specified by:
appendChild in interface Node
Overrides:
appendChild in class NodeImpl
Parameters:
newChild - the new child node to append.
Returns:
the new appended node (possibly clone).
Since:
7.0

getAttributes

public NamedNodeMap getAttributes()
Specified by:
getAttributes in interface Node
Overrides:
getAttributes in class NodeImpl
Returns:
the property map of this Attribute.
Since:
7.0

getChildNodes

public NodeList getChildNodes()
This is the internal list of DOM children this Attribute have. Any changes made to it will reflect the Attribute as well.

Specified by:
getChildNodes in interface Node
Overrides:
getChildNodes in class NodeImpl
Returns:
the internal list of children nodes

getFirstChild

public Node getFirstChild()

Specified by:
getFirstChild in interface Node
Overrides:
getFirstChild in class NodeImpl

getLastChild

public Node getLastChild()

Specified by:
getLastChild in interface Node
Overrides:
getLastChild in class NodeImpl

hasChildNodes

public boolean hasChildNodes()

Specified by:
hasChildNodes in interface Node
Overrides:
hasChildNodes in class NodeImpl

insertBefore

public Node insertBefore(Node newChild,
                         Node refChild)
Inserts the new child before the reference child. If the new child is already in the tree it is just moved. If this child belongs to another entry it is first cloned and then inserted. If the reference child is null then the new child is appended to the end.

Specified by:
insertBefore in interface Node
Overrides:
insertBefore in class NodeImpl
Parameters:
newChild - the new child node to inserted.
refChild - the reference child before which the new child will be inserted.
Returns:
the new appended node (possibly clone).
Since:
7.0

removeChild

public Node removeChild(Node oldChild)
Removes the specified Node from this Attribute. The passed node could be any instance of the NodeImpl class.

Specified by:
removeChild in interface Node
Overrides:
removeChild in class NodeImpl
Parameters:
oldChild - the node to remove.
Returns:
the removed node.
Since:
7.0

replaceChild

public Node replaceChild(Node newChild,
                         Node oldChild)
Replaces an existing node with a new node. If the existing node is not found null is returned.

Specified by:
replaceChild in interface Node
Overrides:
replaceChild in class NodeImpl
Parameters:
newChild - the node to replace the old node with
oldChild - then node that will be replaced
Returns:
the old node if found, null otherwise
Since:
7.0

setPrefix

public void setPrefix(String prefix)
               throws DOMException
Specified by:
setPrefix in interface Node
Throws:
DOMException

getPrefix

public String getPrefix()
Specified by:
getPrefix in interface Node

getNodeName

public String getNodeName()
Specified by:
getNodeName in interface Node
Overrides:
getNodeName in class NodeImpl
Returns:
the node name. This name is different than the one returned by the getName() method, because it does not contain escaped characters. For example if this method returns node.name it will defer from the other name which would be node\.name