Contents


Work the CIM event model efficiently

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

Comments

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 Related topics 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 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
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
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
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
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
Register CIM event handlers with our solution

Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

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