com.arsdigita.categorization.Category

A Category encapsulates a persistent category object. This object contains the name and description for the category, as well as information about whether the category is enabled. It also provides an API for placing objects within this category, creating subcategories under the instance category, and retrieving parent and child categories and objects.

com.arsdigita.categorization.CategorizedObject

This class is the "leaf" node of a category tree, containing the actual data object and methods to find the parent. That is, when a subcategory is asked for its objects, it returns a collection of CategorizedObjects. Methods within CategorizedObject can then be used to retrieve information about the parents of the given Object as well as the actual ACSObject.

com.arsdigita.categorization.CategoryFilter

This class allows you to filter the categories that will be returned as parents or children of categories. Currently, it allows you to choose enabled categories only, disabled categories only, or all categories. By subclassing this class, applications can add further filtering criteria.

Other Classes

• The class com.arsdigita.categorization.CategoryTreeModel and the class com.arsdigita.categorization.CategoryTreeNode work together to provide access to a Bebop Tree that can be used to display the category tree. These classes are not of much importance to you unless you want to change the way the tree appears. Displaying a category hierarchy is a multiple-step process. First, create a TreeModelBuilder that will instantiate a CategoryTreeModel (based either on a query or some other external data source). This TreeModelBuilder is passed to the Tree, which uses your builder to create its TreeModel. This process is necessary since a DataObject cannot be used across connections.

Creating a new Category

// Creates the Movies category at the top level with a description
Category movies = new Category("Movies", "long television shows");
movies.save();
// Create the Romantic Comedies category under the Movies category.
Category romance = new Category("Romantic Comedies",
                                "Comedies with love stories");
romance.setDefaultParentCategory(movies);
romance.save();
// Create the Titanic category under the Romantic Comedies category.
Category titanic = new Category("Titanic", "A category for large movies");
// set this as the default category
titanic.setDefaultParentCategory(romance);
titanic.save();
// Create the Drama category under the Movies category.
Category drama = new Category("Drama", "long, not funny stories");
drama.save();
// Make Drama a parent category (but not the default parent) of Titanic.
drama.addChild(titanic);
drama.save();
// Finally, make movies a parent of Drama
drama.setDefaultParentCategory(movies);
drama.save();

Note the following about this example:

• Whenever a new item is instantiated, it must be explicitly saved. This allows developers to easily back out of changes in the middle of the transaction.

• Adding the "Titanic" category to two categories looks the same as adding it to a single category. The first category to which an item (category or other ACSObject) is added is explictly added as the default category. If a category/item only has one parent, that parent is implicitly the default.

Deleting a Category

// Fetch the Movies category from the database.
Category category = new Category(new OID(123));
// Delete the Movies category.
category.deleteCategoryAndRemap();

You can delete a category in the following ways:

• Deleting Leaf Category: If the category is a leaf, call Category.delete().

• Remapping Child Categories: If you want to remove the current category and make all categories that were pointing to it point to its default parent (as in the example), call Category.deleteCategoryAndRemap().

• Orphaning Children: If you want to delete the category without remapping any of the child categories, call Category.deleteCategoryAndOrphan().

• Deleting Category Subtree: If you want to delete the entire subtree, including the passed-in category and all categories below it whose default ancestry can be traced to the root, call Category.deleteCategorySubtree()

Adding more Parent Categories

Category a = new Category(new OID(123));
Category b = new Category(new OID(124));
Category c = new Category(new OID(125));
if ( a != null && b != null && c != null ) {
// Makes Category B the parent of Category A
b.addChild(a);
b.save();
// Makes Category C the parent of Category A
c.addChild(a);
c.save();
// Sets Category B as the default parent of Category A
a.setDefaultParentCategory(b);
a.save();
}
                  

Removing Parent Categories

// Fetch category A from the database.
Category a = new Category(new OID(123));
// Fetch the parent category
Category b = a.getDefaultParentCategory();
b.removeChild(a);
b.save();
a.setDefaultParentCategory(b.getDefaultParentCategory());
                  

Retrieving all Subcategories of a given Category

// assume that we have the Category OID (call it categoryOID)
Category category = new Category(categoryOID);
// the Collection will be a Collection of Category objects
Collection subcategories = category.getChildCategories();
        

Retrieving all child objects of a given Category

// assume that we have the Category OID 
// (call it categoryOID)
Category category = new Category(categoryOID);
// the Collection will be a Collection of 
// CategorizedObjects
Collection childObjects = category.getChildObject();

// print out the toString for each object 
// and its parents
Iterator childIterator = childObjects.iterator();
while (childIterator.hasNext()) {
CategorizedObject object = 
 (CategorizedObject) childIterator.next();
System.out.println("object = " + object.getObject());
Iterator parents = object.getParentCategories().iterator();
while(parents.hasNext()) {
System.out.println("parent = " + 
 ((Category) parents.next()).toString());
}
}