Introduction

With the release of IBM® WebSphere® Business Integration Server Foundation V5.1.1 comes the ability to put the Common Event Infrastructure (hereafter called CEI) to into full use. The technical preview in V5.1 provided developers with a glimpse into the potential of the CEI for creating, managing, and distributing event information.

This article provides an overview of the changes and added functionality of the Common Event Infrastructure from technical preview to production release. As well as giving a summary of the new features, it also looks at what changes a developer needs to be aware of having previously used the technical preview.

Developers who have used the technical preview and want infomation about the changes and new features contained in the production release will find this article particularly useful. It also provides an overview for anyone looking to use the Common Event Infrastructure.

Applications running in both J2EE and J2SE environments act as event sources to create and send events to the CEI server. When a significant business or system event occurs, the application creates a Common Base Event (hereafter called CBE) containing data describing the details of event. The CBE is then sent to the CEI server, using an event emitter, either synchronously or asynchronously. The CEI server may then persist and/or distribute the event to registered listeners. The production release adds:

• An Event Catalog component that can be used to store event definitions.
• An Event Access component that allows events to be retrieved from the CEI server using a subset of the XPath language for defining queries.
• An ECSEmitter that can be used within the Application Server environment for creating, correlating and sending events.

The rest of this document describes the differences and enhancements from the technical preview of the CEI to the production release in Version 5.1.1.

Back to top

Using the CEI in a WebSphere Application Server environment

The production release of the CEI adds a new package, com.ibm.websphere.cem (hereafter called Common Event Model), which combines event creation, correlation, and emission functions into a single class, com.ibm.websphere.cem.ECSEmitter.

In the technical preview, CBE instances are created using an EventFactory. This has not changed, except of course that the class has moved to org.eclipse.hyades.logging.events.cbe.EventFactory. In the technical preview, two event factories are bound in to the WebSphere JNDI namespace: a generic factory and a WebSphere-specific factory.

The generic event factory is unchanged. The code sample below demonstrates how to obtain the generic Event Factory and create a CBE instance:

import org.eclipse.hyades.logging.events.cbe.*

EventFactory eventFactory = (EventFactory)
	javax.rmi.PortableRemoteObject.narrow(
		initialContext.lookup("com/ibm/events/EventFactory"),
		EventFactory.class);

CommonBaseEvent cbe = eventFactory.createCommonBaseEvent();

Applications running inside the Application Server are recommended to use the ECSEmitter instead. The following code sample shows how to create a CBE instance using this method.

import com.ibm.websphere.cem.ECSEmitter;
import org.eclipse.hyades.logging.events.cbe.CommonBaseEvent;

ECSEmitter emitter = new ECSEmitter("com/ibm/events/emitter/Default", null);
CommonBaseEvent cbe = emitter.createCommonBaseEvent("eventName");

The parameters passed to create the ECS Emitter will be explained in the section entitled Emitting Events below.

Back to top

The Common Base Event

Event instances in the technical preview are modelled by classes in the com.ibm.events.cbe package. For example, the top-level CBE class is called com.ibm.events.cbe.CommonBaseEvent. The location of these classes changes in the production release, due to use of the CBE classes in the Eclipse Tools Hyades Project. The classes may now be found in the org.eclipse.hyades.logging.events.cbe package. Developers that have experimented with the technical preview and wish to reuse their code must therefore change their package imports:

import org.eclipse.hyades.logging.events.cbe.*;

CommonBaseEvent event = ...;

The classes, methods and attributes in the Hyades package are virtually identical, with only some minor changes have been made to the XML serialization code known at time of writing. For more information on the CBE specification and the Hyades project, refer to the Resources section at the end of this article.

Back to top

Populating events

The way in which data in manually added to events is unchanged. However the manner in which business context data is created and automatically added by the Application Server to events is different.

In the technical preview, the Business Context Data Service (BCDS) enables users to define a collection of named contexts, each containing name-value pairs relevant to that context. This context data is then inserted in to the event via the WebSphere specific content handler on the event instance. The content handler may be invoked either by the user, calling the complete(), method on the event instance, or at the point of emission where the emitter invokes the complete() method.

For example, a business with a BPEL business process used for capturing customer details via a website defines a business context instance for "completing customer details" and inserts context name-value pairs that are copied in to every CBE that is emitted within that process.

In the production release, the functionality of the BCDS used for event correlation is integrated in to the new ECSEmitter class. The ECSEmitter introduces the concept of an Event Correlation Sphere (hence ECS). The ECSEmitter provides methods for setting the current and parent correlation sphere IDs.

An event correlation sphere is a string identifier that may be used to correlate events that belong to a particular business process or context. Events sent by the ECSEmitter can contain two correlation sphere identities; a current sphere and a parent sphere.

The ECSEmitter provides the following methods to get and set these IDs: getParentEcsId(), getCurrentEcsID(), setCurrentEcsID(String currentID), setParentEcsID(String parentID). The current ECS ID may also be set during the construction of an ECSEmitter instance.

When the current correlation ID is set the previous current ID overwrites the parent ID. If the sphere IDs are set they will be inserted in to the event during the sendEvent(...) method of the ECSEmitter inside context data elements as follows:

<contextDataElements name="ECSCurrentID" type="ECSID"> 
   <contextValue>current ECS ID</contextValue>
</contextDataElements>
<contextDataElements name="ECSParentID" type="ECSID">
   <contextValue>parent ECS ID</contextValue>
</contextDataElements> 

To easily send reporting events containing extended data elements the ECSEmitter also provides an addUserDataEvent(java.util.Properties) method. This method emits an event to the CEI server with the properties set as extended data elements in the CBE. Figure 2 below shows other data that is set in the event when this method is used.

Table 1. Event data added when using ECSEmitter.addUserDataEvent(...) method

The following code snippet shows how you can use the addUserDataEvent(Properties) method.

Properties properties = new Properties();
properties.addProperty("MyPropertyNameA", "MyPropertyValueA");
properties.addProperty("MyPropertyNameB", "MyPropertyValueB");
emitter.addUserDataEvent(properties);

This code sends an event to the CEI server without the need to create a CBE first.

Back to top

Emitting events

When a CBE instance has been populated, the event source can send the event to the CEI server using one of the sendEvent(...) methods of a emitter instance: com.ibm.events.emitter.Emitter.

The technical preview events only support sending events synchronously to the event server, using an EJB interface. The production release adds the ability to send events asynchronously via JMS. This, for example, allows the event source to continue processing after emitting an event rather than blocking until the event has been successfully transmitted and processed by the event server. Administrators configure the synchronization mode of each emitter to suit their own application requirements.

In addition to the EventBusTransmissionProfile for synchronous transmission, there is now a JMSTransmissionProfile containing the JNDI names for the JMS Queue and Queue Connection Factory to be used by the emitter. If asynchronous transmission is required, the application server must, of course, be configured with the appropriate JMS Queue and Queue Connection Factory. In addition to this, CEI server must be enabled to listen for events appearing in the specified JMS queue. A JACL script called event-message.jacl is located in /event/application/ and can be used to create an emitter and all the appropriate resources required to send events asynchronously.

Within the Application Server environment the ECSEmitter removes the need to perform the lookup of a CEI Emitter from JNDI. The ECSEmitter class is illustrated below in Figure 3 and defines the constructor:

ECSEmitter(String emitterJNDIName, String ecsId)

The ECSEmitter obtains the EmitterFactory from JNDI using the JNDI name passed in on the contructor. It creates the CBE and provides methods to populate it with data before sending it to the CEI server.

The code snippet below shows how to create an ECSEmitter instance:

import com.ibm.websphere.cem.ECSEmitter;

ECSEmitter emitter = new ECSEmitter(
	"com/ibm/events/emitter/Default", 
	"mySphereID");

If you do not want to have the event source set the current correlation sphere ID, you should pass null in as the second parameter. For further information on constructing the ECSEmitter refer to the Infocenter and API documentation.

Back to top

Event filtering

The production release enables administrators to configure emitters to filter events, that is, to discard events within the emitter so they are not sent to the event server. A Filter Factory Profile is created and configured with an XPath-like expression that is used to determine if the CBE should be sent to the CEI server. For example, setting the filter expression to CommonBaseEvent[@severity = 50] would cause the emitter to only send events to the event server that have a severity of precisely 50.

To enable an emitter to use a filter factory profile, enter the JNDI name in the emitters FilterFactoryProfileJNDIName attribute as well configuring it to enabling filtering.

In addition to using the profile described above, users can create their own filter and bind it into JNDI. To create a custom event filter:

1. Create a filter by implementing the com.ibm.events.filter.Filter interface.
2. Create a filter factory by implementing the com.ibm.events.filter.FilterFactory.
3. Bind a FilterFactory instance into JNDI.
4. Enter this JNDI name into the emitter's Filter Factory JNDI Name attribute.

The factory is obtained by the emitter during initialization in the event source and is used to create an instance of a Filter. Notice that it is not possible for an event source to bypass a filter configured by an emitter.

Back to top

Event distribution

The production release introduces a new concept called event consumers. Whereas applications that create and send events to the CEI server are called event sources, event consumers subscribe and listen for events. An administrator can configure event group profiles contained within an event group profile list. An event group profile object defines a selector string which determines which events belong to this group. These selector strings use the same XPath-like syntax as the filter configuration.

Each event group profile can be associated with a JMS topic and multiple JMS queues. When the CEI server receives an event (and provided that event distribution is enabled), it attempts to match the event to an event group. If the event matches a group, it then publishes the CBE to the JMS queue or topic configured for that event group. Consumers can listen for events on the appropriate JMS queue or subscribe to the JMS topic to process the event information.

Figure 4 shows the classes and concepts of an event group profile list that contains a list of event group profiles. Each event group profile can contain multiple distribution queues.

Example using distribution

Two event group profiles have been created:

Table 2. Event group profiles

EventGroupA contains two distribution queue definitions but EventGroupB contains none.

If the CEI server receives a CBE and distribution is enabled, it will check to see if the event matches any of the event groups configured in the EventGroupProfileList. If the CBE has a severity field with its value set to 70, then it will match 'EventGroupA' and send the CBE information to the any JMS resources configured for that Group (in this case the two JMS resources specified in the DistributionQueue resources).

If consumers wish to listen for events on a particular resource, then they can use an Message Driven Bean (MDB). The CEI provides a helper object, called the NotificiationHelper, that obtains the information from a JMS resource and converts it in to a CBE instance. The NotificationHelper is created from a NotificationHelperFactory object bound into JNDI under com/ibm/events/NotificationHelperFactory. When a message is received on the onMessage() method, the CBE can be obtained using the getCreatedMessage(javax.jms.Message message) method.

Back to top

Event access API

The full event access API has been delivered in the production release of the CEI. This provides a powerful API for retrieving events based on particular criteria.

The technical preview supports the retrieval of events via event group and GUID. The production release supports the use of event selectors that can be used to select events based on their contents. The event selector syntax is a subset of the W3C XPath (this is not a coincidence as the Common Base Event specification describes events in terms of their serialization as XML documents).

For example, given the following event, users could retrieve all events that came over IPv4 using the event selector string CommonBaseEvent/sourceComponentId/locationTtype='IPv4'; or retrieve all events that happened after this using CommonBaseEvent/@creationTime > '2004-07-25T11:53:59.403Z'.

<?xml version="quot1.0" encoding="ASCII"?>
<CommonBaseEvent 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:="http://www.ibm.com/AC/commonbaseevent1_0_1"
    creationTime="2004-07-24T11:53:59.403Z"
    globalInstanceId="CE264B5C800D6811D884C5BF68E0F9AC22"
    sequenceNumber="1"
>
  <situation categoryName="OtherSituation">
    <situationType xsi:type="OtherSituation" reasoningScope=
       "EXTERNAL" any="Application Event"
  />
  </situation>
  <sourceComponentId 
      component="J2EE Component"
      componentType="My Stateless Session EJB"
      componentIdType="Stateless Session Bean"
      location="127.0.0.1"
      locationType="IPv4"
      subComponent="None"
  />
</CommonBaseEvent>

Getting access to the Event Access API is very simple. The entry point is unchanged from the technical preview that is by using a stateless session bean bound with the JNDI name /ibm/events/access/EventAccess. The interface returned will be com.ibm.events.access.EventAccessHome. The object returned by the create method on this home interface provides all the methods required for the different types of querying. The example queries described above would be executed using the following code snippet:

EventAccessHome home = (EventAccessHome)
	PortableRemoteObject.narrow(ctx.lookup(EVENT_ACCESS_JNDI_NAME),
       EventAccessHome.class);

EventAccess eventAccess = home.create();

CommonBaseEvent results[];

results = eventAccess.queryEventsByEventGroup(
	"All events",
	"CommonBaseEvent/sourceComponentId/@locationType='aposIPv4'apos",
	true);

results = eventAccess.queryEventsByEventGroup(
	"All events",
	CommonBaseEvent/@creationTime > '2004-07-25T11:53:59.403Z'pos,
	true);

eventAccess.close();

Back to top

Event catalog

The Event catalog is a repository of event meta-data and provides the user with the ability to specify event definitions. It defines a set of API's that the user can use to add, query and remove event definitions from the repository. An event definition consists of its name, the name of any parent event definition, the extended data elements, and event properties that it can contain. An event definition can also be bound to an event category that is used to define logical groupings of event definitions.

The Event Catalog is implemented using a stateless session bean and can be accessed by looking up the home interface from JNDI as shown below:

EventCatalogHome eventCatalogHome = (EventCatalogHome)
	javax.rmi.PortableRemoteObject.narrow(
	initialContext.lookup("quotejb/com/ibm/events/catalog.EventCatalog"),
	EventCatalogHome.class)

EventCatalog eventCatalog = (EventCatalog) eventCatalogHome.create();

You can use the event definition to define what properties a particular event should contain. However, if you want your applications to use this information to validate events, then these applications must write their own validation logic. Each time an event definition is modified or added, an event will be sent to the CEI server.

This article can only provide a brief introduction as the Event catalog would on its own require a further article to describe how users can add, remove, and query event definitions and categories. For additional information, refer to the API documentation.

Back to top

Command line utilities

The production release adds some new command line utilities, JACL scripts, located in the /event/bin directory that can be used to perform the following operations on the CEI

• Emit events
• Query the Event Catalog
• Query events persisted by the event server
• Purge persisted events from the event server

Each file lists the parameters needed to use the JACL scripts and provides examples. To run the scripts, use the WSAdmin command (wsadmin.bat or wsadmin.sh depending on your platform of choice) line tool located in /bin directory.

Example invocations:
wsadmin -f emitevent.jacl
WASX7209I: Connected to process "server1" on node ozona using SOAP connector;
The type of process is: UnManagedProcess
Successfully submitted event(s) with global instance id(s): CEFD55B434391C9FB9E62154D0E13511D8

wsadmin -f eventquery.jacl -globalinstanceid CEFD55B434391C9FB9E62154D0E13511D8
WASX7209I: Connected to process "server1" on node ozona using SOAP connector;  
     The type of process is: UnManagedProcess
<CommonBaseEvent
        creationTime="2004-07-29T08:04:19.180Z"
        globalInstanceId="CEFD55B434391C9FB9E62154D0E13511D8"
        sequenceNumber="1" version="1.0.1">
    <sourceComponentId component="emitevent.jacl" componentIdType="Application" location="ozona"
            locationType="Hostname" subComponent="com.ibm.events.cli.util.EmitEventCliHelper" 
            componentType="http://www.ibm.com/namespaces/autonomic/Tivoli/EventInfrastructure"/>

        <situation categoryName="ReportSituation">

            <situationType xsi:type="ReportSituation" reasoningScope="EXTERNAL"
               reportCategory="CLI"/>
        </situation>
</CommonBaseEven>
1 Event(s) returned.
wsadmin -f eventpurge.jacl -group "All events" -seconds 10
WASX7209I: Connected to process "server1" on node ozona using SOAP connector;
The type of process is: UnManagedProcess
1 Event(s) deleted.

Back to top

Conclusion

The production release of the CEI contained within WebSphere Business Integration Server Foundation builds substantially on the technical preview offering for providing a complete event infrastructure for both technical and business events.

This article provides a quick-reference guide for the new functionality offered in the technical preview. It is specifically targeted at developers who have previously experimented with the technical preview.

Resources

• Standardize messages with the Common Base Event model
  
  
• Common Base Event specification
  
  
• IBM WebSphere Developer Technical Journal: Using the Common Base Event in the Common Event Infrastructure
  
  
• WebSphere Business Integration zone
  
  
• IBM WebSphere Developer Technical Journal
  
  

About the authors

Andy Brodie worked on the development of the Common Event Infrastructure, specifically on the design and implementation of the emitter component. He also contributed to the development of WebSphere Application Server Enterprise.

Amanda Watkinson is a Software Engineer at IBM Hursley Lab in Winchester, England. Amanda has worked on numerous WebSphere projects, including the configuration management of the Common Event Infrastructure technical preview release.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Using the CEI in a WebSphere Application Server environment
• The Common Base Event
• Populating events
• Emitting events
• Event filtering
• Event distribution
• Event access API
• Event catalog
• Command line utilities
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers