|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface AttributePathHelper
String attribute paths are used in MDMPIM for a number of purposes:
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:
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:
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:
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.
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 |
---|
static final java.lang.String copyright
Method Detail |
---|
boolean isValidPath(java.lang.String path)
path
- the String path to analyze
java.lang.IllegalArgumentException
- if path is null or empty
PIMInternalException
- if an internal error occurs
PIMAuthorizationException
- Reserved for future usejava.lang.String getSpecName(java.lang.String path)
path
- the path to extract the spec name from
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 usejava.util.List<java.lang.String> getAttributeNames(java.lang.String path, boolean omitLeafName)
path
- the path to extract the attribute names fromomitLeafName
- 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.
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 usejava.lang.String getAttributeName(java.lang.String path)
path
- the path to extract the attribute name from
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 usejava.lang.String createAttributePath(java.lang.String specName, java.util.ArrayList<java.lang.String> attributeNames)
specName
- the name of the specattributeNames
- 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
java.lang.IllegalArgumentException
- if any of the parameters is null or empty
PIMInternalException
- if an internal error occursjava.lang.String stripAttributeName(java.lang.String nameOrPath)
nameOrPath
- an attribute name or path containing an index e.g, "myattr#4"
java.lang.IllegalArgumentException
- if nameOrPath is null or empty
PIMInternalException
- if an internal error occursjava.lang.String qualifyAttributeName(java.lang.String nameOrPath, int index)
nameOrPath
- an attribute name or path without an index e.g, "myattr"index
- an index to be added
java.lang.IllegalArgumentException
- if any of the parameters is null or empty
PIMInternalException
- if an internal error occurs
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |