com.ibm.pim.catalog.item
Interface Item

All Superinterfaces:
AttributeOwner, ExtendedAttributeOwner

public interface Item
extends ExtendedAttributeOwner

Represents the Item object in the system.

Since:
6.0.0

Nested Class Summary
static class Item.SaveResult
          Describes the Item Status after a Save operation
 
Field Summary
static java.lang.String copyright
           
 
Method Summary
 void addToCategory(Category category)
          Deprecated. use mapToCategory() instead.
 void delete()
          Deletes the item
 Catalog getCatalog()
          Returns the catalog to which this item belongs.
 java.util.Collection<Category> getCategories()
          Returns all the categories to which this item belongs.
 java.util.Collection<Category> getCategories(Hierarchy hierarchy)
          Returns all the categories of the Hierarchy which is passed in, to which this item belongs.
 CollaborationItem getCheckedOutItem(ItemCollaborationArea itemCollaborationArea)
          Returns the item's collaboration object in the collaboration area that the item is checked out to.
 java.util.Collection<CollaborationArea> getCollaborationAreas()
          Returns the collaboration areas that the item is checked out to.
 java.lang.String getDisplayName()
          Returns the display name.
 java.util.Collection<Item> getLinkedItems()
          Retrieves all of the Items that are linked to this item's primary key.
 java.util.Collection<Hierarchy> 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.util.Collection<Organization> getOrganizationsMappedTo()
          Return a collection of all Organizations this item is mapped to
 java.lang.String getPrimaryKey()
          Returns the primary key.
 PIMCollection<Item> getRelatedItems(Catalog filter, boolean toOrFrom)
          Retrieves all of the Items that this item is connected to via a relationship link on other items.
 Item.SaveResult getSaveResult()
          Returns an enumeration of the net effect of the last save on this item.
 java.lang.String getXMLRepresentation(Spec spec, boolean includePrimaryKeyValue, boolean addNameSpace, java.util.Collection<java.util.Locale> locales, java.util.Collection<AttributeCollection> attrGroups)
          Returns the XML Representation for the particular item.
 java.lang.String getXMLRepresentation(Spec spec, boolean includePrimaryKeyValue, boolean addNameSpace, java.util.Collection<java.util.Locale> locales, java.util.Collection<AttributeCollection> attrGroups, java.lang.String dateFormat)
          Returns the XML Representation for the particular item.
 boolean isCheckedOut()
          Determines if the item is checked out to a collaboration area.
 void mapToCategory(Category category)
          Map an item to a category.
 void mapToOrganization(Organization organization)
          Maps this item to the given Organization
 void moveToCategories(java.util.Collection<Category> categories)
          Move item from existing categories to new set of categories.
 void moveToCategoriesWithMapping(java.util.Collection<Category> categories)
          This method behaves exactly like Item.moveToCategories(Collection categories), the only difference being, even after the move to the new set of categories the mapping to the original category is maintained
 void removeFromCategory(Category category)
          Remove an item from a category.
 ExtendedValidationErrors save()
          Saves the item.
 void setCategorySpecificAttributeProcessing(boolean setEnabled)
          Set whether or not category specific attributes should be processed for the item Default would be true to process them
 void setPrimaryKey(java.lang.String primaryKey)
          Sets the primary key.
 ExtendedValidationErrors validate()
          Validates the item.
 
Methods inherited from interface com.ibm.pim.attribute.ExtendedAttributeOwner
executeNonPersistedScript, getAttributeChangesComparedTo, getAttributeChangesSinceLastSave, getAvailableLocations, getLocationAttributeInstance, getLocationAttributeValue, getLocationsHavingData, getRootLocationAttributeInstance, isAvailableInLocation, isAvailableInLocation, makeAvailableInLocation, makeAvailableInLocationRecursively, makeUnavailableInLocation, makeUnavailableInLocationRecursively, setLocationAttributeValue
 
Methods inherited from interface com.ibm.pim.attribute.AttributeOwner
getAttributeChangesComparedTo, getAttributeInstance, getAttributeValue, getLastModifiedTimeMillis, getOriginalAttributeOwner, getRootAttributeInstance, getRootAttributeInstances, getSpecs, isComparable, setAttributeValue
 

Field Detail

copyright

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

addToCategory

void addToCategory(Category category)
Deprecated. use mapToCategory() instead.

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 does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS

delete

void delete()
Deletes the item

Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_DELETE_ITEMS

getLinkedItems

java.util.Collection<Item> getLinkedItems()
Retrieves all of the Items that are linked to this item's primary key. This list is refined to contain only to those items from Catalogs the user has permission to view. The required permission is Permission.CATALOG_VIEW_ITEMS

Returns:
a Collection of the linked items
Throws:
PIMInternalException - If an internal error occurs

getRelatedItems

PIMCollection<Item> getRelatedItems(Catalog filter,
                                    boolean toOrFrom)
Retrieves all of the Items that this item is connected to via a relationship link on other items.

Parameters:
filter - A catalog which contains the items that contain a relationship link to or from this item
toOrFrom - If true only items in the filter catalog that have a relationship link to this item are returned. If false only items in the filter catalog that have a relationship link from this item are returned.
Returns:
a PIMCollection of the related items Please note this is a lazily instantiated collection
Throws:
PIMInternalException - if an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_VIEW_ITEMS
See Also:
for more info

getCatalog

Catalog getCatalog()
Returns the catalog to which this item belongs.

Returns:
A catalog
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_LIST

getCategories

java.util.Collection<Category> getCategories()
Returns all the categories to which this item belongs. Only categories that the user has access to are returned as prescribed by Permission.HIERARCHY_VIEW_HIERARCHY_NODES

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 - reserved for future use

getCategories

java.util.Collection<Category> getCategories(Hierarchy hierarchy)
Returns all the categories of the Hierarchy which is passed in, to which this item belongs.

Returns:
The Collection of Category of the Hierarchy 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.
java.lang.IllegalArgumentException - If the hierarchy argument is null
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES

getCheckedOutItem

CollaborationItem getCheckedOutItem(ItemCollaborationArea itemCollaborationArea)
Returns the item's collaboration object in the collaboration area that the item is checked out to.

Parameters:
itemCollaborationArea - - a collaboration area that this source object is checked out to
Returns:
the corresponding collaboration object in the specified collaboration area for this collaboration source object
Throws:
java.lang.UnsupportedOperationException - If the collaboration area is not one of those in getCollaborationAreas() collection or if this object is not checked out.

getCollaborationAreas

java.util.Collection<CollaborationArea> getCollaborationAreas()
Returns the collaboration areas that the item is checked out to.

Returns:
a Collection of collaboration areas that this item is checked out to. If the item is not checked out to any collaboration areas, an empty Collection will be returned

getDisplayName

java.lang.String getDisplayName()
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.

getOrganizationsMappedTo

java.util.Collection<Organization> getOrganizationsMappedTo()
Return a collection of all Organizations this item is mapped to

Returns:
Collection of Organization objects
Throws:
PIMInternalException - if an internal error occurs
PIMAuthorizationException - if the user is not authorized

getPrimaryKey

java.lang.String getPrimaryKey()
Returns the primary key.

Returns:
The primary key
Throws:
PIMInternalException - If an internal error occurs.

getSaveResult

Item.SaveResult getSaveResult()
Returns an enumeration of the net effect of the last save on this item. Possible values are UNKNOWN, ADDED, MODIFIED and DELETED.

Returns:
a SaveResult enumeration
Throws:
PIMInternalException - If an internal error occurs.

isCheckedOut

boolean isCheckedOut()
Determines if the item is checked out to a collaboration area.

Returns:
true if this object is checked out to one or more collaboration areas, false otherwise

validate

ExtendedValidationErrors validate()
Validates the item.

Returns:
An ExtendedValidationErrors object containing the list of validation errors for this item or null if no validation errors were found.
Throws:
PIMInternalException - If an internal error occurs.

mapToCategory

void mapToCategory(Category category)
                   throws PIMInvalidOperationException
Map an item to a category.

Parameters:
category - - The category to map the item to.
Throws:
PIMInternalException - If an internal error occurs
PIMInvalidOperationException - If map is not allowed by category
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS

mapToOrganization

void mapToOrganization(Organization organization)
Maps this item to the given Organization

Parameters:
organization - - The Organization object to map the item to
Throws:
PIMInternalException - if an internal error occurs
PIMAuthorizationException - if the user is not authorized

moveToCategories

void moveToCategories(java.util.Collection<Category> categories)
Move item from existing categories to new set of categories.

Parameters:
categories - - the categories to move the item to.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS
java.lang.IllegalArgumentException - If the categories argument is null

moveToCategoriesWithMapping

void moveToCategoriesWithMapping(java.util.Collection<Category> categories)
This method behaves exactly like Item.moveToCategories(Collection categories), the only difference being, even after the move to the new set of categories the mapping to the original category is maintained

Parameters:
categories - - collection of categories to move the item to.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS
java.lang.IllegalArgumentException - If the categories argument is null

removeFromCategory

void removeFromCategory(Category category)
Remove an item from a category.

Parameters:
category - - There will be no effect if the item does not belong to the given category.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS

save

ExtendedValidationErrors save()
Saves the item. This must be done for any changes to the item to take effect.

Returns:
An ExtendedValiadtionErrors object containing the list of validation errors for the item, or null if no validation errors were found.
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS

setCategorySpecificAttributeProcessing

void setCategorySpecificAttributeProcessing(boolean setEnabled)
Set whether or not category specific attributes should be processed for the item Default would be true to process them

Parameters:
setEnabled - To process them (default) or false to ignore processing them
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS

setPrimaryKey

void setPrimaryKey(java.lang.String primaryKey)
Sets the primary key.

Parameters:
primaryKey - - The primary key
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_MODIFY_ITEMS
java.lang.IllegalArgumentException - If the primary key argument is null

getLocationHierarchies

java.util.Collection<Hierarchy> 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. Only those hierarchies to which the user has access will be returned as prescribed by Permission.HIERARCHY_LIST

Returns:
A Collection of Hierarchy
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - If the user does not have the equivalent of Permission.CATALOG_ATTRIBUTES

getXMLRepresentation

java.lang.String getXMLRepresentation(Spec spec,
                                      boolean includePrimaryKeyValue,
                                      boolean addNameSpace,
                                      java.util.Collection<java.util.Locale> locales,
                                      java.util.Collection<AttributeCollection> attrGroups)
Returns the XML Representation for the particular item.

Parameters:
spec - - The Spec.
includePrimaryKeyValue - - Flag to determine whether to include Primary Key.
addNameSpace - - TFlag to determine whether to add name space.
locales - - Collection of Locales.
attrGroups - - Collection of Attribute Collections.
Returns:
the XML representation of the item.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use.
java.lang.IllegalStateException - if the object is not in a stable persisted state.
java.lang.IllegalArgumentException - if argument passed is null.

getXMLRepresentation

java.lang.String getXMLRepresentation(Spec spec,
                                      boolean includePrimaryKeyValue,
                                      boolean addNameSpace,
                                      java.util.Collection<java.util.Locale> locales,
                                      java.util.Collection<AttributeCollection> attrGroups,
                                      java.lang.String dateFormat)
Returns the XML Representation for the particular item.

Parameters:
spec - - The Spec.
includePrimaryKeyValue - - Flag to determine whether to include Primary Key.
addNameSpace - - Flag to determine whether to add name space.
dateFormat - - The value of Spec Nodes whose type is Date, will be formatted using the date format provided.
locales - - Collection of Locales.
attrGroups - - Collection of Attribute Collections.
Returns:
the XML representation of the item.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use.
java.lang.IllegalStateException - if the object is not in a stable persisted state.
java.lang.IllegalArgumentException - if argument passed is null or empty.