User's Manual

Chapter 11.
Services Tutorials
These tutorials build upon the discussion in Chapter 4 WAF Component: Services.
11.1. Categorization Tutorial
This section presents an overview of using the categorization layer within WAF. The focus in this
section is on describing the main concepts, classes, and interfaces that a programmer uses to work
with the categorization API.
11.1.1. Overview
This section partially overlaps with and elaborates on the material presented in
http://rhea.redhat.com/documentation/api/ccm-core-6.1.0/com/arsdigita/categorization/package-
summary.html.
A category is a class of objects or things that share something in common within a conceptual scheme.
It has a short name and an optional description. Each category also has a unique identity. Two distinct
categories may happen to have the same name. They are treated as two different categories, if their
identities are different. This abstraction is represented by the Category class.
There are two kinds of things that can be placed in a category. Firstly, a category may contain other
categories within it. Such categories are called subcategories or child categories. The enclosing cate-
gory is referred to as the parent category. Category Y is said to be a descendant of category X if either
Y is a child of X, or the parent of Y is a descendant of X. If Y is a descendant of X, then X is called an
ancestor category or ascendant category of X.
Secondly, a category may contain objects other than categories. In our system, a category may contain
any ACSObject. Note that the Category class is itself an ACSObject, but one that has a special
status in the categorization service. If ACSObject A is placed into category X, then we say that A
is a child object of X and X is a parent category of A. We say that object B is a descendant object of
category X, if either B is a child object of X, or the parent category of B is a descendant of X.
Let us first concentrate on the category-subcategory relationship. A category cannot contain two iden-
tically named subcategories.
We also require that there be no cycles. In other words, A must not be its own descendant. As an edge
case of this general rule, A cannot contain itself as a subcategory.
A category may have more than one parent. By allowing this, we make possible categorization
schemes that do not look like trees (see below). This complicates matters slightly, insofar as trees
are easier to deal with than the more general structure known as directed acyclic graphs. To restore
the ability to treat categorization schemes as trees, we allow some category-subcategory links to be
marked as "default". We require that each category have no more than one default parent. A default
parent is also sometimes referred to as a primary parent. Non-default parents are called secondary
parents.
A category with no parents is called a root category. This category and its descendants are referred
to as a category scheme. By disregarding non-default parent-child links, we can obtain a subset of
the categorization scheme that forms a proper rooted tree. The following diagram shows a simple
categorization scheme.