Work the CIM event model efficiently

How to register multiple CIM event handlers with a single connection port

In the Common Information Model (CIM), a client application can subscribe to be notified of CIM events. Normally, an application can create event filters with multiple event handlers through different connection ports, but this consumes lots of network resources and adds much complexity when it comes to maintenance. In this article, see how to register multiple CIM event handlers with a single specific connection port. Also pick up some tips on how to write code with the SBLIM CIM client library.

Hui Yang (hyang@cn.ibm.com), Staff Software Engineer, IBM

Hui Yang is a staff software engineer at the IBM China Systems & Technology Laboratory Laboratories in Shanghai. He is currently working on the Platform Component Configuration Library project, which supplies CIM-related back-end support for the IBM Director and Storage Configuration Manager projects. He is also interested in CIM technology and open source projects, and he will be very happy to play table tennis with you.



Yi Sheng Zhu (zhuyis@cn.ibm.com), Software Engineer, IBM

Yi Sheng Zhu is a software engineer at the IBM China Systems and Technology Laboratories in Shanghai. He is working on the Storage Configuration Manager project. He is also interested in open source projects and football.



Jun Wei Zhang (zhjunwei@cn.ibm.com), Staff Software Engineer, IBM

Jun Wei Zhang is a staff software engineer who joined IBM China Systems and Technology Laboratories in March 2005. He is a member of IBM Storage Configuration Manager Shanghai team, and is currently working on DS8K Agent Provider.



Wen Gang Luo (luoweng@cn.ibm.com), Software Engineer, IBM

Wen Gang Luo is a software engineer at the IBM China Systems & Technology Laboratories in Shanghai. He is currently working on the Cross System Software Test project which focuses on IBM Director and Hatteras testing.



20 August 2008

Also available in Russian

Let's first review some key terms. The Distributed Management Task Force (DMTF) Common Information Model (CIM) is a conceptual information model for describing computing and business entities in enterprise and Internet environments. It provides a consistent definition and structure of data using object-oriented techniques.

A CIM event is the occurrence of a phenomenon of interest, which can be classified as either lifecycle or alert. CIM events are complex and cover a wide range of topics and scenarios. In the CIM architecture, a client application can subscribe to be notified of CIM events. Generally, an application can create event filters with associated event handlers through multiple connection ports.

In this article, we show you how to register CIM event handlers with a a single specific connection port to avoid added complexity. This will make it easier for you to implement and maintain a concrete and operable CIM event model with minimal network resources.

Overview of the CIM event model

The CIM event model defines the event-related abstractions. It describes the CIM indication hierarchy and how to use indications to model events. The event model also describes how to use subscriptions to register so you can receive indications.

An indication may have zero or more event triggers, which are recognitions of changes in state. For example, when a trigger is engaged due to volume creation, this event results in a lifecycle indication that the volume has been created. For another example, when a trigger is engaged due to disk pullout, this event results in an alert indication that the disk has been pulled out.

The specification for CIM operations over HTTP (see Resources for a link) describes the CIM-XML standard for sending and receiving CIM indications. The overall workflow of the CIM event model is shown in Figure 1:

Figure 1. The workflow of CIM event model
The workflow of CIM event model

The entire operation process includes these steps:

  • The CIM Client issues a CIM server process request that creates a subscription over the network; the main function of the process is to register to receive indications.
  • The CIM Object Manager (CIMOM) receives the request and checks its validation. Subsequently, the CIMOM creates CIM indication filters, CIM indication handlers, and CIM indication subscriptions in the CIMOM Repository.
  • The CIMOM contacts the CIM Indication Provider, requesting that the provider generate the appropriate indications in response to requests made by the CIMOM.
  • When the provider generates the indication, the CIMOM routes the indication to the CIM Indication Listener specified by the CIM indication handler instances. These instances are created by the subscribers in the CIMOM Repository.

Technically speaking, three kinds of CIM instances need to be created when the client registers to receive indications in the CIM event model:

  1. A CIM Indication Filter: An instance of CIM_IndicationFilter that defines the set of indications of interest to an indication consumer.
  2. A CIM Indication Handler: An instance of CIM_ListenerDestination that describes the location, encoding, and transport protocol of an indication consumer.
  3. A CIM Indication Subscription: An instance of CIM_IndicationSubscription that describes a flow of indications. The flow is specified by the referenced indication filter and directed to the referenced destination or processed in the indication handler.

The CIM indication class hierarchy is used to describe the type of events that can be detected if the indication subscriptions are defined correctly. An instance of CIM_Indication represents the occurrence of an event. Typically, indications are very short-lived objects used to communicate information from an indication generator to zero or more indication consumers. Following are the related CIM indication classes defined in the CIM event model:

  • Root class
    • CIM_Indication
  • Super class
    • CIM_ClassIndication
    • CIM_InstIndication
    • CIM_ProcessIndication
  • Subclass
    • CIM_ClassCreation
    • CIM_ClassDeletion
    • CIM_ClassModification
    • CIM_InstCreation
    • CIM_InstDeletion
    • CIM_InstMethodCall
    • CIM_InstModification
    • CIM_InstRead
    • CIM_AlertIndication
    • CIM_J2eeNotification
    • CIM_SNMPTrapIndication

All of the classes can be used when you register CIM event handlers in the CIM event model, depending on your specific requirements. We will give you some code examples in the following section and the experiment results at the end.


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. These properties can be set to uniquely identify the filter, specify a query string, and specify the query language that parses the query string. Note that whether properties are mandatory depends on the implementation of the CIM provider on the target CIM server; the format of the string properties can vary slightly between different CIM providers.

Listing 1 shows an example of creating an event filter with SBLIM CIM client library:

Listing 1. Sample code for creating an event filter
// Define the name of CIM class to be created

String   filterClassName = "CIM_IndicationFilter";

// Define the filter string for CIM_IndicationFilter instance

String   filterString = "SELECT * FROM CIM_InstCreation WHERE SourceInstance
 ISA CIM_StorageVolume";

// Get the CIM class definition from the CIMOM

CIMClass filterClass = _client.getClass(new CIMObjectPath(filterClassName));

// Create an instance of the CIM_IndicationFilter class

CIMInstance filterInstance = filterClass.newInstance();

// Set the name of the filter

filterInstance.setProperty("Name",
                            new CIMValue("PCL_Event",
                            new CIMDataType(CIMDataType.STRING)));

// Set the filter string to select CIM events

filterInstance.setProperty("Query",
                            new CIMValue(filterString,
                            new CIMDataType(CIMDataType.STRING)));

// Set the query language (WQL) to parse the query string

filterInstance.setProperty("QueryLanguage",
                            new CIMValue("WQL",
                            new CIMDataType(CIMDataType.STRING)));

// Set the source name space of the filter

filterInstance.setProperty("SourceNamespace",
                            new CIMValue(_namespace,
                            new CIMDataType(CIMDataType.STRING)));

// Create an instance of CIM_IndicationFilter on the target CIM server

CIMObjectPath filterCOP = _client.createInstance(new CIMObjectPath(),
                                                 filterInstance);

Creating an event handler with single connection port

Generally, an application can create event listeners with event handlers through multiple connection ports, but this is costly in terms of network resources and maintenance.

By using two classes—CIMEventDispatcher and HttpServerConnection as defined in the SBLIM CIM Client Library—CIM event handlers can be registered with a single specific connection port. The overall process is shown in Figure 2.

Figure 2. Dispatch events to event handlers with a single connection port
Dispatch events to event handlers with a single connection port

There are two steps for creating event handlers with the same port:

  1. Register the listener at the client side.
  2. Create the listener instance with the destination information at the provider side.

Listings 2 and 3 show you how.

Listing 2. Registering the listener at the client side
// Create a CIMIndicationListenertList instance

CIMIndicationListenertList _indicationClient = 
new CIMIndicationListenertList();
        
/* 
* Add a inner listener to the list, because if there is only one listener in
* CIMIndicationListenertList, it will get all event no matter the event is the
* certain listener registered to listen or not, we need to add a InnerListener
* which implements CIMListener and doing nothing
*/

_indicationClient.addListener(new InnerListener());

/*
* Add IndicationListenerList to a dispatcher, CIMEvent will be dispatched to
* target listener according to the hash code of one listener
*/

CIMEventDispatcher dispatcher = new CIMEventDispatcher(_indicationClient);

// Create an new CIMIndicationHandler instance which wraps the dispatcher

CIMIndicationHandler indicationHdlr = new CIMIndicationHandler(dispatcher);

// Create a HttpServerConnection with the specified port
// NOTE: This target port is shared by all the event handlers

HttpServerConnection _serverConn = new HttpServerConnection(
                     new HttpConnectionHandler(indicationHdlr), targetPort);
_serverConn.setName("CIMListener - Http Server");
_serverConn.start();

// You can also add listener after HttpServerConnection has started
Listing 3. Creating the listener instance at the provider side
// Create internal listener, InternalListener should implement CIMListener and
// have its own function

InternalListener internalListener = new InternalListener();

// Add internal listener to CIMIndicationListenertList instance

_indicationClient.addListener(internalListener);

// Create a listener destination instance

CIMClass    indicationDestinationClass = _client.getClass(
                  new CIMObjectPath("CIM_ListenerDestinationCIMXML"), false);
CIMInstance cimListener = indicationDestinationClass.newInstance();

// Set the properties of CIM instance, and which properties are mandatory are
// highly depending on the implementation of CIM providers
// Set the creation class name of the listener

cimListener.updateProperty(new CIMProperty("CreationClassName",
                       new CIMValue("CIM_ListenerDestinationCIMXML",
                       CIMDataType.getPredefinedType(CIMDataType.STRING))));

// Set the system creation class name of the listener

cimListener.updateProperty(new CIMProperty("SystemCreationClassName",
                       new CIMValue(null, 
                       CIMDataType.getPredefinedType(CIMDataType.STRING))));

// Set the system name of the listener

cimListener.updateProperty(new CIMProperty("SystemName",
                       new CIMValue(null, 
                       CIMDataType.getPredefinedType(CIMDataType.STRING))));

// Set the name of the listener

cimListener.updateProperty(new CIMProperty("Name",
                       new CIMValue(listenerName, 
                       CIMDataType.getPredefinedType(CIMDataType.STRING))));

// Set destination value, it should be combined with IP address of client and
// hash code of the listener object

cimListener.updateProperty(new CIMProperty("Destination", 
                           new CIMValue(IPAddress +
                                         "/" +
                                         internalListener.hashCode(),
                      CIMDataType.getPredefinedType(CIMDataType.STRING))));

// Register the listener destination on the target CIM server

CIMObjectPath listenerCOP = _client.createInstance(new CIMObjectPath(),
                                                    cimListener);

Binding an event filter to an event handler

Event filters define the conditions chosen to act as a filter. Event handlers describe the action that will be taken after a specific event occurs.

So, binding an event filter to an event handler means you're setting up a situation in which specific actions will be taken when a particular event happens.

There are two properties in the CIM class CIM_IndicationSubscription:

  • Filter refers to the object path of one event filter instance.
  • Handler refers to the object path of one event handler instance.

When you bind an event filter to an event handler, you are creating an instance of the CIM_IndicationSubscription class and setting the properties Filter and Handler of that instance. When you create an indication of this class, indications for the events specified by the event filter are delivered.

Under the CIM event model, the relationship between event filter and event handler is can be represented by m:n, which means that one event filter can be bound to multiple event handlers, or that one event handler can be bound to multiple event filters. Figures 3 and 4 demonstrate both conditions.

Figure 3. Register one event filter with multiple event handlers
Register one event filter with multiple event handlers
Figure 4. Register multiple event filters for one event handler
Register multiple event filters for one event handler

Listing 4 shows how to bind an event handler to an event filter with the SBLIM CIM client library.

Listing 4. Sample code for binding an event filter to an event handler
// Define class name of indication subscription

String subscriptionClassName = "CIM_IndicationSubscription";

// Construct object path of CIM_IndicationSubscription 

CIMObjectPath cop = new CIMObjectPath(subscriptionClassName, _namespace);

// Get the  CIMClass object for subscription

CIMClass subscriptionClass = _client.getClass(cop);

// Create CIM_IndicationSubscription instance and set properties

CIMInstance subscriptionInstance = subscriptionClass.newInstance();

// Set object path of event filter instance as the value of "Filter" property

subscriptionInstance.setProperty("Filter",
                                new CIMValue(filterInstance.getObjectPath(), 
                                new CIMDataType(CIMDataType.REFERENCE)));

// Set object path of event handler instance as the value of "Handler" property

subscriptionInstance.setProperty("Handler",
                               new CIMValue(handlerInstance.getObjectPath(), 
                               new CIMDataType(CIMDataType.REFERENCE)));

// Create CIM_IndicationSubscription instance on the target CIM server

CIMObjectPath sop = _client.createInstance(new CIMObjectPath(),
                                          subscriptionInstance);

Test results on Linux

We deployed our implementation on Linux® and did some testing. When the CIM event handlers are registered on the target CIM server, we were able to get the connection information of each established listener.

Figure 5 shows the typical network status; each listener has its own communication port.

Figure 5. Register CIM event handlers, typical case
Register CIM event handlers with normal case

Figure 6 shows the network status with our implementation. You can see that all of the listeners share the same communication port.

Figure 6. Register CIM event handlers, our implementation
Register CIM event handlers with our solution

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Linux on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Linux
ArticleID=332341
ArticleTitle=Work the CIM event model efficiently
publish-date=08202008