Using Process Indications

This chapter describes CIM process indications; how they are used to communicate the occurrence of events; and the classes that enable clients to subscribe to receive CIM process indications. This chapter includes the following topics:

• The CIM Event Model
• How Indications are Generated
• How Subscriptions Are Created
• Adding a CIM Listener
• Creating an Event Filter
• Creating an Event Handler
• Binding an Event Filter to an Event Handler

For more information about process indication classes, see Chapter 4, "Classes, Domains, Associations, and Indications in WDR."

---

Note - For more in-depth information on the CIM Event Model, see the Distributed Management Task Force white paper at http://www.dmtf.org/education/whitepapers.php.

---

---

The CIM Event Model

---

Tip - The CIM Event API is located at /usr/sadm/lib/wbem/doc/javax/wbem/client/CIMEvent.html.

---

An event is a real-world occurrence. A process indication is an object that is created as a result of the occurrence of an event. It is important to distinguish between the event; and the process indication, which is a notification of the event. In CIM, events are not published; process indications are published.

A process indication is a subtype of a class that has an association with zero or more triggers (descriptions of changes in data that result from events) that can create instances of the Indication class. The WBEM implementation does not have an explicitly defined object that represents a trigger. Triggers are implied either by the operations on basic objects of the system (create, delete, and modify on classes, instances, and namespaces) or by events in the managed environment. When an event takes place, the WBEM provider generates a process indication that something happened in the system.

For example, with a Service class, when the service stops and a trigger is engaged, it results in a process indication that serves as notification that the service stopped.

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

• Root class: CIM_Indication
• Superclass: CIM_ClassIndication
• Subclasses: CIM_ClassCreation
• CIM_ClassDeletion
• CIM_ClassModification
• Superclass: CIM_InstIndication
• Subclasses: CIM_InstCreation
• CIM_InstDeletion
• CIM_InstMethodRecall
• CIM_InstRead
• Superclass: CIM_ProcessIndication

The CIM_ProcessIndication superclass resides at the top of the The WDR Indication Class Hierarchy Diagram.

---

How Indications are Generated

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

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 (part number 806-6468-10).

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 interface to contact the appropriate 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.

---

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.

An application that subscribes for indications of CIM events describes:

• The events in which it is interested.
• The action that the CIM Object Manager must take when each event occurs.

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.

To create a subscription, specify an instance of the CIMListener interface and create instances of the following subclasses of the CIM_Indication class:

CIM_IndicationFilter -- Defines the criteria for generating an indication and which data should be returned in the indication.

CIM_IndicationHandler -- Describes how to process and handle an indication. May include a destination and a protocol for delivering indications.

CIM_IndicationSubscription -- An association that binds an event filter with an event handler.

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.

---

Adding a CIM Listener

To register for indications of CIM events, add an instance of the CIMListener interface. 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 indicationOccurred method which takes the argument CIMEvent. This method is invoked when an indication is available for delivery.

To Add a CIM Listener

Use code such as the following to add 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 identify the filter uniquely, specify a query string, and set the query language used to parse the query string, as shown in the following table. Currently, only the WBEM Query Language is supported.

TABLE 3-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 CIMSystem.Creation ClassName
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 that was 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 expressions are supported. To learn how to construct WQL query expressions, see the section "Querying" in the Sun WBEM SDK Developer's Guide (part number 806-6831-10).	Required
QueryLanguage	The language in which the query expression is written.	Required. The default is WQL (WBEM Query Language).

To Create an Event Filter

1. Create an instance of the CIM_IndicationFilter Class, using code such as the following:

CIMClass cimfilter = cc.getClass

(new CIMObjectPath(``CIM_IndicationFilter''), true, true, true, null);CIMInstance ci = cimfilter.newInstance();

2. Specify the name of the event filter, using code such as the following:

Name = ``filter_all_new_solarisdiskdrives'';

3. Create a WQL string to identify event indications to be returned, using code such as the following:

String filterString = ``SELECT *

FROM CIM_InstCreation WHERE sourceInstance is
ISA Solaris_DiskDrive''

4. Set property values in the cimfilter instance to identify the name of the filter, the filter string that selects CIM events, and the query language used to parse the query string, using code such as the following.

---

Note - Currently, only the WBEM Query Language can be used to parse query strings.

---

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 from the cimfilter instance and store it in the CIM Object Manager Repository, using code such as the following:

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

---

Creating an Event Handler

The Solaris Event MOF extends the CIM_IndicationHandler class by creating the Solaris_JAVARXMIDelivery 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. Clients can use only RMI to receive events; HTTP is not supported.

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

TABLE 3-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. Set by the CIM Object Manager.
SystemName	The name of the system on which the handler 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 that was used to create the handler	Optional. The CIM Object Manager assigns the appropriate class 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 that 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 is creating the instance.

To Create a CIM Event Handler

To create a CIM event handler, use code such as the following:

 

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

To Bind an Event Filter to an Event Handler

The following example code creates a subscription (filterdelivery) and defines the filter property to the filter object that was created in Creating an Event Filter, and defines the handler property to the delivery object created in To Create a CIM 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);