com.ibm.pim.attribute
Interface AttributeInstance

All Known Subinterfaces:
LocationAttributeInstance

public interface AttributeInstance

An AttributeInstance is on object representing an occurrence of a data value AttributeDefinition on a particular Item or Category. An AttributeInstance is similar to the Script API EntryNode concept. The AttributeDefinition contains the generic information about the field while the AttributeInstance is used to stores and retrieve the data value for a specific AttributeOwner (Item, Category, etc.)

In regards to permissions, NONE of the read type methods can throw a permission exception, as read access is handled by never returning an attribute instance that you cannot read. Mutable methods (setters) can throw an exception if the user does not have write permissions.

See Also:
for a full explanation of attributes & attribute paths

Field Summary
static java.lang.String copyright
           
static java.lang.String OCCURRENCE_DELIMITER
           
static java.lang.String PATH_DELIMITER
           
 
Method Summary
 AttributeInstance addOccurrence()
          Add an occurrence to this attribute instance if this a multi-occurrence attribute .
 boolean canAddOccurrence()
          Determine if the current attribute instance allows another child occurrence to be created Return true if the attribute instance meets all of the following conditions:
 AttributeDefinition getAttributeDefinition()
          The attribute definition defines the template characteristics of this particular AttributeInstance
 java.util.List<? extends AttributeInstance> getChildren()
          This method allows retrieval of Attribute Instances within a particular occurrence of a multi-occurrence or a grouping node.
 java.lang.String getDisplayValue()
          Returns the string for displaying the item attribute specified by attribute object.
 int getOccurrenceIndex()
          Return the index that would be used to qualify this attribute instance in a path.
 AttributeOwner getOwner()
          Return the AttributeOwner associated with this AttributeInstance.
 AttributeInstance getParent()
          The parent attribute instance of an attribute instance is the attribute instance that contains this attribute instance and would return this attribute instance when getChildren() is called.
 java.lang.String getPath()
          Return the path for this AttributeInstance, like /MySpec/MyMultiGrouping#1/MyStringAttribute.
 java.util.Set<java.lang.String> getPossibleValues()
          For applicable attribute types, retrieve all possible values (e.g.
 java.lang.Object getValue()
          Get the current value of this attribute instance
 boolean isGrouping()
          AttributeInstance representing a directory, which is either a "grouping" or the root node for a spec.
 boolean isMultiOccurrence()
          AttributeInstance containing N child occurrences of the same AttributeDefinition.
 boolean isValue()
          AttributeInstance representing a leaf value.
 void removeOccurrence()
          If this is an occurrence of an attribute instance which has an attribute definition with a max occurrence greater than zero, the AttributeInstance will be deleted.
 void setValue(Catalog catalog, java.lang.String itemPrimaryKey)
          If this AttributeInstance is of type RELATIONSHIP, this method can set a related item as the value for this instance, specified by catalog and primary key
 void setValue(Item item)
          If this AttributeInstance is of type RELATIONSHIP, this method can set a related item as the value for this instance, specified by object reference
 void setValue(java.lang.Object value)
          Set the current value of this attribute instance.
 void setValueByExecutingNonPersistedAttributeRule(boolean overwrite)
          Executes the non-persisted script to set the value for this attribute instance
 

Field Detail

copyright

static final java.lang.String copyright
See Also:
Constant Field Values

PATH_DELIMITER

static final java.lang.String PATH_DELIMITER
See Also:
Constant Field Values

OCCURRENCE_DELIMITER

static final java.lang.String OCCURRENCE_DELIMITER
See Also:
Constant Field Values
Method Detail

getOwner

AttributeOwner getOwner()
Return the AttributeOwner associated with this AttributeInstance.

The owner of an attribute instance can beone of the following:

      Item
      CollaborationItem
      Category
      CollaborationCategory
      Organization
      LookupTableEntry
 

Returns:
the AttributeOwner associated with this AttributeInstance
Throws:
PIMInternalException - if there is internal error

canAddOccurrence

boolean canAddOccurrence()
Determine if the current attribute instance allows another child occurrence to be created Return true if the attribute instance meets all of the following conditions:

 1) the attribute instance is of type multi-dir  
 2) the attribute instance corresponds to a node with maxOccurrence limit being greater 
          than one in its spec 
 3) the attribute instance has number of child occurrence attribute instances less than the 
    maxOccurrence limit.
    
 Otherwise return false. 
 

Returns:
true if this attribute instance is a multi-dir that has room for another child occurrence; return false otherwise.
Throws:
PIMInternalException - if there is internal error

getPath

java.lang.String getPath()
Return the path for this AttributeInstance, like /MySpec/MyMultiGrouping#1/MyStringAttribute.

An AttributeInstance path differs from an AttributeDefinition path in that the AttributeInstance will have #occurrenceNumber when appropriate. The path is delimited by PATH_DELIMITER ("/") and occurrences are indicated by OCCURRENCE_DELIMITER ("#")

Returns:
the path for this AttributeInstance
Throws:
PIMInternalException - if there is internal error
See Also:
for utility methods for handling this path

getAttributeDefinition

AttributeDefinition getAttributeDefinition()
The attribute definition defines the template characteristics of this particular AttributeInstance

Returns:
the AttributeDefinition associated with this AttributeInstance

Throws:
PIMInternalException - if there is internal error

getValue

java.lang.Object getValue()
Get the current value of this attribute instance

Returns:
the current value of this attribute instance
Throws:
PIMInternalException - if there is internal error

setValue

void setValue(java.lang.Object value)
Set the current value of this attribute instance.

Note, you may pass null for value. This means that the attribute will have no value. For inheriting type attribute instances (LocationAttributeInstance, this is equivalent to calling useInheritance(true).

If there is a type conversion exception due to invalid value, that will result in a validation error and the value will not be saved. Validation errors can be obtained using save or validate methods.

Parameters:
value - the new value for this attribute instance
Throws:
PIMInternalException - if there is internal error
java.lang.UnsupportedOperationException - when called on a RELATIONSHIP attribute with a non-null value.
PIMAuthorizationException - Reserved for future use

setValue

void setValue(Catalog catalog,
              java.lang.String itemPrimaryKey)
If this AttributeInstance is of type RELATIONSHIP, this method can set a related item as the value for this instance, specified by catalog and primary key

Parameters:
catalog - the catalog containing the related item
itemPrimaryKey - the primary key of the related item
Throws:
PIMInternalException - if there is internal error
java.lang.UnsupportedOperationException - if this is not an instance of a relationship attribute
PIMAuthorizationException - Reserved for future use

setValue

void setValue(Item item)
If this AttributeInstance is of type RELATIONSHIP, this method can set a related item as the value for this instance, specified by object reference

Parameters:
item - the item to set as related. When item is null, the value is unset.
Throws:
PIMInternalException - if there is internal error
java.lang.UnsupportedOperationException - if this is not an instance of a relationship attribute
PIMAuthorizationException - Reserved for future use
java.lang.IllegalStateException - if the input parameter item is not null and has not been persisted

setValueByExecutingNonPersistedAttributeRule

void setValueByExecutingNonPersistedAttributeRule(boolean overwrite)
Executes the non-persisted script to set the value for this attribute instance

Parameters:
overwrite - a value of true will cause the current value to be overwritten, a value of false will mean that if a value is set already, this operation has no effect.
Throws:
PIMInternalException - if there is internal error
java.lang.UnsupportedOperationException - if the associated AttributeDefinition is is not a non persisted attribute or does not have a non-persisted script
PIMAuthorizationException - Reserved for future use

getChildren

java.util.List<? extends AttributeInstance> getChildren()
This method allows retrieval of Attribute Instances within a particular occurrence of a multi-occurrence or a grouping node. For example with a spec as follows:

 /spec1/grouping (max occurs=2)
 /spec1/grouping/mystringattr
 /spec1/grouping/mynumattr
 with instances as follows:
 
 Item
   /spec1 (root node for spec)
   /spec1/grouping (multi-occurrence container)
   /spec1/grouping#0 (directory)
   /spec1/grouping#0/mystringattr=Fish
   /spec1/grouping#0/mynumattr=23
   /spec1/grouping#1 (directory)
   /spec1/grouping#1/mystringattr=Goat
   /spec1/grouping#1/mynumattr=57
 getChildren on the AttributeInstance for /spec1/grouping#0 will return the "value" AttributeInstances for Fish
 and 23.
 getChildren on the AttributeInstance for /spec1/grouping#1 will return the "value" AttributeInstances for Goat
 and 57.
 getChildren on the AttributeInstance for /spec1/grouping will return the "grouping" AttributeInstances for
 grouping#0 and grouping#1
 getChildren on the AttributeInstance for spec1 will return the "multi-occurrence" AttributeInstance for
 grouping
 
Note, before processing a child attribute instance, one should use the methods isValue(), isDirectory(), and isMultiOccurrence() to determine the nature of the child attribute instance. As a rule of thumb, you may only call getValue() and setValue() on a "value" attribute instance, and on a non-value attribute instance, you may call getChildren(). Grouping attribute instances always have a multi-occurrence container as their parent. For values, on the other hand, there is a multi-occurrence container as the parent if and only if the max occurrences on the attribute definition is greater than one.

Returns:
the child AttributeInstances contained within this instance of a directory or multi-occurrence container attribute
Throws:
PIMInternalException - if there is internal error
java.lang.UnsupportedOperationException - if this is a value instance (cannot have children)

getParent

AttributeInstance getParent()
The parent attribute instance of an attribute instance is the attribute instance that contains this attribute instance and would return this attribute instance when getChildren() is called.

There are three different types of AttributeInstance:

 1. Value:
   If max occurrence of the value is one, then the parent is definitely a directory.
   If the max occurrence of the value is greater than one, then the parent is a multi-occurrence container.
 2. Directory: The parent of a directory is ALWAYS a multi-occurrence container
 3. Multi-Occurrence Container: The parent of a multi-occurrence container is always a directory
 

Returns:
the AttributeInstance containing this attribute instance.
Throws:
PIMInternalException - if there is internal error
java.lang.UnsupportedOperationException - if isContained() would return false (i.e. this is a root level attribute with no parent)

addOccurrence

AttributeInstance addOccurrence()
Add an occurrence to this attribute instance if this a multi-occurrence attribute .

This must be called on the multi-occurence attribute instance.

Returns:
the added attribute instance
Throws:
PIMInternalException - if there is internal error
PIMAuthorizationException - Reserved for future use

removeOccurrence

void removeOccurrence()
If this is an occurrence of an attribute instance which has an attribute definition with a max occurrence greater than zero, the AttributeInstance will be deleted. You may not call this operation otherwise.

Throws:
java.lang.UnsupportedOperationException - if this method is called on an attribute instance that is not a child of a multi-occurrence attribute instance.
PIMAuthorizationException - Reserved for future use
PIMInternalException - if there is internal error

getOccurrenceIndex

int getOccurrenceIndex()
Return the index that would be used to qualify this attribute instance in a path.

Note that the first occurrence will have an index of 0. For values, the occurrenceIndex is 0. If you want to check if a AttributeInstance is part of a multi-occurrence, use (getParent().isMultiOccurrence())

Returns:
the index
Throws:
java.lang.UnsupportedOperationException - if called on a multi-occurrence attribute instance
PIMInternalException - if there is internal error

getPossibleValues

java.util.Set<java.lang.String> getPossibleValues()
For applicable attribute types, retrieve all possible values (e.g. string enumeration, timezone, lookuptable)

Returns:
an array list of possible values as strings
Throws:
java.lang.UnsupportedOperationException - if possible values do not apply to this AttributeInstance
PIMInternalException - if there is internal error

isValue

boolean isValue()
AttributeInstance representing a leaf value. You may call getValue() on this instance and not getChildren(). If getValue() returns false, then you may call getChildren()

Only one of isValue(), isGrouping(), or isMultiOccurrence is ever true for a given AttributeInstance.

Returns:
true if the getValue can be called on this AttributeInstance
Throws:
PIMInternalException - if there is internal error

isGrouping

boolean isGrouping()
AttributeInstance representing a directory, which is either a "grouping" or the root node for a spec.

Only one of isValue(), isGrouping(), or isMultiOccurrence is ever true for a given AttributeInstance.

Returns:
true if this AttributeInstance is either a Grouping or the spec's root node
Throws:
PIMInternalException - if there is internal error

isMultiOccurrence

boolean isMultiOccurrence()
AttributeInstance containing N child occurrences of the same AttributeDefinition. You may not call getValue() on this instance. You may call getChildren().

Only one of isValue(), isGrouping(), or isMultiOccurrence is ever true for a given AttributeInstance.

Such nodes are used for: 1. Holding all child AttributeInstances for a given AttributeDefinition 2. The AttributeInstance that is flagged when there is a violation in the min or max occurrences 3. Logical place to call addChild() to add a child occurrence.

Returns:
true if a Multi Occurrence attribute instance.
Throws:
PIMInternalException - if there is internal error

getDisplayValue

java.lang.String getDisplayValue()
Returns the string for displaying the item attribute specified by attribute object.

Returns:
the preview string for displaying the entry attribute specified by attribute path or null if the attribute does not exist.
Throws:
PIMInternalException - If an internal error occurs.