This topic describes how to you can extend hardware status using the status provider plug-in.
There are four basic ideas that you need to have in mind when creating a status provider:
Using the hardware status function in IBM Director, you can see hardware problems on the main IBM Director Console and quickly "drill-down" to the specific cause of the problem. A snapshot of the hardware status task window for a specific system is shown in Figure 1.
Figure 1. Snapshot of the hardware status task window for a specific system
Hardware status is organized by hardware component and is shown in the tree structure in the left pane. Each hardware type is represented by a node in the tree. The hardware status events are at the leaf nodes of the tree. The events identify the problem as either "INFO", "WARNING" or "CRITICAL". The leaf node status is always the status of the most severe event in that node. Likewise, the status is propagated up the tree all the way to the managed object.
Hardware status is able to represent the status of any type of hardware; all that is required is to have code which can detect the hardware state and to create a status provider. To be a hardware status provider, you must do the following:
The hardware status is organized in a tree structure. At the root is the system node with category nodes as child nodes. Beneath each category node will be zero or more component nodes. These components represent the system components in their respective categories for which hardware status will be monitored. The available component nodes will vary from system to system. The available component nodes depend on which hardware components are discovered on the individual systems by all hardware status providers.
The CIM plug-in is the default status provider plug-in. The status provider is a server extension that registers with the hardware status service during its initialization. The ESStatusService class in the com.ibm.sysmgt.esstatusserver package supplies the method to register the plug-in and methods to manage the status tree (query, get and set). During initialization the status provider registers the list of existing components, including the default status node categories: storage, device, environmental, security, other, generic, and network.
The default status provider captures all CIM events sent to the management server from managed clients. The events are categorized and fed to the appropriate listening hardware component nodes (ESStatusNode). All new events and status changes are reflected up the status tree.
A new status provider plug-in is an extension of the existing ESStatusProviderSource. Your extended code must implement the method initComponents(). This method is called to solicit status for a specific managed object. The initComponents() method will be called:
The provider must have an init() method which can be used to extend the status tree by creating new status nodes and inserting them where needed. An ESStatusNode is a leaf node or hardware component and an ESStatusCategory represents a category or sub-category further up the status tree. Your edited plug-ins should utilize the existing categories, (storage, device, environmental, security, other, generic, or network), and add only hardware component nodes. A status node contains the status for all clients (managed objects) that have the corresponding hardware component. When a status provider creates a status node it must provide a resource bundle for NLS translation of the node name that is displayed by the GUI. It can optionally override the default status rules. The default rules changes node status only if an arriving status event has higher severity.
Note: See Creating a provider for implementation details and examples.
The intent of a hardware status is to source status for one or more hardware components in one or more categories. A provider can gather status for any managed object which possesses one or more of these hardware components. The provider supplies the status and abstracts the "where" and "how" it is gathered. The status tree is used to maintain the status. The provider and the status tree are related since the terminal nodes of the hardware status tree (representing components) are assigned as listeners to the providers.
When creating a new hardware status provider you would create a new class that extends the status provider source: ESStatusProviderSource and overrides the init() method. The init() method typically includes the following:
The initComponents(CompID, moid) method must be implemented. The initComponents method provides a mechanism for the initial status of all the systems being managed to be set by the status provider.
Your code is expected to do the following:
Steps 1-3 should be carried out by the initComponents() method.
The intent of a status provider is to maintain dynamic hardware status for a defined set of hardware components. For example a provider could become a director event listener and watch for hardware status changes in the components that it monitors. The framework will not poll the providers for status. This will only occur when initComponents() is called for the reasons stated above: system startup, new managed objects, and when a managed object goes from offline to online.
Below is a sample hardware status provider code.
/*
* Licensed Materials - Property of IBM
*
* OCO Source Materials
*
* 09N6996
*
* (C) Copyright IBM Corp. 1999, 2001 All Rights Reserved
*
* The source code for this program is not published or other-
* wise divested of its trade secrets, irrespective of what has
* been deposited with the U.S. Copyright Office.
*/
package com.ibm.sysmgt.esstatusserver;
import java.util.*;
import com.tivoli.twg.engine.TWGEventListener;
import com.tivoli.twg.engine.*;
import com.tivoli.twg.alertmgr.*;
import com.tivoli.twg.libs.*;
import com.tivoli.twg.log.TWGRas;
import com.ibm.sysmgt.esstatuscommon.*;
/** Sample Hardware Status Provider. This provider provides hardware status for
* a device Fan99 found under the category Device.
*
* @version 1.0
*/
public class DeviceFan99HWStatus extends ESStatusProviderSource
implements ESStatusConst, TWGEventListener
{
private static String FAN99_COMPONENT_ID = "Fan99";
// The Init method is called by the hardware status framework during initialization
// We'll use this call to make sure the appropriate category exists (Device)
// and register as an IBM Director event listener.
public void init()
{
try
{
ESStatusNode component = ESStatusService.getRegistered( "Device" );
if ( component == null )
{
ESStatusCategory category = new ESStatusCategory( "Device" );
ESStatusService.registerStatusCategory( category, this );
}
// register this provider
ESStatusService.registerStatusProvider( this );
// Prepare to monitor for status changes on the actual fan
// Become an event listener
// NOTE: Listening for events is only one exampole of the
// many ways an extension could monitor for status changes
// on a type of hardware.
TWGEventRouter.addListener(this);
} catch ( ESStatusException e )
{
TWGRas.error( TWGRas.HW_STATUS, "DeviceFan99HWStatus()", e );
}
}
// Cleanup: You should remove event listener. This method would be
// called from the extension shutdown.
public boolean shutdown()
{
TWGEventRouter.removeListener(this);
return true;
}
/**
* initComponents()
* Called by framework:
* - at server startup for each existing MO
* - when a new MO is created
* - when an MO goes from offline to online
*
* Initialize components for a specific managed object in the status tree
* if necessary and provide initial status. You must provide initial
* status normal or not.
*
* @param id- compID requesting init (can be ignored)
* @param moid - managed object which has been discovered or went online.
*/
public void initComponents( String id, long moid )
{
TWGRas.entry( TWGRas.HW_STATUS, "DeviceFan99HWStatus.initComponents()" );
try
{
// called from extension init
ESStatusCategory category = (ESStatusCategory)ESStatusService.getRegistered("Device");
if ( category == null )
throw new ESStatusException( " Category \"Device\" not defined!" );
else
{
Enumeration children = category.getChildren();
String compID = FAN99_COMPONENT_ID;
ESStatusNode component=null;
// look for Fan99 status node under Device category
while ( children.hasMoreElements() )
{
component = (ESStatusNode)children.nextElement();
if (component.getCompID().equals(compID))
{
break;
}
}
// if not found then create
if (component==null)
{
TWGRas.debug( TWGRas.HW_STATUS, " registering " + compID + " under Device" );
component = new ESStatusNode( compID );
ESStatusService.registerStatusNode( "Device", component, this );
}
// Make the component a listener for status from this provider.
// This must be done regardless of who created the component (statusNode).
// The addListener method will insure no duplicate listeners are registered.
addListener( compID, component );
// determine the status of this client, normal or not, and post it.
ESBaseEvent event = getInitialStatus( compID, moid );
fireStatusChange( compID, event, true );
}
} catch ( ESStatusException e )
{
TWGRas.error( TWGRas.HW_STATUS, "DeviceFan99HWStatus.initComponents()", e );
}
TWGRas.entry( TWGRas.HW_STATUS, "DeviceFan99HWStatus.initComponents()" );
}
//---------------- TWGEventListener interface methods ----------------------------//
// IBM Director events are typically use as a source of status but it doesn't need
// to be. Another posibility could be SNMP traps. It is only necessary to
// present status in a ESBaseEvent. Using TWGBaseEvent has an advantage though.
// As a published event the event description provides NLS translation.
/**
* Method to receive an event.
* @param event TWGBaseEvent object
*/
public void receiveEvent(com.tivoli.twg.alertmgr.TWGEventEvent event)
{
// Determine if this is my event and what component it is associated with.
// Assume it's Fan99 in our example.
// Check to see if this is an event related to Fan99
if(typestr.equals("Sample.Hardware.Fan.99.Failure" )) {
// Fire a statuse change to show that the fan has Failed
// on the hardware status console panel.
String compID = FAN99_COMPONENT_ID;
TWGBaseEvent baseEvent = event.getEvent();
ESBaseEvent statusEvent = new ESBaseEvent(compID, baseEvent);
fireStatusChange( compID, statusEvent, true );
}
}
/**
* Method to receive a list of existing publications.
* This method is called when a listener is added.
*
* @param publishList vector of publish objects to process.
*/
public void receivePublishList( Vector publishList )
{
}
/**
* Method to receive a publish event.
*
* @param publish publish object to process.
*/
public void receivePublish( TWGPublish publish )
{
}
/**
* Method to receive an unpublish event.
*
* @param unpublish unpublish object to process.
*/
public void receiveUnpublish( TWGUnpublish unpublish )
{
}
// Provide initial status (dummy)
// It is important that a hardware status provider can gather initial status
// for the components it monitors. The hardware status framework
// does NOT persist hardware status for any components.
private ESBaseEvent getInitialStatus( String compID, long moid )
{
// NOTE: This example always sets the inital status to Critical
String qualifiers[] = { "CIM", compID };
TWGBaseEvent baseEvent = new TWGBaseEvent(
new String("UMService"),/* String family */
qualifiers, /* String[] qualifiers */
TWGPartialEvent.EVENT_SEVERITY_CRITICAL,/* short severity */
moid, /* byte[] unique id of who its about */
null, /* byte[] my unique id */
"test event", /* String text */
Locale.ENGLISH, /* Locale */
null, /* sub vars */
new TWGEventCorrelator(0),/* TWGEventCorrelator correlator */
0); /* int flags 0 = alert */
ESBaseEvent event = new ESBaseEvent( compID, baseEvent );
return event;
}
}