Work the CIM event model efficiently
How to register multiple CIM event handlers with a single connection port
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 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:
- A CIM Indication Filter: An instance of
CIM_IndicationFilterthat defines the set of indications of interest to an indication consumer.
- A CIM Indication Handler: An instance of
CIM_ListenerDestinationthat describes the location, encoding, and transport protocol of an indication consumer.
- A CIM Indication Subscription: An instance of
CIM_IndicationSubscriptionthat 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
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
- Super class
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
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—
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
There are two steps for creating event handlers with the same port:
- Register the listener at the client side.
- 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
Filterrefers to the object path of one event filter instance.
Handlerrefers 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
class and setting the properties
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
Figure 4. 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
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
- The "CIM Event Model White Paper" provides further details on the CIM event model and how it defines event-related abstractions, the CIM indication hierarchy, the use of indications to model events, and the use of subscriptions to register to receive indications.
- "Instrumentation for Linux Event Log Analysis" describes the interaction of Linux, CIM, and events; its log analysis solution for Linux is based on CIM event handling.
- This CIM tutorial takes you from novice to expert in understanding the Common Information Model.
Try these emerging technologies from IBM alphaWorks:
- The Testing Tool for Common Information Model (CIM) Providers (alphaWorks, April 2008) provides a common interface for testing the functionality of different types of CIM providers based on the CIM specification.
- The IBM CIM Provider Certification Tool (alphaWorks, January 2007) eases verification of CIM providers.
- The CIM Modeling and Monitoring tool (alphaWorks, January 2008) is a suite of tools for modeling CIM class structure and monitoring CIM-managed objects.
- The IBM Mining Tool for Common Information Model (CIM) Test Simulation (alphaWorks, July 2007) is designed for localized test simulation of multiple devices communicating as CIMOM objects.
- In the developerWorks Linux zone, find more resources for Linux developers, and scan our most popular articles and tutorials.
- See all Linux tips and Linux tutorials on developerWorks.