JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris WBEM Developer's Guide     Oracle Solaris 11 Express 11/10
search filter icon
search icon

Document Information

Preface

1.  Overview of Solaris Web-Based Enterprise Management

2.  Using the CIM Object Manager

3.  Using the Sample Programs

4.  Writing a Client Program

Client API Overview

Sequence of a Client Application

Opening and Closing a Client Connection

About Namespaces

Opening a Client Connection

Closing a Client Connection

Performing Basic Client Operations

Creating an Instance

Deleting an Instance

Getting and Setting Instances

Getting and Setting Properties

Enumerating Objects

Enumerating Objects

Creating Associations

About the Association Methods

Passing a Class to the Association Methods

Passing Instances to the Association Methods

Using Optional Arguments With the Association Methods

Calling Methods

Retrieving Class Definitions

Handling Exceptions

Creating a Namespace

Deleting a Namespace

Creating a Base Class

Deleting a Class

Setting Access Control

Solaris_UserAcl Class

To Set Access Control for a User

Solaris_NamespaceAcl Class

To Set Access Control for a Namespace

Working With Qualifiers and Qualifier Types

Getting and Setting CIM Qualifiers

Batching Client Requests

Handling CIM Events

About Indications

About Subscriptions

To Create a Subscription

Adding a CIM Listener

Creating an Event Filter

To Create an Event Filter

Creating an Event Handler

Binding an Event Filter to an Event Handler

Reading and Writing Log Messages

About Log Files

5.  Writing WBEM Queries

6.  Writing a Provider Program

7.  Creating JavaBeans Components Using the MOF Compiler

8.  Administering Security

9.  Troubleshooting

A.  Solaris Schema

Index

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 dmtf.org/education.


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:

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 file:/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 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:

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:

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

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

    If the provider does not implement the EventProvider interface and the CIMOM tries to poll, the authorization succeeds if enumerateInstances succeeds on the provider.

  3. activateFilter– Invoked by the CIMOM 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 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 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 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 name space 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_IndicationFilteras 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 name space 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_solarisdiskdrive"
  3. Create a WQL string identifying 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 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");)
  5. Create a cimfilter instance that 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);