All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sgi.sysadm.category.Category

java.lang.Object
   |
   +----com.sgi.sysadm.util.AttrBundle
           |
           +----com.sgi.sysadm.category.Category

public abstract class Category
extends AttrBundle
Represents a collection of monitored Item(s) of a specific type. For example, the collection of user account Item(s) can be represented by a Category instance. A Category is also a subclass of AttrBundle and can have a set of Attributes that apply to all Item(s) of that type.

Clients interested in information about a Category instance can create an instance CategoryListener and register for notifications by passing a CategoryListener instance to addCategoryListener(). The specific Items of interest are indicated by the NotificationFilter paramater. The NotificationFilter also specifies whether the CategoryListener instance is interested in notifications about the Category attributes. Call removeCategoryListener() to unregister interest in notification.

Category notifies registered CategoryListener instances about an Item discovered at startup that are later added via CategoryListener.itemAdded() calls, Item changes via CategoryListener.itemChanged() calls, and Item removals via CategoryListener.itemRemoved(). When addCategoryListener() is called, Category sends the listener its current list of Item(s) via itemAdded() calls. If the Category has completed discovery of the existing Item(s) of the specific type in the system before the time the CategoryListener registers for notification, it will notify CategoryListener of all the Item(s) in its list and send the endExists() notification. If not, it will send the endExists() notifications when it completes discovery of the existing Item(s).

Category also calls CategoryListener methods beginBlockChanges() and endBlockChanges() to indicate the start and end of a block of notifications.

In order to get an Item corresponding to a specific selector in a Category, you must pass a ResultListener to getItem. getItem calls the succeeded method of the ResultListener, if an Item with the specified selector exists in the system. Use the getResult method of ResultEvent to get the Item. The Object returned by getResult should be cast to an Item. getItem calls the failed method of the ResultListener, if an Item with the specified selector does not exists in the system. For example:

 Category cat;
 ...
 cat.getItem("Test", new ResultListener() {
     public void succeeded(ResultEvent event) {
         Item item = (Item) event.getResult();
     }
     public void failed(ResultEvent event) {
         System.out.println("getItem failed.");
     }
 });
 
The actual logic for determining and monitoring Item(s) in a Category resides on the server-side. Clients can obtain a Category instances using HostContext methods.

See Also:
HostContext, NotificationFilter, CategoryListener

Variable Index

 o CATEGORY
This is the suffix that all Category selectors must end with.

Constructor Index

 o Category(String)
Category constructor.

Method Index

 o addCategoryListener(CategoryListener)
Convenience method to specify that the CategoryListener object is interested in receiving all notifications.
 o addCategoryListener(CategoryListener, NotificationFilter)
Called by clients to add a CategoryListener to the list of objects which will receive types of notifications specified.
 o addItem(Item)
Called by subclasses when a new Item is discovered at startup or when an Item is added.
 o beginBlockChanges()
Begin a change block.
 o changeItem(Item)
Called by subclasses when an item in the system changed.
 o endBlockChanges()
End a change block.
 o endExists()
Called by subclasses after it has called addItem() for every Item that existed in the system when startMonitor() is called.
 o getItem(String, ResultListener)
Get the Item corresponding to a selector.
 o getItemCount(ResultListener)
Gets the number of Items in this Category.
 o getItemEnum()
Get an Enumeration of the Items in this Category.
 o getItemList(ResultListener)
Gets the list of Items in this Category.
 o hasExistsEnded()
Called by subclasses to check if the Category has received an endExists notification.
 o isInBlockChangesNotification()
Called by subclasses to check if the Category is in the middle of a block changes notification.
 o isMonitoring()
Called by subclasses to check if the Category has started monitoring the system.
 o removeCategoryListener(CategoryListener)
Remove a listener from the list of objects that will receive notifications.
 o removeItem(String)
Called by subclasses when an item is removed from the system.
 o replaceItemList(Hashtable)
Replace the current list of Item(s) by a new list.
 o startMonitor()
Called by Category when the first CategoryListener is added to start monitoring the system.

Variables

 o CATEGORY
 protected static final String CATEGORY
This is the suffix that all Category selectors must end with.

Constructors

 o Category
 protected Category(String selector)
Category constructor.

Parameters:
selector - The string representing the type of the Item that this Category monitors. For example, the Category instance representing user accounts could have selector: "UserAccountCategory". This should be the same as the name of the library representing the Category on the server side which resides in /usr/sysadm/category

Methods

 o addCategoryListener
 public void addCategoryListener(CategoryListener listener,
                                 NotificationFilter filter)
Called by clients to add a CategoryListener to the list of objects which will receive types of notifications specified.

Parameters:
listener - The object to call when something happens.
filter - Specified the notifications of interest to listener object. Category makes a copy of "filter" and any changes to "filter" after this call is made has no effect on the filter that Category associates with "listener".
 o addCategoryListener
 public void addCategoryListener(CategoryListener listener)
Convenience method to specify that the CategoryListener object is interested in receiving all notifications.

Parameters:
listener - The object to call when something happens.
 o removeCategoryListener
 public void removeCategoryListener(CategoryListener listener)
Remove a listener from the list of objects that will receive notifications.

Parameters:
listener - listener to remove.
 o getItem
 public synchronized void getItem(String selector,
                                  ResultListener listener)
Get the Item corresponding to a selector.

Parameters:
selector - Selector of an Item.
listener - Gets notified of the result of this operation. listener.succeeded is called on succcess. listener.failed is called on failure. The getResult method should be called on the ResultEvent passed to listener.succeeded to get the Item corresponding to "selector". The Object returned should be cast to an Item.
 o getItemCount
 public synchronized void getItemCount(ResultListener listener)
Gets the number of Items in this Category.

Parameters:
listener - listener.succeeded is called upon completion of the operation. getResult method should be called on the ResultEvent passed to listener.succeeded to get the number of Items in this Category. The Object returned should be cast to an Integer.
 o getItemList
 public synchronized void getItemList(ResultListener listener)
Gets the list of Items in this Category.

Parameters:
listener - listener.succeeded is called upon completion of the operation. getResult method should be called on the ResultEvent passed to listener.succeeded to get the list of Items in this Category. The Object returned should be cast to a Hashtable. The elements of the Hashtable are Items, with selectors used as the Hashtable key.
 o getItemEnum
 protected synchronized Enumeration getItemEnum()
Get an Enumeration of the Items in this Category.

Returns:
Enumeration of Items in this Category.
 o startMonitor
 protected abstract void startMonitor()
Called by Category when the first CategoryListener is added to start monitoring the system. Subclasses should do whatever is necessary to start monitoring the system within this method. None of addItem(), changeItem(), orphanItem() or removeItem() should be called prior to the call to startMonitor().

 o addItem
 protected synchronized void addItem(Item item)
Called by subclasses when a new Item is discovered at startup or when an Item is added. Add the Item to our list and inform listeners.

Parameters:
item - The Item that was added.
 o isMonitoring
 protected boolean isMonitoring()
Called by subclasses to check if the Category has started monitoring the system.

Returns:
true if the Category is monitoring the system, false otherwise.
 o isInBlockChangesNotification
 protected boolean isInBlockChangesNotification()
Called by subclasses to check if the Category is in the middle of a block changes notification.

Returns:
true if the Category is in the middle of a block changes notification, false otherwise.
 o hasExistsEnded
 protected boolean hasExistsEnded()
Called by subclasses to check if the Category has received an endExists notification.

Returns:
true if the Category has received an endExists notification, false otherwise.
 o changeItem
 protected synchronized void changeItem(Item item)
Called by subclasses when an item in the system changed. Change the corresponding item in our list and inform listeners.

Parameters:
item - The item that changed.
 o removeItem
 protected synchronized Item removeItem(String selector)
Called by subclasses when an item is removed from the system. Remove the item from our list and inform listeners

Parameters:
selector - selector of the item that was removed.
Returns:
The object that was removed from the list of items
 o replaceItemList
 protected synchronized void replaceItemList(Hashtable list)
Replace the current list of Item(s) by a new list. The Category base class computes any changes between its previous list and the new "list" and notifies interested listeners of any changes. "list" becomes the new list of Category items.

Parameters:
list - New list of Item(s).
 o beginBlockChanges
 protected synchronized void beginBlockChanges()
Begin a change block. CategoryListeners can defer doing expensive stuff until the change block ends.

 o endBlockChanges
 protected synchronized void endBlockChanges()
End a change block.

 o endExists
 protected synchronized void endExists()
Called by subclasses after it has called addItem() for every Item that existed in the system when startMonitor() is called. Category informs listeners.


All Packages  Class Hierarchy  This Package  Previous  Next  Index