com.ibm.pim.interfaces.item
Interface Item


public interface Item

Read-write interface for Item object.


Field Summary
static java.lang.String copyright
           
 
Method Summary
 void addAttributeOccurrence(Category location, java.lang.String path)
          Add an occurrence to a multi-occurrence or grouping attribute.
 void addAttributeOccurrence(java.lang.String path)
          Add an occurrence to a multi-occurrence or grouping attribute.
 void addToCategory(Category category)
          Add an item to a category.
 void clearAttribute(Category location, java.lang.String path)
          Clear an attribute such that it still exists but contains no value.
 void clearAttribute(java.lang.String path)
          Clear an attribute such that it still exists but contains no value.
 void delete()
          Deletes the item from the Product Information Manager.
 void deleteAttributeOccurrence(Category location, java.lang.String path)
          Delete an occurrence from an attribute.
 void deleteAttributeOccurrence(java.lang.String path)
          Delete an occurrence from an attribute.
 java.lang.Object getAttribute(Category location, java.lang.String path)
          Get an attribute from a location.
 java.lang.Object getAttribute(java.lang.String path)
          Get an attribute value.
 int getAttributeOccurrenceCount(Category location, java.lang.String path)
          Get the number of occurrences in a multi-occurrence attribute or the number of child attributes in a grouping node.
 int getAttributeOccurrenceCount(java.lang.String path)
          Get the number of occurrences in a multi-occurrence attribute or the number of child attributes in a grouping node.
 Catalog getCatalog()
          Returns the catalog to which this item belongs.
 PIMCollection getCategories()
          Returns the categories to which this item belongs.
 java.lang.String getDisplayName()
          Returns the display name.
 PIMCollection getLocationHierarchies()
          Returns all the location hierarchies which are available on this catalog for this item, regardless of whether it has stored any data in them.
 java.lang.String getPrimaryKey()
          Returns the primary key.
 PIMCollection getSpecs()
          Returns the specs in which this item participates.
 ValidationErrors getValidationErrors()
          Returns the validation errors from the last isValid(), delete() or save() call.
 boolean hasLocationData(Category location)
          Returns true if the location contains any data.
 boolean isAttributeInherited(Category location, java.lang.String path)
          Returns true if the attribute is set to inherit a value.
 boolean isLocationAvailable(Category location)
          Returns true if the given location is available in this item.
 boolean isValid()
          Returns true if the item has no validation errors.
 void removeFromCategory(Category category)
          Remove an item from a category.
 void resetAttribute(Category location, java.lang.String path)
          Reset the attribute to its default value.
 void resetAttribute(java.lang.String path)
          Reset the attribute to its default value.
 void save()
          Saves the item.
 void setAttribute(Category location, java.lang.String path, java.lang.Object value)
          Set an attribute at a location.
 void setAttribute(java.lang.String path, java.lang.Object value)
          Set an attribute value on an item.
 void setAttributeInherited(Category location, java.lang.String path, boolean inherit)
          Set the inheritence state of a location attribute.
 void setLocationAvailable(Category location, boolean isAvailable, boolean recursive)
          Set the availability of a location.
 

Field Detail

copyright

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

addToCategory

public void addToCategory(Category category)
                   throws PIMInternalException,
                          PIMAuthorizationException,
                          java.lang.IllegalArgumentException
Add an item to a category.

Parameters:
category - Must be one which belongs to a hierarchy contained by the catalog which contains the item.

If the item was already mapped to the category then no change will take place.

Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation

removeFromCategory

public void removeFromCategory(Category category)
                        throws PIMInternalException,
                               PIMAuthorizationException
Remove an item from a category.

Parameters:
category - There will be no effect if the item does not belong to the given category.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation

setLocationAvailable

public void setLocationAvailable(Category location,
                                 boolean isAvailable,
                                 boolean recursive)
                          throws PIMInternalException,
                                 PIMAuthorizationException
Set the availability of a location.

Parameters:
location - A Category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's Catalog.

The root Category is a valid location - it can be used to recursively set the entire set of locations for a Hierarchy as available or unavailable.

isAvailable -
recursive - If true, then availability is set on all descendent locations. If false, availability is only set on the given location.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation

hasLocationData

public boolean hasLocationData(Category location)
                        throws PIMInternalException,
                               PIMAuthorizationException
Returns true if the location contains any data.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
Returns:
true if the location contains any data.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation

setAttribute

public void setAttribute(java.lang.String path,
                         java.lang.Object value)
                  throws PIMInternalException,
                         PIMAuthorizationException
Set an attribute value on an item. The type of the input Object must be compatible with the attribute type as shown in the table below.

Individual Occurrences on a multi-Occurrence node have to be set seperately using paths which point to those particular Occurrences. For instance, the second Occurrence on a multi-Occurrence attribute which already has one Occurrence can be set by the command sequence.

 item.addAttributeOccurrence("exampleSpec/MultiOccSpecNode");
 item.setAttribute("exampleSpec/MultiOccSpecNode#1", "myValue");
 

Values which are valid in the conversion table but do not conform to the correct format (for example, a string beginning with "xml://" for an Image URL) will cause a validation error on delete(), isValid() or save()

Parameters:
path - A path to an existing attribute.
value - The value to set. A null argument will unset the attribute.

Java input types corresponding to WPC types are in the table below.

Attribute typeJava type Notes
Binary String This is the file name as stored in the PIM. It cannot contain any of the characters !@$%^&()=+
Currency Number The method Number.doubleValue() will be called to transform the Number into a double. The value will not be rounded in storage.
Date Date
Flag Boolean
Image String This is the file name as stored in the PIM. The String must end with the character sequence ".gif" or ".jpg", ignoring case.
Image URL String The String must start with the character sequence "http://", "https://" or "ftp://", ignoring case.
Integer Number The method Number.intValue() will be called to transform the Number into an integer. This may mean that a floating point value is truncated rather than rounded (e.g. passing Double(43.56) as an argument will set 43 as the attribute value rather than 44.
Lookup Table String The key given must be a valid key in the lookup table used by this attribute.
Number Number The method Number.doubleValue() will be called to transform the Number into a double.
Number Enumeration Number The number set must match one of the possible enumerations or be null. The method Number.doubleValue() will be called to transform the Number into a double.
Password String
Relationship Item The Item to which this relationship points.
Sequence N/A Cannot be set.
String String
String Enumeration String
Thumbnail Image String This is the file name as stored in the PIM. The String must end with the character sequence ".gif" or ".jpg", ignoring case.
Thumbnail Image URL String The String must start with the character sequence "http://", "https://" or "ftp://", ignoring case.
Timezone String The timezone String given must match one of the timezone enumerations. XXX See yet to be written Timezone factory code
URL String The String must start with the character sequence "http://", "https://" or "ftp://", ignoring case.

Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

setAttribute

public void setAttribute(Category location,
                         java.lang.String path,
                         java.lang.Object value)
                  throws PIMInternalException,
                         PIMAuthorizationException
Set an attribute at a location.

See setAttribute(String, Object) for value types and formats.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to an existing attribute.
value - The value to set. A null argument will unset the attribute.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

resetAttribute

public void resetAttribute(java.lang.String path)
                    throws PIMInternalException,
                           PIMAuthorizationException
Reset the attribute to its default value. If the attribute does not have a default value then it is cleared (equivalent to calling clearAttribute(String)).

Parameters:
path - A path to an existing attribute.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

resetAttribute

public void resetAttribute(Category location,
                           java.lang.String path)
                    throws PIMInternalException,
                           PIMAuthorizationException
Reset the attribute to its default value. If the attribute does not have a default value then it is cleared (equivalent to calling clearAttribute(Category, String).

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to an existing attribute.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

clearAttribute

public void clearAttribute(java.lang.String path)
                    throws PIMInternalException,
                           PIMAuthorizationException
Clear an attribute such that it still exists but contains no value.

Parameters:
path - A path to an attribute to clear.

It is possible to clear attributes which do not yet have an Occurrence (a single instance attribute which does not yet have a value or a multi-Occurrence attribute where the Occurrence named is not yet instantiated). In these cases, the attribute will be instantiated with an empty value.

Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

clearAttribute

public void clearAttribute(Category location,
                           java.lang.String path)
                    throws PIMInternalException,
                           PIMAuthorizationException
Clear an attribute such that it still exists but contains no value.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to an attribute to clear.

It is possible to clear attributes which do not yet have an Occurrence (a single instance attribute which does not yet have a value or a multi-Occurrence attribute where the Occurrence named is not yet instantiated). In these cases, the attribute will be instantiated with an empty value.

Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

setAttributeInherited

public void setAttributeInherited(Category location,
                                  java.lang.String path,
                                  boolean inherit)
                           throws PIMInternalException,
                                  PIMAuthorizationException
Set the inheritence state of a location attribute.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path which points to an attribute at the given location which is capable of inheriting values.
inherit - true will cause the attribute at the given location to always inherit from its parent location; false will set this attribute to never inherit a value.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getAttribute

public java.lang.Object getAttribute(java.lang.String path)
                              throws PIMInternalException,
                                     PIMAuthorizationException
Get an attribute value.

Multi-Occurrence attributes will be returned as a java.util.List of Occurrences. You can determine whether a particular attribute is single or multi-Occurrence by calling getAttributeOccurrenceCount(String).

Parameters:
path - A path to an existing attribute or a multi-Occurrence parent attribute.
Returns:
The attribute value as an Object. The type of that Object corresponds to the attribute types as follows

Attribute typeJava type Notes
Binary String This is the file name
Currency Double The currency symbol needs to be retrieved from the SpecNode
Date Date
Flag Boolean
Image String This is the file name
Image URL String
Integer Integer
Lookup Table String This is the lookup table entry key. It is left to the caller to retrieve values from the appropriate lookup table
Number Double
Number Enumeration Double
Password String Password is returned in the clear
Relationship Item The Item which this relationship points to
Sequence Integer
String String
String Enumeration String
Thumbnail Image String This is the file name
Thumbnail Image URL String
Timezone String Timezone is returned in WPC native form
URL String

It is left to the caller to cast the returned Object to the appropriate type.

Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getAttribute

public java.lang.Object getAttribute(Category location,
                                     java.lang.String path)
                              throws PIMInternalException,
                                     PIMAuthorizationException
Get an attribute from a location. See getAttribute(String) for return types.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to an existing attribute or a multi-occurrence parent attribute.
Returns:
The attribute value as an Object
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

addAttributeOccurrence

public void addAttributeOccurrence(java.lang.String path)
                            throws PIMInternalException,
                                   PIMAuthorizationException
Add an occurrence to a multi-occurrence or grouping attribute. To subsequently set values the caller will need to invoke setAttribute(String, Object).

Parameters:
path - A path to a multi-occurrence or grouping attribute which does not already contain the maximum number of possible occurrences as specified in the spec.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

addAttributeOccurrence

public void addAttributeOccurrence(Category location,
                                   java.lang.String path)
                            throws PIMInternalException,
                                   PIMAuthorizationException
Add an occurrence to a multi-occurrence or grouping attribute. To subsequently set values the caller will need to invoke setAttribute(Category, String, Object).

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to a multi-occurrence or grouping attribute which does not already contain the maximum number of possible occurrences as specified in the spec.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

deleteAttributeOccurrence

public void deleteAttributeOccurrence(java.lang.String path)
                               throws PIMInternalException,
                                      PIMAuthorizationException
Delete an occurrence from an attribute.

Parameters:
path - A path to the specific occurrence to be deleted.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

deleteAttributeOccurrence

public void deleteAttributeOccurrence(Category location,
                                      java.lang.String path)
                               throws PIMInternalException,
                                      PIMAuthorizationException
Delete an occurrence from an attribute.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to the specific occurrence to be deleted.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getAttributeOccurrenceCount

public int getAttributeOccurrenceCount(java.lang.String path)
                                throws PIMInternalException,
                                       PIMAuthorizationException
Get the number of occurrences in a multi-occurrence attribute or the number of child attributes in a grouping node.

Parameters:
path - A path to a multi-occurrence attribute, a grouping attribute or a single occurrence attribute.
Returns:
The number of occurrences of the attribute.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getAttributeOccurrenceCount

public int getAttributeOccurrenceCount(Category location,
                                       java.lang.String path)
                                throws PIMInternalException,
                                       PIMAuthorizationException
Get the number of occurrences in a multi-occurrence attribute or the number of child attributes in a grouping node.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to a multi-occurrence attribute, a grouping attribute or a single occurrence attribute.
Returns:
The number of occurrences of the attribute.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

isLocationAvailable

public boolean isLocationAvailable(Category location)
                            throws PIMInternalException,
                                   java.lang.IllegalArgumentException
Returns true if the given location is available in this item.

Parameters:
location - Any category.
Returns:
true if the location is available for this item, false if the location is currently unavailable or is in a hierarchy which is not attached as a location hierarchy to this item's containing catalog.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
java.lang.IllegalArgumentException - If the user is not allowed to perform this operation

isAttributeInherited

public boolean isAttributeInherited(Category location,
                                    java.lang.String path)
                             throws PIMInternalException,
                                    PIMAuthorizationException,
                                    java.lang.IllegalArgumentException
Returns true if the attribute is set to inherit a value.

Parameters:
location - A category which belongs to one of this item's location hierarchies. Location hierarchies are explicitly attached in the item's catalog.
path - A path to an existing attribute.
Returns:
true if the location attribute is set to inherit a value.
Throws:
java.lang.IllegalArgumentException
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getCatalog

public Catalog getCatalog()
                   throws PIMInternalException,
                          PIMAuthorizationException
Returns the catalog to which this item belongs.

Returns:
A catalog
Throws:
PIMInternalException
PIMAuthorizationException

getCategories

public PIMCollection getCategories()
                            throws PIMInternalException,
                                   PIMAuthorizationException
Returns the categories to which this item belongs.

Returns:
The Collection of Category to which this item belongs. If the item does not belong to any categories (in other words, it is unassigned), then an empty Collection is returned.
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getPrimaryKey

public java.lang.String getPrimaryKey()
                               throws PIMInternalException,
                                      PIMAuthorizationException
Returns the primary key.

Returns:
The primary key
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getDisplayName

public java.lang.String getDisplayName()
                                throws PIMInternalException,
                                       PIMAuthorizationException
Returns the display name.

Returns:
The display name. If there is no display name set on this item then the primary key is returned.
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getLocationHierarchies

public PIMCollection getLocationHierarchies()
                                     throws PIMInternalException,
                                            PIMAuthorizationException
Returns all the location hierarchies which are available on this catalog for this item, regardless of whether it has stored any data in them.

Returns:
A Collection of Hierarchy
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getSpecs

public PIMCollection getSpecs()
                       throws PIMInternalException,
                              PIMAuthorizationException
Returns the specs in which this item participates.

Returns:
A Collection of Spec
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

isValid

public boolean isValid()
                throws PIMInternalException,
                       PIMAuthorizationException
Returns true if the item has no validation errors. If there are validation errors, detailed results can be retrieved by the getValidationErrors() method.

Returns:
true if the item has no validation errors, false if there are validation errors.
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

save

public void save()
          throws PIMValidationException,
                 PIMInternalException,
                 PIMAuthorizationException
Saves the item. This must be done for any changes to the item to take effect.

Throws:
PIMValidationException - If there are any validation errors. The detailed results can be retrieved by the getValidationErrors() method.
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

delete

public void delete()
            throws PIMValidationException,
                   PIMInternalException,
                   PIMAuthorizationException
Deletes the item from the Product Information Manager. If there are validation errors these can be retrieved via getValidationErrors().

Throws:
PIMValidationException - If there are any validation errors. The detailed results can be retrieved by the getValidationErrors() method.
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user is not allowed to perform this operation

getValidationErrors

public ValidationErrors getValidationErrors()
                                     throws PIMAuthorizationException
Returns the validation errors from the last isValid(), delete() or save() call.

Any particular ValidationErrors object retrieved by this method is a snapshot of the validation errors at the last isValid(), delete() or save() call. Therefore, subsequent changes to the Item will not affect existing ValidationErrors objects. Only freshly retrieved ValidationErrors objects will reflect the latest attribute changes.

Returns:
A ValidationErrors object containing the validation errors from the last isValid(), delete() or save() call. If there are no validation errors, a ValidationErrors object will still be returned but ValidationErrors.hasErrors() will return false.
Throws:
PIMAuthorizationException - If the user is not allowed to perform this operation