Sun Microsystems, Inc.
spacerspacer
spacer www.sun.com docs.sun.com |
spacer
black dot
 
 
Chapter 3, Writing a Client Program Batching Client Requests   Previous   Contents   Next 
   
 

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:

  1. 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.

  2. 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.

  3. activateFilter - Invoked by the CIM Object Manager when the authorization succeeds and the provider does not want to be polled.

  4. 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.

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

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

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

  4. 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

  1. Create an instance of the CIM_IndicationFilter class:

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

  2. Specify the name of the event filter:

    Name = "filter_all_new_solarisdiskdrives"

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

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

  4. 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");)

  5. 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

 		 
 
  Previous   Contents   Next