com.canto.cumulus

Class CategoryItemCollection

java.lang.Object

com.canto.cumulus.ItemCollection

com.canto.cumulus.CategoryItemCollection

All Implemented Interfaces:

java.lang.AutoCloseable, java.lang.Iterable<Item>

Direct Known Subclasses:

AllCategoriesItemCollection

public class CategoryItemCollection
extends ItemCollection

This class represents the categories of a Cumulus catalog. It allows access to the categories in two ways: as a tree of categories or as a flat list. The tree-related access is useful when your code displays the categories in a tree and allow the user to expand and collapse categories in the view. All tree-related methods contain "CategoryTree" in their name and usually get a parameter which specifies the categories of the tree that are assumed to be expanded.

Since:

8.0

Method Summary

Methods

Modifier and Type	Method and Description
CategoryItemCollection	clone() Create a clone of this collection.
int	countCategoryTreeItems(java.util.Set<java.lang.Integer> expandedCategoryIDs) Return the number of categories that would be visible in the category tree if the given categories are expanded.
int	countTotalCategoryTreeItems() Return the number of categories that would be visible in the category tree if all categories were expanded.
java.util.Set<java.lang.Integer>	findCategoryIDs(java.lang.String categoryName) Find categories by their name.
CategoryItem	getCategoryItemByID(int categoryID) Return a CategoryItem specified by ID.
CategoryItem	getCategoryTreeCatalogRootCategory() Get the CategoryItem that represents the root of the category tree of the given catalog.
CategoryItem	getCategoryTreeItemByIndex(int index, java.util.Set<java.lang.Integer> expandedCategoryIDs) Get the ID of the category specified by index in the tree assuming a set of categories being expanded.
int	getCategoryTreeItemIDByPath(CategoryItem parent, java.lang.String path) Returns the ID of the category with the given relative tree path underneath a given category.
int	getCategoryTreeItemIDByPath(java.lang.String path) Returns the ID of the category with the given tree path.
java.util.List<java.lang.Integer>	getCategoryTreeItemIDs(int startIndex, int count, java.util.Set<java.lang.Integer> expandedCategoryIDs, boolean excludeDisabledCategories) Get the IDs of all categories in the category tree assuming a set of categories being expanded.
int	getCategoryTreeItemIndex(int categoryItemID, java.util.Set<java.lang.Integer> expandedCategoryIDs) Return the index of a given category in the tree assuming a set of categories being expanded.
static java.lang.String	getCategoryTreePath(java.util.List<java.lang.String> categories) Construct a valid category tree path for the category specified by the list of category names.
java.util.Map<java.lang.Integer,java.lang.Integer>	getNumberOfAssignedRecords(java.util.Set<java.lang.Integer> categoryIDs, java.util.EnumSet<FindFlag> flags) Return statistics about how many records are assigned to a given set of categories.
boolean	hasCategoryTreeItem(int categoryItemID) Return whether the given category (specified by ID) is included in the category tree.
java.util.Iterator<Item>	iterator() Return an iterator that iterates over all category items in this collection using the tree hierarchy.
java.util.List<java.lang.Integer>	sortCategoryIDsAccordingToCategoryTree(java.util.Set<java.lang.Integer> categoryIDs) Reorder the given categories according to their position in the category tree.

Methods inherited from class com.canto.cumulus.ItemCollection

addCatalogingListener, addCollectionListener, addFilter, addFilter, addGlobalCatalogingListener, addGlobalCollectionListener, addItemByID, addItemsByID, catalogAsset, catalogAsset, catalogAsset, catalogAssets, catalogAssets, catalogAssets, close, createItem, createItem, equals, find, find, find, find, findAll, getCatalog, getCumulusSession, getItemByID, getItemCount, getItemIDs, getItemPosition, getItemTotalCount, getLayout, getMultiSorting, getSortDirection, getSorting, getTableName, hashCode, hasItem, matchIDs, moveItem, moveItemByID, removeAllItems, removeCatalogingListener, removeCollectionListener, removeFilter, removeGlobalCatalogingListener, removeGlobalCollectionListener, removeItemsByID, setFreesorted, setMultiSorting, setSortDirection, setSorting, updateItems, updateItems, updateWantedFields, updateWantedFields

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

clone

public CategoryItemCollection clone()

Create a clone of this collection. The cloned collection will contain the same categories as this collection.

Overrides:

clone in class ItemCollection

Returns:

The newly created clone of this collection.

getCategoryItemByID

public CategoryItem getCategoryItemByID(int categoryID)
                                 throws ItemNotFoundException,
                                        CumulusException

Return a CategoryItem specified by ID.

Parameters:

categoryID - The ID of the category item to be returned.

Returns:

The CategoryItem object requested.

Throws:

ItemNotFoundException - if the collection does not contain the given item.

CumulusException - on other errors.

See Also:

ItemCollection.hasItem(int), ItemCollection.addItemByID(int), ItemCollection.addItemsByID(java.util.List)

getCategoryTreeCatalogRootCategory

public CategoryItem getCategoryTreeCatalogRootCategory()

Get the CategoryItem that represents the root of the category tree of the given catalog. You can use this as a starting point to enumerate all categories in the tree hierarchy.

 private void walkCategoryTree (CategoryItem categoryItem)
 {
     CategoryItem childItem = categoryItem.getFirstChildCategoryItem ();
     while (childItem != null)
     {
         System.out.println ("Category: " + childItem.toString ());
         walkCategoryTree (childItem);
         childItem = childItem.getNextSiblingCategoryItem ();
     }
 }
 ...
 walkCategoryTree (categoryItemCollection.getCategoryTreeCatalogRootCategory ());
 

Returns:

The root CategoryItem of the category tree.

getNumberOfAssignedRecords

public java.util.Map<java.lang.Integer,java.lang.Integer> getNumberOfAssignedRecords(java.util.Set<java.lang.Integer> categoryIDs,
                                                                            java.util.EnumSet<FindFlag> flags)

Return statistics about how many records are assigned to a given set of categories. The numbers correspond to the number of record found by searching for the given categories.

Parameters:

categoryIDs - The IDs of the categories to return the number of assigned records for.

flags - The flags that control how the assignments are calculated.

Returns:

A map with the category ID as it's key and the number of assigned records as it's value.

countTotalCategoryTreeItems

public int countTotalCategoryTreeItems()

Return the number of categories that would be visible in the category tree if all categories were expanded. The count includes the catalog root category.

Returns:

the total number of categories including the catalog root category.

countCategoryTreeItems

public int countCategoryTreeItems(java.util.Set<java.lang.Integer> expandedCategoryIDs)

Return the number of categories that would be visible in the category tree if the given categories are expanded. The count includes the catalog root category.

Parameters:

expandedCategoryIDs - The IDs of the categories that should be treated as expanded

Returns:

the number of visible categories including the catalog root category

hasCategoryTreeItem

public boolean hasCategoryTreeItem(int categoryItemID)

Return whether the given category (specified by ID) is included in the category tree.

Parameters:

categoryItemID - The ID of the category to look for.

Returns:

true if the given category is included in the category tree. Return false otherwise.

getCategoryTreeItemIDs

public java.util.List<java.lang.Integer> getCategoryTreeItemIDs(int startIndex,
                                                       int count,
                                                       java.util.Set<java.lang.Integer> expandedCategoryIDs,
                                                       boolean excludeDisabledCategories)

Get the IDs of all categories in the category tree assuming a set of categories being expanded. This method can be used to maintain a tree view of categories with some of the expanded and the rest of them collapsed. This method traverses the tree and returns the categories that can be found at specific positions in the tree where the catalog root category appears at index 0.

Parameters:

startIndex - The starting index for the categories. The catalog root category has index 0, the first top-level category has index 1 and so on.

count - The number of categories to return.

expandedCategoryIDs - The set of categories that should be taken as expanded meaning that this method looks into it's sub-categories.

excludeDisabledCategories - Pass true if you do not want to include disabled categories that are added to the tree after searching.

Returns:

The list of category ID for the categories in a given range of the tree.

See Also:

getCategoryTreeItemByIndex(int, java.util.Set)

getCategoryTreeItemByIndex

public CategoryItem getCategoryTreeItemByIndex(int index,
                                      java.util.Set<java.lang.Integer> expandedCategoryIDs)
                                        throws InvalidArgumentException

Get the ID of the category specified by index in the tree assuming a set of categories being expanded. This method can be used to maintain a tree view of categories with some of the expanded and the rest of them collapsed. This method traverses the tree and returns the category that can be found at the given position in the tree where the catalog root category appears at index 0.

Parameters:

index - The index for the category to return. The catalog root category has index 0, the first top-level category has index 1 and so on.

expandedCategoryIDs - The set of categories that should be taken as expanded meaning that this method looks into it's sub-categories.

Returns:

The ID of the category that can be found in the tree at the given position.

Throws:

InvalidArgumentException - if the index is out of range

See Also:

getCategoryTreeItemIDs(int, int, java.util.Set, boolean)

getCategoryTreeItemIndex

public int getCategoryTreeItemIndex(int categoryItemID,
                           java.util.Set<java.lang.Integer> expandedCategoryIDs)
                             throws InvalidArgumentException

Return the index of a given category in the tree assuming a set of categories being expanded.

Parameters:

categoryItemID - The ID of the category to find.

expandedCategoryIDs - The set of categories that should be taken as expanded meaning that this method looks into it's sub-categories.

Returns:

The index of the given category in the tree.

Throws:

InvalidArgumentException - if the given category ID is invalid.

sortCategoryIDsAccordingToCategoryTree

public java.util.List<java.lang.Integer> sortCategoryIDsAccordingToCategoryTree(java.util.Set<java.lang.Integer> categoryIDs)

Reorder the given categories according to their position in the category tree.

Parameters:

categoryIDs - The IDs of the categories to sort.

Returns:

A list of the given categories sorted by their position in the category tree.

findCategoryIDs

public java.util.Set<java.lang.Integer> findCategoryIDs(java.lang.String categoryName)

Find categories by their name. Please note that several categories can have the same name.

Parameters:

categoryName - The name to search for.

Returns:

The IDs of the categories that have the given name.

getCategoryTreeItemIDByPath

public int getCategoryTreeItemIDByPath(java.lang.String path)
                                throws InvalidArgumentException

Returns the ID of the category with the given tree path. Example: "$Sources:Volume:2009::05::18" specifies the category "2009:05:18" inside the category "Volume" inside the category "$Sources".

Parameters:

path - The path to the category (similar to paths in file systems) using colons as separators. Colons in category names need to be escaped by using a double colon character.

Returns:

The ID of the category that you specified by path.

Throws:

InvalidArgumentException - if the path does not specify an existing category.

getCategoryTreeItemIDByPath

public int getCategoryTreeItemIDByPath(CategoryItem parent,
                              java.lang.String path)
                                throws InvalidArgumentException

Returns the ID of the category with the given relative tree path underneath a given category.

Parameters:

parent - The parent category where the path starts. You can specify null to start at the root level.

path - The relative path from the parent category.

Returns:

The ID of the category that you specified by path.

Throws:

InvalidArgumentException - if the path does not specify an existing category.

getCategoryTreePath

public static java.lang.String getCategoryTreePath(java.util.List<java.lang.String> categories)

Construct a valid category tree path for the category specified by the list of category names. This method escapes colon characters appearing in category names correctly.

Parameters:

categories - A sorted list of category names starting at the top level that specifies the path to the category. Example: new String[] {"$Sources", "Volume", "2009:05:18"} specifies the category "2009:05:18" inside the category "Volume" inside the category "$Sources".

Returns:

The path to the category.

iterator

public java.util.Iterator<Item> iterator()

Return an iterator that iterates over all category items in this collection using the tree hierarchy. This allows you to use Java 5 for-each loops that simplify your source code:

 for (Item item : categoryItemCollection)
 {
    CategoryItem categoryItem = (CategoryItem) item;
    // use the categoryItem
 }
 

Specified by:

iterator in interface java.lang.Iterable<Item>

Overrides:

iterator in class ItemCollection

Returns:

An iterator for all items in this collection.

Since:

8.0.3