Solaris WBEM Developer's Guide

Handling CIM Events

Note –

For in-depth information on CIM indications and how indications 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 actions:

An operation on a basic object of a system. An operation could create, delete, modify, or access a class. An operation might also modify or access an instance.
Any event that takes place in the managed environment.

For example, when a trigger is engaged due to service termination, 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 shown in the following table.

Table 4–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 a particular change in data. The types of changes that trigger a life cycle event are:

A class is created, modified, or deleted
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 CIMOM. The CIMOM analyzes subscription requests. The CIMOM uses the EventProvider or the CIMIndicationProvider interface to contact the provider, requesting the provider to generate the appropriate indications. When the provider generates the indication, the CIMOM 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. There is a sequence of steps that the CIMOM follows in the case of subscriptions pertaining to instance life cycle indication, such as subclasses of CIM_InstIndication. Once the CIMOM determines the classes covered by the subscription, the CIMOM contacts the instance providers for those classes. For process indications, the CIMOM 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 CIMOM handles the following events, if either the provider does not support indications or the provider tells the CIMOM not to poll:
- CIM_InstMethodCall
- CIM_InstModification
- CIM_InstDeletion
- CIM_InstCreation
The CIM Object Manager Repository handles all class indications and life cycle indications for classes that do not have providers. These classes include the following:
- CIM_ClassCreation
- CIM_ClassDeletion
- CIM_ClassModification
- CIM_InstCreation
- CIM_InstModification
- CIM_InstDeletion
- 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. The CIMOM compares snapshots of previous states to current states to determine whether instances have been created, modified, or deleted.

Note –

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

If a provider implements the EventProvider interface, the CIMOM invokes the methods in the interface and takes actions according to the responses. When the CIMOM 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 whether 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 CIMOM to determine whether the subscription is authorized. The provider can make the determination based on either: the user ID of the owner of the indication handler, which is 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 CIMOM tries to poll, the authorization succeeds if enumerateInstances succeeds on the provider.
activateFilter– Invoked by the CIMOM 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 CIMOM. 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 provides the following information:

The indications to which the application wants to subscribe
The handler to which the CIMOM 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 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 4–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. These properties can be 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 4–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 identifying 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 following information:

Name of the filter
Filter string to select CIM events
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 a cimfilter instance tahat is called filter. Store the instance in the CIM Object Manager Repository

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

Example 4–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 to 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 that use the HTTP protocol. The Solaris Event MOF extends the CIM_IndicationHandler class by creating the Solaris_JAVAXRMIDelivery class. This subclass handles delivery of indications of CIM events to client applications that use the RMI protocol. RMI clients must instantiate the Solaris_JAVAXRMIDelivery class to set up an RMI delivery location.

Table 4–7 CIM_IndicationHandler Properties


Property	Description	Required or 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 to authorize a handler to receive an indication.	Optional. The default value is the Solaris user name of the user who creates the instance.

Example 4–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. The example also defines the handler property to the delivery object path that is created in Example 4–23.

Example 4–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);