Sun WBEM SDK Developer's Guide

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));