com.ibm.pim.attribute
Interface AttributePathHelper


public interface AttributePathHelper

String attribute paths are used in MDMPIM for a number of purposes:

  1. For retrieving attribute definitions
  2. Inside an Attribute Collection to specify which fields which will be included in that attribute collection
  3. For creating or retrieving data for a particular attribute (field) on an item, category, location or organization - an Attribute Instance
  4. For specifying data for optional attributes on a item, category or location
  5. For specifying and retrieving data occurrences on an item or category, for multi-occurrence attributes

Examples of attribute path usage for these purposes are given below.

1. Retrieving attribute definitions

A typical usage is the method call:

Spec.getAttributeDefinition(String attributeDefinitionPath)

An AttributeDefinition (previously called a SpecNode in the Script API) contains information and properties about the data field (for example, its data type, validation rules, maximum length, localized status, and minimum and maximum occurrence settings). It is the AttributeDefinition that holds these properties, not the attribute path. The attribute path defines exactly which AttributeDefinition to use.

Examples

The following paths can all be used to identify a specific AttributeDefinition object:

  1. spec1/myattr - references a simple AttributeDefinition
  2. spec1/group - references a grouping AttributeDefinition
  3. spec1/group/myattr - references a simple AttributeDefinition within a grouping AttributeDefinition
  4. spec1/group/mysubgroup - references a grouping AttributeDefinition within a grouping

An attribute definition cannot store data, and the path can be used only as a means to access a data value if it happens to have an identical instance path (see below).

2. Inside an Attribute Collection

A typical usage is the method call:

AttributeCollection.getAttributeDefinitionPaths()

This retrieves the attribute paths corresponding to the AttributeDefinitions in the attribute collection.

3. Creating or retrieving data for a particular attribute

Some typical usages are the method calls:

Item.setAttributeValue(String attributeInstancePath, Object value)

Item.getAttributeValue(String attributeInstancePath)

The attributes associated with an item, category or location are not AttributeDefinitions, they are AttributeInstances (in the Script API these were called EntryNodes).

An AttributeInstance is different from a AttributeDefinition in that instead of having data about the field, it stores the actual data values for a specific MDMPIM entity such as an item or category.

In many cases, the attribute instance path pointing to the AttributeInstance will be the same as the attribute definition path pointing to that AttributeInstance's AttributeDefinition. This will be true for attributes which have MinOccurrence = 1 and MaxOccurrence = 1 on the AttributeDefinition definition. Section 5 below elaborates on the cases when this is not so.

For a given item or category there may or may not be data at a given attribute instance path even if the path is valid. This is a key difference between attribute definition paths, which can be used in isolation from any MDMPIM data entity, and attribute instance paths, which only have meaning in the context of a particular item, category or other MDMPIM entity.

Examples

The following paths can all be used along with an item, category or location to identify a specific AttributeInstance object:

  1. spec1/myattr - instance of attribute such as 1 in Section 1
  2. spec1/group - instance of attribute such as 2 in Section 1
  3. spec1/group/myattr - instance of attribute such as 3 in Section 1
    Since this is contained attribute, the instance will itself be contained in an AttributeInstance
  4. spec1/group/mysubgroup - instance of attribute such as 4 in Section 1
    Since this is contained attribute, the instance will itself be contained in an AttributeInstance

4. Specifying data for optional attributes

Some typical usages are the method calls:

Item.setAttributeValue(String attributeInstancePath, Object value)

Item.getAttributeValue(String attributeInstancePath)

An attribute can be considered optional if the AttributeDefinition has a MinOccurs value of zero. The attribute instance path can be valid even if there is no AttributeInstance yet (that is, no data value in that field for this entity yet). This means that there is the potential that the get methods return null. It also means that in calling setAttributeValue, you are creating an AttributeInstance object at the specified path and putting the specified value into it.

5. Specifying data for multi-occurrence attributes

Some typical usages are the method calls:

AttributeInstance.getOtherOccurrences()

Item.getAttributeInstances(String attributeDefinitionPath)

Item.setAttributeValues(String attributeInstancePath, ArrayList values)

When a AttributeDefinition has MaxOccurrence > 1, the attribute is known as a multi-occurrence attribute. This means it can have multiple data values per MDMPIM entity, up to and including the MaxOccurs value. These are represented as separate AttributeInstances. A multi-occurrence attribute may also be a grouping attribute; this is a separate concept which should not be confused.

Occurrences of multi-occurrence attributes are specified using a # symbol followed by a number

Note that it is legal from an attribute path perspective to access an index greater than MaxOccurrence (e.g. multiAttr#9972) and you can even set data into this attribute occurrence, but you will receive validation errors when trying to save the item/entity.

Examples

The following paths can all be used along with an item, category, and so on to identify a specific AttributeInstance object:

  1. spec1/myattr - as well as pointing to an AttributeInstance for a simple instance as mentioned above), it could also point to the first occurrence of a multi occurrence attribute
  2. spec1/myattr#0 - this is the same as 1, but definitely refers only to the first occurrence of a multi occurrence attribute
  3. spec1/myattr#7 - this refers to the eighth occurrence of a multi occurrence attribute
  4. spec1/group - as well as pointing to an AttributeInstance for a simple grouping instance, it could also point to the first occurrence of a multi occurrence attribute
  5. spec1/group#0 - this is the same as 4, but definitely refers only to the first occurrence of a multi occurrence attribute
  6. spec1/group#3 - refers to the fourth occurrence of a multi occurrence attribute
  7. spec1/group/myattr - refers to an instance of a simple contained attribute, or the first occurrence of a multi occurrence contained attribute
  8. spec1/group/myattr#0 - same as 7, but definitely a first occurrence
  9. spec1/group/myattr#7 - the eighth occurrence of a multi occurrence contained attribute
  10. spec1/group/mysubgroup - refers to an instance of a simple contained group, or the first occurrence of a multi occurrence contained group
  11. spec1/group/mysubgroup#0 - same as 10, but definitely a first occurrence
  12. spec1/group/mysubgroup#4 - the fifth occurrence of a contained multi occurrence group
  13. spec1/group#0/myattr - for 7-10, group could be replaced by group#0 and that would indicate this was the first occurrence of a repeating group. Without the #0 it could either be a simple group or the first occurrence of a repeating group
  14. spec1/group#3/myattr - this is either an instance of a simple attribute within the fourth occurrence of a multi occurrence group, or the first occurrence of a repeating attribute within the fourth occurrence of a multi occurrence group
  15. spec1/group#3/myattr#0 - same as 14 but definitely a first occurrence
  16. spec1/group#3/myattr#7 - eighth occurrence of a repeating attribute in the fourth occurrence of a repeating group
  17. spec1/group#3/mysubgroup - a simple contained grouping attribute within the fourth occurrence of a repeating group attribute, or the first occurrence of a repeating contained group within the fourth occurrence of a repeating group attribute
  18. spec1/group#3/mysubgroup#0 - same as 17 but definitely a first occurrence
  19. spec1/group#3/mysubgroup#4 - the fifth occurrence of a repeating contained group attribute, within the fourth occurrence of a repeating group

Note that the above paths (indeed all attribute instance paths) can also be used as attribute definition paths - since every AttributeInstance has an associated AttributeDefinition, MDMPIM will automatically use the path of the associated AttributeDefinition instead.

Note that as soon as multi-occurrence grouping attributes are introduced into the picture, it becomes very important to specify which instance of the grouping attribute you want to look inside.

See Also:
AttributeDefinition, AttributeInstance, Item, Category, Organization

Field Summary
static java.lang.String copyright
           
 
Method Summary
 java.lang.String createAttributePath(java.lang.String specName, java.util.ArrayList<java.lang.String> attributeNames)
          Construct an attribute path from a spec name, and a list of attribute names.
 java.lang.String getAttributeName(java.lang.String path)
          Extract the name of the attribute identified by a path
 java.util.List<java.lang.String> getAttributeNames(java.lang.String path, boolean omitLeafName)
          Extract the attribute names from a path
 java.lang.String getSpecName(java.lang.String path)
          Extract the spec name from a path
 boolean isValidPath(java.lang.String path)
          Determine whether the specified path is valid.
 java.lang.String qualifyAttributeName(java.lang.String nameOrPath, int index)
          Qualify an attribute name or path
 java.lang.String stripAttributeName(java.lang.String nameOrPath)
          Remove qualifier from attribute name or path
 

Field Detail

copyright

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

isValidPath

boolean isValidPath(java.lang.String path)
Determine whether the specified path is valid. As well as checking the path formatting, this will also check that the spec exists and the specified attribute path exists on that spec. If multi-occurrence attributes are qualified, it will check that the indices do not exceed MaxOccurrence for the AttributeDefinition Note that if the passed in path is intended for use as an instance path, the validity of the path does not have any bearing as to whether the path is valid for a particular MDMPIM entity. To determine this, use e.g. Item.hasAttributeInstance(path) or Item.canInstantiateAttributeOccurrenceAt(String path)

Parameters:
path - the String path to analyze
Returns:
true if the provided path is in a valid format ("/")
Throws:
java.lang.IllegalArgumentException - if path is null or empty
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use

getSpecName

java.lang.String getSpecName(java.lang.String path)
Extract the spec name from a path

Parameters:
path - the path to extract the spec name from
Returns:
the spec name specified in the path
Throws:
PIMInvalidPathException - if isValidPath(path) would return false
java.lang.IllegalArgumentException - if path is null or empty
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use

getAttributeNames

java.util.List<java.lang.String> getAttributeNames(java.lang.String path,
                                                   boolean omitLeafName)
Extract the attribute names from a path

Parameters:
path - the path to extract the attribute names from
omitLeafName - The last entry in the list will be the name of the attribute specified by the path if this flag is false. If this flag is true it will be omitted (so in the above example the returned list would contain {"group","subgroup"} only.
Returns:
the attribute names specified in the path, in descending order. For example spec/group/mysubgroup/myattr would return a List of {"group", "mysubgroup", "myattr"} (if omitLeafName is false). If the attribute names are qualified (e.g. "myattr#0") they will be returned in that same format with the index still attached. This can be removed with stripAttributeName() method
Throws:
PIMInvalidPathException - if isValidPath(path) would return false
java.lang.IllegalArgumentException - if any of the parameters is null or empty
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use

getAttributeName

java.lang.String getAttributeName(java.lang.String path)
Extract the name of the attribute identified by a path

Parameters:
path - the path to extract the attribute name from
Returns:
the attribute name specified by the path. If the attribute name is qualified (e.g. "myattr#0") it will be returned in that same format with the index still attached. This can be removed with stripAttributeName() method
Throws:
PIMInvalidPathException - if isValidPath(path) would return false
java.lang.IllegalArgumentException - if any of the parameters is null or empty
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use

createAttributePath

java.lang.String createAttributePath(java.lang.String specName,
                                     java.util.ArrayList<java.lang.String> attributeNames)
Construct an attribute path from a spec name, and a list of attribute names. For example passing "myspec" and {"group","subgroup","myattr"} would return "myspec/group/subgroup/myattr"

Parameters:
specName - the name of the spec
attributeNames - the list of attribute names. These can be qualified eg "myattr#3" if needed. The attribute names must be in the correct order and the last attribute name must be the name of the attribute to be addressed by this path
Returns:
a path constructed from the passed in spec name and attribute name list. This path has not been validated for existence of each attribute/spec name - this can be done using isValidPath()
Throws:
java.lang.IllegalArgumentException - if any of the parameters is null or empty
PIMInternalException - if an internal error occurs

stripAttributeName

java.lang.String stripAttributeName(java.lang.String nameOrPath)
Remove qualifier from attribute name or path

Parameters:
nameOrPath - an attribute name or path containing an index e.g, "myattr#4"
Returns:
the attribute name without the index e.g. "myattr". If the attribute name does not have an index or is not in the correct format, it will be returned unmodified.
Throws:
java.lang.IllegalArgumentException - if nameOrPath is null or empty
PIMInternalException - if an internal error occurs

qualifyAttributeName

java.lang.String qualifyAttributeName(java.lang.String nameOrPath,
                                      int index)
Qualify an attribute name or path

Parameters:
nameOrPath - an attribute name or path without an index e.g, "myattr"
index - an index to be added
Returns:
the attribute name with the index added e.g. "myattr#4". If the attribute name already has an index or is not suitable for qualification, it will be returned unmodified.
Throws:
java.lang.IllegalArgumentException - if any of the parameters is null or empty
PIMInternalException - if an internal error occurs