Solaris WBEM SDK Developer's Guide

Handling CIM Events

Note -

For in-depth information on CIM Indications and how they are used to communicate occurrences of events, see the Distributed Management Task Force (DMTF) Event white paper at http://www.dmtf.org/education/whitepapers.php.

An event is a real world occurrence. An indication is an object that communicates the occurrence of an event. In the Common Information Model, indications are published—not events. Providers generate an indication when an event takes place.

An indication may have zero or more triggers, which are recognitions of changes in state. WBEM does not have an explicit object representing a trigger. Instead, a trigger is implied by the following:

An operation on a basic object of a system — Create, delete, modify, or access a class; modify or access an instance
Any event that takes place in the managed environment

For example, when a service terminates and a trigger is engaged, this event results in an indication that serves as notification that the service has terminated.

You can view the related CIM event classes in the Solaris WBEM Services schema at /usr/sadm/lib/wbem/doc/mofhtml/index.html. The class is structured as follows:

Table 3-5 CIM_Indication Class Structure


Root Class	Superclass	Subclass
`CIM_Indication`	`CIM_ClassIndication`	`CIM_ClassCreation` , `CIM_ClassDeletion`, `CIM_ClassModification`
	`CIM_InstIndication`	`CIM_InstCreation`, `CIM_InstDeletion`, `CIM_InstMethodCall`, `CIM_InstModification`, `CIM_InstRead`
	`CIM_ProcessIndication`	`CIM_AlertIndication`, `CIM_AlertInstIndication`, `CIM_ThresholdIndication`, `CIM_SNMPTrapIndication`

About Indications

CIM events can be classified as either life cycle or process. A life cycle event is a built-in CIM event that occurs in response to a change to data in which a class is created, modified, or deleted, or a class instance is created, modified, deleted, read, or has a method invocation. A process event is a user-defined event that is not described by a life cycle event.

Event providers generate indications in response to requests made by the CIM Object Manager. The CIM Object Manager analyzes subscription requests and uses the EventProvider and/or the CIMIndicationProvider interface to contact the provider, requesting that it generate the appropriate indications. When the provider generates the indication, the CIM Object Manager routes the indication to the destinations specified by the CIM_IndicationHandler instances. These instances are created by the subscribers.

Event providers are located in the same manner as instance providers. In the case of subscriptions pertaining to instance life cycle indication (subclasses of CIM_InstIndication), once the CIM Object Manager determines the classes covered by the subscription, it contacts the instance providers for those classes. For process indications, the CIM Object Manager contacts the appropriate provider using the Provider qualifier.

The CIM Object Manager and the CIM Object Manager Repository handle indications under the following circumstances:

The CIM Object Manager handles CIM_InstMethodCall, CIM_InstModification, CIM_InstDeletion and CIM_InstCreation events if the provider does not support indications, or tells the CIM Object Manager to poll.
The CIM Object Manager Repository handles all class indications and life cycle indications for classes that do not have providers. These classes include CIM_ClassCreation, CIM_ClassDeletion CIM_ClassModification, CIM_InstCreation, CIM_InstModification, CIM_InstDeletion and CIM_InstRead.

In these cases, the provider does not generate indications or implement the EventProvider interface. In addition, the provider can delegate event generation responsibilities to the CIM Object Manager. The CIM Object Manager invokes enumerateInstances on the providers and compares snapshots of previous states to current states to determine if instances have been created, modified, or deleted.

Note -

In most cases, providers should handle their own indications since polling carries a high overhead. In order to generate indications, the provider itself must poll. In this case, the provider can delegate the task to the CIM Object Manager.

If a provider implements the EventProvider interface, the CIM Object Manager invokes the methods in the interface and takes actions according to the responses. When the CIM Object Manager determines that a particular provider must participate in a subscription request, the methods are invoked in the following order:

mustPoll - Invoked by the CIM Object Manager for CIM_InstCreation, CIM_InstDeletion, and CIM_InstModification to determine if the provider wants the CIM Object Manager to poll. If the provider does not implement the EventProvider interface, the CIM Object Manager assumes polling by default.
authorizeFilter - If the provider implements the Authorizable interface, this method is invoked by the CIM Object Manager to determine if the subscription is authorized. The provider can make the determination based on the user ID of the owner of the indication handler—the user who receives the indications—or based on the user ID of the user who created the subscription.

If the provider does not implement the Authorizable interface, the CIM Object Manager performs the default read authorization check for the namespace.

If the provider does not implement the EventProvider interface and the CIM Object Manager tries to poll, the authorization succeeds if enumerateInstances succeeds on the provider.
activateFilter - Invoked by the CIM Object Manager when the authorization succeeds and the provider does not want to be polled.
deActivateFilter - Called when a subscription is removed either by the subscriber or the CIM Object Manager; for example, if the destination handler malfunctions.

About Subscriptions

A client application can subscribe to be notified of CIM events. A subscription is a declaration of interest in one or more streams of indications. Currently, providers cannot subscribe for event indications.

An application that subscribes for indications of CIM events describes the following:

The indications to which it wants to subscribe.
The handler to which the CIM Object Manager delivers the indication.

The occurrence of an event is represented as an instance of one of the subclasses of the CIM_Indication class. An indication is generated only when a client subscribes to the event.

To Create a Subscription

An application can create one or more event filters with one or more event handlers. Event indications are not delivered until the application creates the event subscription.

Create an instance of CIM_Listener. See Adding a CIM Listener..

Create an instance of CIM_IndicationFilter. See Creating an Event Filter.

Create an instance of CIM_IndicationHandler. See Creating an Event Handler.

Bind the to the CIM_IndicationFilter to the CIM_IndicationHandler. See Binding an Event Filter to an Event Handler.

Adding a CIM Listener

To receive indications of CIM events, first add an instance of CIMListener to CIMClient, by invoking the addCIMListener method on CIMClient.

Note -

The CIMListener interface must implement the indicationOccured method, which takes the argument CIMEvent. This method is invoked when an indication is available for delivery.

Example 3-21 Adding a CIM Listener

// Connect to the CIM Object Manager
cc = new CIMClient();

// Register the CIM Listener
cc.addCIMListener(
new CIMListener() {
    public void indicationOccured(CIMEvent e) {
    }
});

Creating an Event Filter

Event filters describe the types of events to be delivered and the conditions under which they are delivered. To create an event filter, create an instance of the CIM_IndicationFilter class and define values for its properties. Each event filter works only on events that belong to the namespace to which the filter belongs.

The CIM_IndicationFilter class has string properties that you can set to uniquely identify the filter, specify a query string, and specify the query language that parses the query string. Currently, only the WBEM Query Language (WQL) is supported.

Table 3-6 CIM_IndicationFilter Properties


Property	Description	Required/Optional
`SystemCreationClassName`	The name of the system on which the creation class for the filter resides or to which it applies.	Optional. The value is decided by the CIM Object Manager.
`SystemName`	The name of the system on which the filter resides or to which it applies.	Optional. The default for this key property is the name of the system on which the CIM Object Manager is running.
`CreationClassName`	The name of the class or subclass used to create the filter.	Optional. The CIM Object Manager assigns `CIM_IndicationFilter` as the default for this key property.
`Name`	The unique name of the filter.	Optional. The CIM Object Manager assigns a unique name.
`SourceNamespace`	The path to a local namespace where the CIM indications originate.	Optional. The default is null.
`Query`	A query expression that defines the conditions under which indications are generated. Currently, only Level 1 WBEM Query Language (WQL) expressions are supported. To learn more about WQL query expressions, see Chapter 5, Writing WBEM Queries.	Required.
`QueryLanguage`	The language in which the query is expressed.	Required. The default is WQL (WBEM Query Language).

To Create an Event Filter

Create an instance of the CIM_IndicationFilter class:

CIMClass cimfilter = cc.getClass
        (new CIMObjectPath(“CIM_IndicationFilter”),
         true, true, true, null);
CIMInstance ci = cimfilter.newInstance();

Specify the name of the event filter:

Name = “filter_all_new_solarisdiskdrives”

Create a WQL string to identify that event indications to return:

String filterString = “SELECT * 
        FROM CIM_InstCreation WHERE sourceInstance 
        ISA Solaris_DiskDrive”;

Set property values in the cimfilter instance to identify the name of the filter, the filter string to select CIM events, and the query language (WQL) to parse the query string.

ci.setProperty(“Name”, new 
        CIMValue("filter_all_new_solarisdiskdrives”));
ci.setProperty("Query", new CIMValue(filterString));
ci.setProperty("QueryLanguage", new CIMValue("WQL");)

Create an instance of the cimfilter instance called filter and store it in the CIM Object Manager Repository:

CIMObjectPath filter = cc.createInstance(new
                                               CIMObjectPath(), ci);

Example 3-22 Creating an Event Filter

CIMClass cimfilter = cc.getClass(new CIMObjectPath
                                (“CIM_IndicationFilter”), true);
CIMInstance ci = cimfilter.newInstance();
//Assuming that the test_a class exists in the namespace
String filterString = "select * from CIM_InstCreation where sourceInstance 
                       isa test_a"

ci.setProperty("query", new CIMValue(filterString));
CIMObjectPath filter = cc.createInstance(newCIMObjectPath(), ci);

Creating an Event Handler

An event handler is an instance of a CIM_IndicationHandler class. You set the properties in an instance of the CIM_IndicationHandler class to uniquely name the handler and identify the UID of its owner. The CIM Event MOF defines a CIM_IndicationHandlerCIMXML class for describing the destination for indications to be delivered to client applications using the HTTP protocol. The Solaris Event MOF extends the CIM_IndicationHandler class by creating the Solaris_JAVAXRMIDelivery class to handle delivery of indications of CIM events to client applications using the RMI protocol. RMI clients must instantiate the Solaris_JAVAXRMIDelivery class to set up an RMI delivery location.

Table 3-7 CIM_IndicationHandler Properties


Property	Description	Required/Optional
SystemCreationClassName	The name of the system on which the creation class for the handler resides or to which it applies.	Optional. Completed by the CIM Object Manager.
SystemName	The name of the system on which the handler resides or to which it applies.	Optional. The default value for this key property is the name of the system on which the CIM Object Manager is running.
CreationClassName	The class or subclass used to create the handler.	Optional. The CIM Object Manager assigns the appropriate class name as the default for this key property.
Name	The unique name of the handler.	Optional. The client application must assign a unique name.
Owner	The name of the entity that created or maintains this handler. The provider can check this value to determine whether or not to authorize a handler to receive an indication.	Optional. The default value is the Solaris user name of the user creating the instance.

Example 3-23 Creating an Event Handler

// Create an instance of the Solaris_JAVAXRMIDelivery class or get
// the appropriate instance of the handler.
CIMInstance ci = cc.getIndicationHandler(null);

//Create a new instance (delivery) from
//the rmidelivery instance.
CIMObjectPath delivery = cc.createInstance(new CIMObjectPath(), ci);

Binding an Event Filter to an Event Handler

You bind an event filter to an event handler by creating an instance of the CIM_IndicationSubscription class. When you create an indication of this class, indications for the events specified by the event filter are delivered.

The following example creates a subscription (filterdelivery) and defines the filter property to the filter object path created in “To Create an Event Filter”, and defines the handler property to the delivery object path created in Example 3–23.

Example 3-24 Binding an Event Filter to an Event Handler

CIMClass filterdelivery = cc.getClass(new 
        CIMObjectPath(“CIM_IndicationSubscription”), 
        true, true, true, null);
ci = filterdelivery.newInstance():

//Create a property called filter that refers to the filter instance.
ci.setProperty("filter", new CIMValue(filter));

//Create a property called handler that refers to the delivery instance.
ci.setProperty("handler", new CIMValue(delivery));

CIMObjectPath indsub = cc.createInstance(new CIMObjectPath(), ci);