com.ibm.pim.hierarchy.category
Interface Category

All Superinterfaces:
AttributeOwner

public interface Category
extends AttributeOwner

Interface for Category object (belongs to a Hierarchy, and groups Items)

Since:
6.0.0

Nested Class Summary
static class Category.SaveResult
          Describes the Category Status after a Save operation
 
Field Summary
static java.lang.String copyright
           
 
Method Summary
 void addChild(Category childCategory)
          Adds a category as a child of this category.
 void addItemSecondarySpec(SecondarySpec spec, boolean addToChildCategories, boolean addAcrossMapping)
          Associates a secondary item spec to this Category.
 void addItemSecondarySpec(SecondarySpec spec, java.util.Collection<Catalog> catalogs, boolean addToChildCategories, boolean addAcrossMapping)
          Associates a secondary item spec to this Category.
 void addSecondarySpec(SecondarySpec spec)
          Associates a secondary spec defining this category’s attributes.
 void delete()
          Deletes the given category.
 CollaborationObject getCheckedOutCategory(CategoryCollaborationArea categoryCollaborationArea)
          Returns the CollaborationObject in the CollaborationArea corresponding to the given Category
 java.util.Collection<Category> getChildren()
          Returns the categories immediately below this category.
 java.util.Collection<Category> getChildren(Catalog catalog, boolean ordered, boolean restrictToSubtreeWithItems)
          Returns the categories immediately below this category.
 java.util.Collection<CollaborationArea> getCollaborationAreas()
          Returns all the collaboration areas that this category is checked out to If the category is not checked out to any collaboration areas, an empty Collection will be returned.
 PIMCollection<Category> getDescendents()
          Returns all the descendants of this category.
 java.lang.String getDisplayName()
          Returns the name of this Category object
 java.util.Collection<java.lang.String> getFullPaths(boolean includeRootName)
          Returns the full name paths of this Category.
 java.util.Collection<java.lang.String> getFullPaths(java.lang.String delimiter, boolean includeRootName)
          Returns the full name paths of this Category.
 Hierarchy getHierarchy()
          Returns the Hierarchy object containing this Category object.
 PIMCollection<Item> getItems(Catalog catalog)
          Returns the items associated with this category in the given catalog.
 PIMCollection<Item> getItems(Catalog catalog, boolean ordered)
          Returns the items associated with this category in the given catalog.
 java.util.Collection<SecondarySpec> getItemSecondarySpecs()
          Returns the item secondary specs associated with this category.
 java.util.Collection<SecondarySpec> getItemSecondarySpecs(Catalog catalog)
          Returns the item secondary specs associated with this category applied to items in the given catalog.
 int[] getLevels()
          Returns the levels of this category in an array of Integers.
 java.util.Collection<Organization> getOrganizationsMappedTo()
          Return a collection of Organizations this category is mapped to
 Category getParent()
          Returns this category's parent.
 java.util.Collection<Category> getParents()
          Returns the parent categories of the given Category.
 java.lang.String getPrimaryKey()
          Return the primary key of this Category
 Category.SaveResult getSaveResult()
          Returns an enumeration of the net effect of the last save on this category.
 java.util.Collection<SecondarySpec> getSecondarySpecs()
          Returns the secondary specs defining this category’s attributes.
 boolean hasChildren()
          Determines if the given category has any children.
 boolean isCheckedOut()
          Identifies if this category is checked to one or more collaboration areas
 boolean isRoot()
          Identifies whether this Category is the root Category of the Hierarchy it lives within
 void mapToOrganization(Organization organization)
          Maps this category to the given Organization
 void removeChild(Category childCategory)
          Remove the given child Category from this category's children.
 void removeItemSecondarySpec(SecondarySpec spec)
          Disassociates a secondary item spec to from this Category.
 void removeSecondarySpec(SecondarySpec spec)
          Disassociates a secondary spec defining this category’s attributes.
 ValidationErrors validate()
          Validates the category.
 
Methods inherited from interface com.ibm.pim.attribute.AttributeOwner
getAttributeChangesComparedTo, getAttributeChangesSinceLastSave, getAttributeInstance, getAttributeValue, getOriginalAttributeOwner, getRootAttributeInstance, getRootAttributeInstances, getSpecs, isComparable, setAttributeValue
 

Field Detail

copyright

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

addChild

void addChild(Category childCategory)
Adds a category as a child of this category. No error is returned if the category already exists as a child.

Parameters:
childCategory - the category to be added as a child
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have equivalent of Permission.HIERARCHY_RECATEGORIZE_HIERARCHY_NODES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

addItemSecondarySpec

void addItemSecondarySpec(SecondarySpec spec,
                          boolean addToChildCategories,
                          boolean addAcrossMapping)
Associates a secondary item spec to this Category. Items from all the catalogs are affected by the spec.

Parameters:
spec - the secondary spec to be associated
addToChildCategories - if true, adds the item secondary spec to the child categories as well. The spec is applied to the child categories on save of the hierarchy.
addAcrossMapping - if true, adds the item secondary spec to the categories mapped to this category. The spec is applied to the mapped categories on save of the hierarchy.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have equivalent of Permission.HIERARCHY_MODIFY_HIERARCHY_NODE_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

addItemSecondarySpec

void addItemSecondarySpec(SecondarySpec spec,
                          java.util.Collection<Catalog> catalogs,
                          boolean addToChildCategories,
                          boolean addAcrossMapping)
Associates a secondary item spec to this Category. Only items from the passed in catalogs are affected by the spec.

Parameters:
spec - the secondary spec to be associated
catalogs - list of catalogs to be affected by the spec
addToChildCategories - if true, adds the item secondary spec to the child categories as well. The spec is applied to the child categories on save of the category tree.
addAcrossMapping - if true, adds the item secondary spec to the categories mapped to this category. The spec is applied to the mapped categories on save of the category tree.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have equivalent of Permission.HIERARCHY_MODIFY_HIERARCHY_NODE_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

addSecondarySpec

void addSecondarySpec(SecondarySpec spec)
Associates a secondary spec defining this category’s attributes.

Parameters:
spec - the secondary spec to be associated
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have equivalent of Permission.HIERARCHY_MODIFY_HIERARCHY_NODE_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

delete

void delete()
Deletes the given category. Save method on the containing Hierarchy object must be called to persist this deletion to the database.

Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have equivalent of Permission.HIERARCHY_DELETE_HIERARCHY_NODES
java.lang.UnsupportedOperationException - if this is a root category

getCheckedOutCategory

CollaborationObject getCheckedOutCategory(CategoryCollaborationArea categoryCollaborationArea)
Returns the CollaborationObject in the CollaborationArea corresponding to the given Category

Parameters:
categoryCollaborationArea - 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:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use.
java.lang.UnsupportedOperationException - if the collaboration area is not one of those in getCollaborationAreas() collection or if this object is not checked out
java.lang.IllegalArgumentException - if any of the parameters is null

getChildren

java.util.Collection<Category> getChildren()
Returns the categories immediately below this category.

Returns:
a Collection of Category objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - reserved for future use

getChildren

java.util.Collection<Category> getChildren(Catalog catalog,
                                           boolean ordered,
                                           boolean restrictToSubtreeWithItems)
Returns the categories immediately below this category.

Parameters:
catalog - the catalog to use
ordered - If true and if the catalog supports ordering, then return the child categories in catalog order.
restrictToSubtreeWithItems - If true, only return categories that have items in their sub-trees.
Returns:
a Collection of Category objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have on the given catalog the equivalent of Permission.CATALOG_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

getCollaborationAreas

java.util.Collection<CollaborationArea> getCollaborationAreas()
Returns all the collaboration areas that this category is checked out to If the category is not checked out to any collaboration areas, an empty Collection will be returned.

Returns:
a Collection of Collaboration Areas
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use.

getDescendents

PIMCollection<Category> getDescendents()
Returns all the descendants of this category.

Returns:
a PIMCollection of Category objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - reserved for future use

getFullPaths

java.util.Collection<java.lang.String> getFullPaths(boolean includeRootName)
Returns the full name paths of this Category.

Parameters:
includeRootName - If true, the returned full paths include the root category name.
Returns:
List of paths
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use

getFullPaths

java.util.Collection<java.lang.String> getFullPaths(java.lang.String delimiter,
                                                    boolean includeRootName)
Returns the full name paths of this Category.

Parameters:
delimiter - The delimiter to be used in the full paths that are returned.
includeRootName - If true, the returned full paths include the root category name.
Returns:
Collection of paths for this Category
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation
java.lang.IllegalArgumentException - if delimiter is null or empty

getItems

PIMCollection<Item> getItems(Catalog catalog)
Returns the items associated with this category in the given catalog.

Parameters:
catalog - The catalog whose items should be returned.
Returns:
a PIMCollection of Item objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have on the given catalog the equivalent of Permission.CATALOG_VIEW_ITEMS
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

getItems

PIMCollection<Item> getItems(Catalog catalog,
                             boolean ordered)
Returns the items associated with this category in the given catalog. If the catalog supports ordering then the items are returned in catalog order if requested.

Parameters:
catalog - The catalog whose items should be returned.
ordered - If true and if the catalog supports ordering, then the items are returned in catalog order.
Returns:
a PIMCollection of Item objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have on the given catalog the equivalent of Permission.CATALOG_VIEW_ITEMS If the user does not have on the given catalog the equivalent of Permission.CATALOG_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

getItemSecondarySpecs

java.util.Collection<SecondarySpec> getItemSecondarySpecs()
Returns the item secondary specs associated with this category.

Returns:
a Collection of Spec objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use

getItemSecondarySpecs

java.util.Collection<SecondarySpec> getItemSecondarySpecs(Catalog catalog)
Returns the item secondary specs associated with this category applied to items in the given catalog.

Parameters:
catalog - the catalog
Returns:
a Collection of Spec objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

getLevels

int[] getLevels()
Returns the levels of this category in an array of Integers.

Returns:
List of levels
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use

getParent

Category getParent()
Returns this category's parent. If there are multiple parents, only the first one is returned.

Returns:
the parent Category
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation
java.lang.UnsupportedOperationException - if this is a root category

getParents

java.util.Collection<Category> getParents()
Returns the parent categories of the given Category.

Returns:
a collection of all parent categories
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user is not allowed to perform this operation
java.lang.UnsupportedOperationException - if this is a root category

getSecondarySpecs

java.util.Collection<SecondarySpec> getSecondarySpecs()
Returns the secondary specs defining this category’s attributes.

Returns:
Collection of Spec objects.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use

getSaveResult

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

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

hasChildren

boolean hasChildren()
Determines if the given category has any children.

Returns:
Returns true if the category has any children.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use

isCheckedOut

boolean isCheckedOut()
Identifies if this category is checked to one or more collaboration areas

Returns:
true if this object is checked out to one or more collaboration areas, false otherwise
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use

validate

ValidationErrors validate()
Validates the category.

Returns:
A ValidationErrors object containing the list of validation errors for this category or null if no validation errors were found.
Throws:
PIMInternalException - If an internal error occurs.
PIMAuthorizationException - reserved for future use

removeChild

void removeChild(Category childCategory)
Remove the given child Category from this category's children. However, orphaned categories are not supported. That means, the child should have more than one one parent before a child can be removed from a parent category.

Parameters:
childCategory - the child category to remove.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have equivalent of Permission.HIERARCHY_RECATEGORIZE_HIERARCHY_NODES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

removeItemSecondarySpec

void removeItemSecondarySpec(SecondarySpec spec)
Disassociates a secondary item spec to from this Category.

Parameters:
spec - the secondary spec to be disassociated
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use Permission.HIERARCHY_MODIFY_HIERARCHY_NODE_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

removeSecondarySpec

void removeSecondarySpec(SecondarySpec spec)
Disassociates a secondary spec defining this category’s attributes.

Parameters:
spec - the secondary spec to be disassociated
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - Reserved for future use Permission.HIERARCHY_MODIFY_HIERARCHY_NODE_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

getOrganizationsMappedTo

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

Returns:
Collection of Organization objects
Throws:
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use

mapToOrganization

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

Parameters:
organization - object to map the category to
Throws:
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

getDisplayName

java.lang.String getDisplayName()
Returns the name of this Category object

Returns:
The name of the Category object as a String
Throws:
PIMInternalException - if an internal error occurs

getHierarchy

Hierarchy getHierarchy()
Returns the Hierarchy object containing this Category object.

Returns:
the Hierarchy object to which this Category object belongs
Throws:
PIMInternalException - if an internal error occurs
PIMAuthorizationException - Reserved for future use

isRoot

boolean isRoot()
Identifies whether this Category is the root Category of the Hierarchy it lives within

Returns:
true if this Category is the root category of its Hierarchy, otherwise false
Throws:
PIMInternalException - if an internal error occurs

getPrimaryKey

java.lang.String getPrimaryKey()
Return the primary key of this Category

Returns:
The primary key for this Category represented as a String
Throws:
PIMInternalException - if an internal error occurs