Sun WBEM SDK Developer's Guide

Chapter 6 Handling CIM Events

This chapter describes the CIM event model and explains how providers generate CIM events and how applications subscribe to be notified of the occurrence of CIM events.

The CIM Event Model

An event is an occurrence, something that happens. In programming terms, an event is an occurrence in a computer system to which an application might need to respond, for example, opening a dialog box in response to a mouse click on a GUI. A CIM event is a change in an occurrence of interest in a managed environment.

The CIM event model, a framework for handling CIM events, conforms to the Common Information Model (CIM) Indications Specification, published by the Desktop Management Task Force (DMTF). The CIM event model distinguishes between an event and the notification of that event (an indication). In CIM, events are not published; indications are published.

CIM events can be classified as intrinsic or extrinsic. An intrinsic event is a built-in CIM event that occurs in response to changes to data in which a namespace, class, or class instance is created, modified, or deleted. An extrinsic event is a user-defined event that is not already described by an intrinsic events.

Currently, only intrinsic events for creating, modifying, and deleting CIM instances are handled. The following classes are used to report intrinsic events:

CIM_InstCreation — Indicates that a new instance was created.
CIM_InstDeletion — Indicates that an existing instance was deleted.
CIM_InstModification — Indicates that an instance was modified.

How Indications of Events are Generated

By default, the CIM Object Manager polls for indications of intrinsic events at regular intervals. Administrators can change the event polling interval and the default polling behavior of the CIM Object Manager by editing the properties in the cimom.properties file. For instructions on editing the cimom.properties file, see the Solaris WBEM Services Administrator's Guide.

The CIM Object Manager polls by enumerating instances, repeating the enumeration at the specified polling interval, and then finding any new, changed, or deleted instances between the two sets of enumerated instances. If a provider generates indications for events, the CIM Object Manager will not poll the provider. If possible, providers should generate indications for the intrinsic events that occur in the dynamic instances of the classes they support. This prevents the performance cost that results from the CIM Object Manager polling for the event.

The CIM Object Manager Repository generates an indication when a static instance is created, modified, or deleted.

How Subscriptions are Created

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:

Which events in which it is interested.
What action the CIM Object Manager should take when the events occur.

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 for the event. If no provider delivers the event for which a client subscribes, the subscription will fail.

Creating a Subscription

Creating a subscription involves adding the CIMListener interface and creating instances of the following classes:

CIM_IndicationFilter — Defines the criteria for generating an indication and what data should be returned in the indication.
CIM_IndicationHandler — Describes how an indication is to be processed and delivered (handled). This may define a destination and protocol for delivering indications.
CIM_IndicationSubscription — An association that binds a particular event filter with a particular event handler.

An application can create one or more event filters with one or more event handlers. Indications of events are not delivered until an application creates a subscription for the events.

Adding a CIM Listener

A client application must add the CIMListener interface to register for indications of CIM events. The CIM Object Manager generates indications for CIM events that are specified by the event filter when a client subscription is created.

The CIMListener interface must implement the indicationOccured method which takes the argument, CIMEvent, the CIM event returned by the CIMListener.

Example 6–1 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. An application creates an event filter by creating an instance of the CIM_IndicationFilter class and defining values for its properties. Event filters belong to a namespace. Each event filter works only on events that belong to the namespace to which the filter also belongs.

The CIM_IndicationFilter class has string properties that an application can set to uniquely identify the filter, specify a query string, and the query language to parse the query string, as shown in the following table. Currently, only the WBEM Query Language is supported.

Table 6–1 Properties in the CIM_IndicationFilter Class


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 default for this key property is the `CIM_System.CreationClassName`.
`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.	Required. The client application must assign a unique name.
`SourceNamespace`	The path to a local namespace where the CIM indications originate.	Optional. The default is `\root\cimv2`.
`Query`	A query expression that defines the conditions under which indications will be generated. Currently, only Level 1 WBEM Query Language expressions are supported. To learn how to construct WQL query expressions, see Querying.	Required.
`QueryLanguage`	The language in which the query is expressed.	Required. The default is WQL (WBEM Query Language).

How to Create an Event Filter

Create an instance of the CIM_IndicationFilter class. For example.

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

Specify the name of the event filter. For example.
Name = “filter_all_new_solarisdiskdrives”

Create a WQL string to identify event indications to be returned. For example.

String filterString = “SELECT * 
        FROM CIM_InstCreation WHERE sourceInstance 
        is 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 to parse the query string.

Currently, only the WBEM Query Language can be used to part query strings. For example.
```
ci.setProperty(“Name”, new 
        CIMValue("filter_all_new_solarisdiskdrives”));
ci.setProperty("Query", new CIMValue(filterString));
ci.setProperty("QueryLanguage", new CIMValue("WQL");)
```

Create an instance from the cimfilter instance, called filter, and store it in the CIM Object Manager Repository.
CIMObjectPath filter = cc.createInstance(new CIMObjectPath(), ci);

Creating an Event Handler

An event handler is an instance of a CIM_IndicationHandler class. The CIM Event MOF defines a CIM_IndicationHandlerXMLHTTP class for describing the destination for indications to be delivered to client applications using the HTTP protocol. Event delivery to HTTP clients is not supported because HTTP delivery for events is not defined yet.

The Solaris Event MOF extends the CIM_IndicationHandler class by creating the Solaris_RMIDelivery class to handle delivery of indications of CIM events to client applications using the RMI protocol. RMI clients must instantiate the Solaris_RMIDelivery class to set up an RMI delivery location.

An application sets the properties in the CIM_IndicationHandler class to uniquely name the handler and identify the UID of its owner.

Table 6–2 Properties in the CIM_IndicationHandler Class


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. The default for this key property is the name of the creation class for the `CIM_System` class.
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 `CIM_IndicationFilter` as the default for this key property.
Name	The unique name of the handler.	Required. The client application must assign a unique name.
Owner	The name of the entity that created or maintains this handler. 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.

The following example shows the code for creating a CIM event handler.

Example 6–2 Creating a CIM Event Handler

// Create an instance of the Solaris_RMIDelivery class.
CIMClass rmidelivery = cc.getClass(new CIMObjectPath
        (“Solaris_RMIDelivery”), false, true, true, null);

CIMInstance ci = rmidelivery.newInstance();

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

Binding an Event Filter to an Event Handler

An application binds an event filter to an event handler by creating an instance of the CIM_IndicationSubscription class. When a CIM_IndicationSubscription is created, 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 created in How to Create an Event Filter, and defines the handler property to the delivery object created in Example 6–2.

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

Generating an Event Indication

Generating an indication for a CIM event involves:

Using the methods in the EventProvider interface to detect when to start and stop delivering indications of CIM event.
Creating an instance of one or more subclasses of the CIM_Indication class to store information about the CIM event that occurred.
Using the deliverEvent method in the ProviderCIMOMHandle interface to deliver indications to the CIM Object Manager.

Methods in the `EventProvider` Interface

An event provider must implement the EventProvider interface. This interface contains methods that the CIM Object Manager uses to notify the provider when a client has subscribed for indications of CIM events, and when a client has cancelled the subscription for CIM events. These methods also allow the provider to indicate whether or not the CIM Object Manager should poll for some event indications and whether or not the provider should authorize the return of an indication to a handler.

The following table lists the methods in the EventProvider interface that must be executed by an event provider.

Table 6–3 Methods in the EventProvider Interface


Method	Description
`activateFilter`	When a client creates a subscription, the CIM Object Manager calls this method to ask the provider to check for CIM events.
`authorizeFilter`	When a client creates a subscription, the CIM Object Manager calls this method to test if the specified filter expression is allowed.
`deActivateFilter`	When a client removes a subscription, the CIM Object Manager calls this method to ask the provider to deactivate the specified event filter.
`mustPoll`	When a client creates a subscription, the CIM Object Manager calls this method to test if the specified filter expression is allowed by the provider, and if it must be polled.

The CIM Object Manager passes values for the following arguments to all methods:

filter — SelectExp that specifies the CIM events for which indications must be generated.
eventType — String that specifies the type of CIM event, which can also be extracted from the FROM clause of the select expression.
classPath — CIMObjectPath that specifies the name of the class for which the event is required.

In addition, the activateFilter method takes the boolean firstActivation, indicating that this is the first filter for this event type. The deActivateFilter method takes the boolean lastActivation, indicating that this is the last filter for this event type.

Creating and Delivering Indications

When a client application subscribes for indications of CIM events by creating an instance of the CIM_IndicationSubscription class, the CIM Object Manager forwards the request to the appropriate provider. If the provider implements the EventProvider interface, the CIM Object Manager notifies the provider when to start sending indications for the specified events by calling the provider's activateFilter method, and it notifies the provider when to stop sending indications for the specified events by calling the provider's deActivateFilter method.

The provider responds to the CIM Object Manager's requests by creating and delivering an indication each time the provider creates, modifies, or deletes an instance. A provider typically defines a flag variable that is set when the CIM Object Manager calls the activateFilter method and cleared when the CIM Object Manager calls the deActivateFilter method. Then in each method that creates, modifies, or deletes an instance, the provider checks the status of the activate filter flag. If the flag is set, the provider creates an indication containing the created CIM instance object and uses the deliverEvent method to return the indication to the CIM Object Manager. If the flag is not set, the provider does not create and deliver an indication of the event.

Authorizations

A provider that handles sensitive data can check authorizations for requests for indications. The provider must implement the Authorizable interface to indicate that it handles authorization checking. The provider also implements the authorizeFilter method. The CIM Object Manager calls this method to test if the owner (UID) of an event handler is authorized to receive the indications that result from evaluating a filter expression. The UID for the owner of the event destination (event handler) can be different than the owner of the client application requesting the filter activation.

CIM Indication Classes

Providers generate indications of CIM events by creating instances of subclasses of the CIM_Indication class.

The following table lists the intrinsic CIM events that a provider should generate.

Table 6–4 CIM Events Indication Classes


Event Class	Description
`CIM_InstCreation`	Notifies when a new instance is created.
`CIM_InstDeletion`	Notifies when an existing instance is deleted.
`CIM_InstModification`	Notifies when an instance is modified. The indication must include a copy of the previous instance whose change generated the indication.

How to Generate an Event Indication

Implement the EventProvider interface. For example:

public class sampleEventProvider implements 
        InstanceProvider EventProvider{

    // Reference for provider to contact the CIM Object Manager
    private ProviderCIMOMHandle cimom;
   }

Execute each of the methods listed in Table 6–3 for each instance indication that the provider handles.

Create an indication listed in Table 6–4 for each create, modify, and delete instance event type. For example, in the createInstance method:

public CIMObjectPath createInstance(CIMObjectPath op, 
        CIMInstance ci)
    throws CIMException {
        CIMObjectpath newop = ip.createInstance(op, ci);
        CIMInstance indication = new CIMInstance();
        indication.setClassName("CIM_InstCreation");
        CIMProperty cp = new CIMProperty();
        cp.setName("SourceInstance");
        cp.setValue(new CIMValue(ci));
        Vector v = new Vector();
        v.addElement(cp);
        indication.setProperties(v);
        ...
    }

Deliver the event indication to the CIM Object Manager. For example:

cimom.deliverEvent(op.getNameSpace(), indication);
        return newop;