IBM WebSphere Developer Technical Journal: Using the Common Base Event in the Common Event Infrastructure

A peek at a WebSphere Business Integration technical preview

This article demonstrates how to create Common Base Events from business events and system events that can be consumed by the Common Event Infrastructure, which was released as a technical preview in IBM® WebSphere® Business Integration Server Foundation V5.1.

Share:

Amanda Watkinson (amanda.watkinson@uk.ibm.com), Software Engineer, EMC

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.


developerWorks Contributing author
        level

04 August 2004

Introduction

IBM WebSphere Business Integration Server Foundation V5.1 includes the Common Event Infrastructure technology preview, which can be used to create, store, and distribute events. The Common Base Event, within the Common Event Infrastructure, provides a means of capturing information about significant system or business occurrences. For example:

  • A significant system event may be when a particular server's performance drops below a critical threshold.
  • A significant business event encapsulates information that is specific to a particular business; for example, when an important customer places an order, you might want to store extra information or alert individuals that this event has occurred.

Although the Common Base Event provides certain standard information, a programming API enables users to populate the event with information specific to their own business requirements. This article provides an introduction to the Common Base Event (CBE) as part of the Common Event Infrastructure (CEI) service, and demonstrates different methods for creating and populating an event to capture and correlate both system and business behavior.


Common Event Infrastructure and Common Base Event API

Figure 1 provides an overview of the Common Event Infrastructure:

  • An application obtains an EventFactory object from JNDI. This object is the access point for the common base event and provides an API to create an empty event.
  • The empty common base event is populated with data and passed to the CEI server (using an emitter), where the event can be persisted or distributed to consumers.
  • Emitters are created from an EmitterFactory object bound into JNDI. Emitters can be configured to have different behavior in terms of how they filter out events, how they process transactions, and their transmission modes. (This article does not describe in any detail the behavior and functionality of the EmitterFactory and CEI server. They are mentioned only to provide a conceptual overview of how the CBE fits into the CEI service.)
Figure 1. Overview of the Common Event Infrastructure
Common Event Infrastructure Overview

The CEI provides a Java programming interface for creating an event. The sections that follow explain how to create a common base event, populate it with system and business information, and also describe some of the CBE attributes and methods for creating application and business-specific data. The information then all comes together to demonstrate how a common base event can be created.


Obtain an EventFactory Object

The EventFactory is the starting point for the common base event. There are three different ways of obtaining and using an EventFactory to generate common base events. The following characteristics distinguish these methods:

  • The first method describes how to obtain a simple EventFactory object, whereas the second and third methods describe how to obtain an EventFactory object with ContentHandlers; ContentHandler objects provide a method to complete the population of an event, and are called either when a user explicitly calls the complete() method on the CBE, or by the emitter prior to sending the event to the CEI server.
  • The second method looks at the WebSphere-specific EventFactory, whereas the third method shows how an application running outside of the WebSphere environment can create its own EventFactory with ContentHandler.

Information on each method follows:

  1. Obtain a generic EventFactory
    This EventFactory provides an API for generating common base events and their associated attributes. Listing 1 shows how this EventFactory object is obtained. The EventFactory is bound into JNDI under com/ibm/events/EventFactory.

    Listing 1.

    import com.ibm.events.cbe.*;
    
    EventFactory eventFactory = (EventFactory)javax.rmi.PortableRemoteObject.narrow
    	(initialContext.lookup("com/ibm/events/EventFactory"), EventFactory.class);
  2. Obtain a WebSphere-specific EventFactory
    This EventFactory is similar to the generic EventFactory, except that it is associated with a ContentHandler object. When the common base event is sent to the CEI service, it automatically completes the SourceComponentId attribute, unless the application specifically overrides the values. (See Populate a Common Base Event for more on the SourceComponentId attribute.) However, by using this EventFactory the SourceComponentId field is filled with information specific to the WebSphere environment. The WebSphere EventFactory object is bound into JNDI under com/ibm/websphere/events/factory. This EventFactory should be used by all applications running in the WebSphere server environment in order to ensure that the SourceComponentId is consistently filled out.

    Listing 2.

    EventFactory eventFactory = (EventFactory)javax.rmi.PortableRemoteObject.narrow
    	(initialContext.lookup("com/ibm/websphere/events/factory"), EventFactory.class);
  3. Obtain a custom made EventFactory
    For applications running outside the WebSphere environment, a custom ContentHandler can be created and associated with an EventFactory. The code sample below shows how an application can generate a ContentHandler object and use the EventFactoryFactory class to generate an EventFactory. This EventFactory object can then be bound into JNDI to make it accessible to other applications. (See Resources for more on JNDI.)

    Listing 3.

    /* Create a custom class which holds the implementation needed to populate the */
    /* Common Base Event */
    CustomContentHandler implements ContentHandler{
    	
    	public CustomContentHandler(){}
    
    	public void completeEvent() {
    
    		// Add code to populate the event with desired values
    	}
    }
    
    /* Create a new CustomerContentHandler and associate it with an EventFactory */
    ContentHandler myCustomContentHandler = new CustomContentHandler();
    EventFactory eventFactory = EventFactoryFactory.createEventFactory
    	(myCustomContentHandler);
    
    /* Bind the EventFactory object into JNDI */
    Context myContext = new InitialContext();
    myContext.bind("eventFactory/myCustomEventFactory");
    
    /* Obtain the EventFactory from JNDI to be used to generate Common Base Events */
    EventFactory = (EventFactory)javax.rmi.PortableRemoteObject.narrow
    	(initialContext.lookup("eventFactory/myCustomEventFactory"), EventFactory.class);

Create a Common Base Event

The EventFactory object provides three methods to create a CommonBaseEvent object, as shown in Listing 4:

Listing 4.
CommonBaseEvent event = eventFactory.createCommonBaseEvent();

CommonBaseEvent event = eventFactory.createCommonBaseEvent
			(java.lang.String extensionName);

CommonBaseEvent event = eventFactory.createCommonBaseEvent
			(java.lang.String extensionName, long creationTime);

Before a common base event is sent to the CEI server by the emitter, it is validated to ensure all the required fields have been set. Table 1 lists the minimum required fields for a common base event to be valid.

Table 1. The required CBE fields
Field Name Description
ExtensionName This can be set on the CBE constructor and identifies the type of event.
CreationTime The creation time can be set on the constructor for the CommonBaseEvent or set explicitly using the CBE methods setCreationTime(java.lang.String creationTimeValue), setCreationTimeAsLong(long creationTime).
SituationType Valid SituationTypes are: AvailableSituation, ConfigureSituation, ConnectSituation, CreateSituation, DependancySituation, DestroySituation, FeatureSituation, OtherSituation, ReportSituation, RequestSituation, StartSituation, StopSituation.
SourceComponentId This field identifies the ComponentIdentification type. The attributes include, for example, the component type, location, process, and thread information.
Version The CBE must have a valid version number. This is created automatically.

The SituationType listed in Table 1 is used to describe the situation in which the event is occurring. For example, a SituationType of StartSituation is used to identify an event which occurs when a component starts. The EventFactory has helper methods to create each type of situation, which is then populated with additional information before being passed into the common base event. Within each SituationType, the reasoningScope, situationQualifier, and situationDisposition can be specified. (Refer to the API documentation for a description of the valid fields.) An example of how these fields can be populated is shown in A Common Base Event Example.

The WebSphere-specific EventFactory automatically sets the CreationTime and, if one is not specified, creates a SituationType attribute of OtherSituation. In addition, the SourceComponentId is automatically created and populated with data. Therefore, the application only needs to specify these fields if an EventFactory other than the WebSphere-specific one is used. Table 2 describes the ComponentIdentification values created by the WebSphere-specific ContentHandler object.

Table 2. ComponentIdentification values created using a WebSphere ContentHandler object
ComponentIdentification field WebSphere-specific values
componentIdType Fixed value set to ProductName.
component WebSphere platform identifiers, for example: Platform 5.0 [BASE 5.0.2 ptf2O0320.06] [ND 5.0.2[ptf2O0320.06].
componentType Fixed value set to WebSphereApplicationServer.
subComponent Values can be:
  • J2EE_Application (default)
  • WebAppServer_EJB_Container
  • Workflow_Engine
locationType Fixed value set to Hostname.
location The hostname of the server or server region.
instanceId Values can be:
  • cell.node.server
  • node.server
  • server
where cell, node and server correspond to the WebSphere cell name, node name, and server name.
executionEnvironment The operating system that the WebSphere application server is running in. This information is extracted from the Java Virtual Machine (JVM).
processId The JVM identification.
threadId The thread identification from where the CBE was originally created.

Populate a Common Base Event

This section expands on the fields described in the section Create a Common Base Event and explains some of the methods that can be used to populate the common base event with data. As with most fields in the common base event, there is more than one way to add data. The attributes listed below are the most common, but refer to the API documentation for a complete list of fields and methods.

  • ContextDataElement: Used to correlate events that occur as part of the same piece or unit of work. The Java code below shows two different methods that add a ContextDataElement to an event. The name of the context defines its type with the contextId being the actual instance of that context within its type. ContextId is not required if the contextValue is specified and vice versa.

    Listing 5.

    ContextDataElement contextDataElement = eventFactory.createContextDataElement();
    contextDataElement.setContextId("1234");
    contextDataElement.setName("Order");
    contextDataElement.setType("string");

    Listing 6.

    event.addContextDataElementWithValue("string", "Order", "newOrder1");
  • CreationTime: Required field used to indicate the time the event occurred. In the WebSphere EventFactory, this is accurate to the nearest millisecond. If an application needs greater precision it should use the SequenceNumber field to indicate the sequence the events, if they occur within the same millisecond time period.
  • ElapsedTime: Optional, but must be specified if RepeatCount is used. This field defines the time that has elapsed between a situation that occurs repeatedly. The Java code below shows how the ElapsedTime can be added to an event.

    Listing 7.

    event.setElapsedTime(time); // Set time as a long
  • ExtensionName: Required field used to identify the type of event; for example, Order, Delivery, and so on. Indicates what type of ExtendedDataElements are inside the event, and can be set on the CommonBaseEvent constructor, as shown in Create a Common Base Event.
  • ExtendedDataElement: Used to store application data. ExtendedDataElements can be nested within other ExtendedDataElements to build up a tree of application information. The Java code below shows an example of how these ExtendedDataElements can be nested inside an event. The TYPE_NO_VALUE is used to indicate that OrderInformation contains the child elements OrderNo and OrderLocation.

    Listing 8.

    ExtendedDataElement extendedDataElement = 
    event.addExtendedDataElement("OrderInformation");
    extendedDataElement.addType(ExtendedDataElememt.TYPE_NO_VALUE);
    
    extendedDataElement.addChildWithIntValue("OrderNo", 30);
    extendedDataElement.addChildWithStringValue("OrderLocation", "LondonBranch");
  • GlobalInstanceId: Must have a unique value. If this field is not set then it will be automatically added when the event is sent to the Common Event Infrastructure Server.

    Listing 9.

    event.setGlobalInstanceId("uniqueValue");
  • LocalInstanceId: Unlike GlobalInstanceId, this field need not be unique. It enables users to set an ID which is meaningful to the application or user.

    Listing 10.

    event.setLocalInstanceId("value");
  • Msg: Optional field that enables an application to specify a user message.

    Listing 11.

    event.setMsg("userReadableValue");
  • Priority: Used to specify the priority by which events should be processed. If severity is set, the priority field takes precedence. Table 3 lists some Priority values; the highest possible value is 100 but any value between 0 and 100 can be used.

    Listing 12.

    event.setPriority(priority); // Set priority as a short
    Table 3. Event Priority
    Priority value (Short) Description
    100 This event must be processed first and is the highest priority available.
    90 Urgent event and should be processed as soon as possible.
    70 An important event.
    50 An average event.
    10 A low priority event.
    1 Process this event last.
  • Severity: Describes the severity of the event. If used in conjunction with priority, then the priority value takes precedence. Table 4 shows some of the severity values although any number can be used between 0 and 60.

    Table 4. Event Severity

    Severity value (Short) Description
    60 Fatal - Used to indicate that an error has occurred and remedial action is not possible.
    50 Critical - Used to indicate an error which requires immediate remedial action.
    40 Minor - Used to indicate that action is needed but the situation is not critical.
    30 Warning - Used to signal a warning to the user. The user can then decide if any action is needed.
    20 Harmless - An error has occurred but will cause no harm to the application or system.
    10 Information - Used to signal that the event is only for information and no error has occurred.
    0 Unknown
  • SequenceNumber: Can be used to indicate a sequence of events. See CreationTime for more information.
  • SourceComponentId: Created using the ComponentIdentification type, and passed to the common base event using the setSourceComponentId(ComponentIdentification value) method. Table 5 lists the ComponentIdentification fields.

    Table 5. ComponentIdentification Fields

    ComponentIdentification fields Description
    Application Identifies the application that created this event.
    Component Identifies the component; for example, the WebSphere platform used by the Application.
    ComponentType Used in conjunction with ComponentIdType and specifies the type of the component; for example, WebSphereApplicationServer.
    ComponentIdType Specifies the ComponentType; for example, ComponentIndentification.COMPONENT_ID_TYPE_PRODUCT_NAME
    ExecutionEnvironment Information about the environment; for example, the operating system and version number.
    InstanceId Defines the instance identification; for example, the WebSphere cell name.
    Location Used in conjunction with LocationType. For example, if we have a LocationType of ComponentIdentification.LOCATION_TYPE_HOSTNAME, then the Location field identifies the hostname.
    LocationType Identifies the type of the Location field.
    ProcessId The JVM process identifier.
    SubComponent The name of the sub component that generated the event; for example, the EJB or J2EE Application.
    ThreadId An identifier for the thread.
  • Situation: Required, as described in Create a Common Base Event. Table 6 describes each SituationType.

    Table 6. SituationTypes

    SituationType Description
    AvailableSituation Indicates a component's available state.
    ConfigureSituation Indicates that a component is being configured.
    ConnectSituation Indicates that a component is connecting to another component.
    CreateSituation Indicates that a component is being created.
    DependancySituation Indicates the availability of a dependent component.
    DestroySituation Indicates that a component is being destroyed.
    FeatureSituation Indicates the status of a particular feature.
    OtherSituation Other situation type.
    ReportSituation Indicates report data from a component.
    RequestSituation Indicates request data from a component.
    StartSituation Indicates a component is starting.
    StopSituation Indicates a component is stopping.
  • RepeatCount: Used in conjunction with ElapsedTime, and specifies the number of times a certain situation has been repeated.

A Common Base Event Example

This section brings together the information described above to show how a common base event can be created and sent to the CEI server. Figure 2 and the code samples below demonstrate how two events can be created when a new Web order is submitted, and how these events illustrate how specific data can be stored within a common base event. The first event records the order data, and the second event is used to identify an important customer. This example uses the WebSphere-specific EventFactory. (An example is provided at the end to show how this would look using the generic EventFactory.)

Figure 2. Order application events
Order Application Events
  1. Obtain the EventFactory from JNDI.

    Listing 13.

    EventFactory eventFactory = (EventFactory)javax.rmi.PortableRemoteObject.narrow
    	(initialContext.lookup("com/ibm/websphere/events/factory"), EventFactory.class);
  2. Create the two common base events with extension names of NewOrder and ImportantCustomer.

    Listing 14.

    CommonBaseEvent newOrderEvent = EventFactory.createCommonBaseEvent("NewOrder");
    
    CommonBaseEvent importantCustomer = EventFactory.createCommonBaseEvent
    	("ImportantCustomer");
  3. Populate each event with the required fields needed for a valid common base event. (This example uses the WebSphere-specific EventFactory, which completes the SourceComponentId automatically.) In this example, we have overridden the Situation and provided our own unique GlobalInstanceId.

    Listing 15.

    /* Set the rest of the required fields for globalInstanceId, and situation */
    OtherSituation situation = eventFactory.createOtherSituation();
    situation.setReasoningScope("EXTERNAL");
    situation.setAny("Application Event");
    
    newOrderEvent.setSituation(situation);
    importantCustomer.setSituation(situation);
    
    newOrder.setGlobalInstanceId("0348yufgfgdgvc");
    importantCustomer.setGlobalInstanceID("vgnruisw74yd");
  4. Set the business data for the new order event.

    Listing 16.

    newOrderElement.addContextDataElementWithValue("string", "OrderEJB_J2EE", 
    	"order_number1");
    
    ExtendedDataElement extendedDataElement = 
    		newOrderEvent.addExtendedDataElement("OrderInformation");
    extendedDataElement.addType(ExtendedDataElememt.TYPE_NO_VALUE);
    extendedDataElement.addChildWithIntValue("OrderNo", 1);
    extendedDataElement.addChildWithIntValue("Quantity", 1000);
    extendedDataElement.addChildWithIntValue("OrderValue", 250000);
    
    ExtendedDataElement extendedDataElement = 
    		newOrderEvent.addExtendedDataElement("CustomerInformation");
    extendedDataElement.addType(ExtendedDataElememt.TYPE_NO_VALUE);
    extendedDataElement.addChildWithStringValue("CustomerName", "Fred Bloggs");
    extendedDataElement.addChildWithStringValue("Address", "1 High Street, L1 1OH");
    extendedDataElement.addChildWithStringValue("ImportantCustomer", "Y");
    
    newOrderEvent.setPriority(70);
    importantCustomer.setPriority(90);
  5. Obtain an emitter and send the events to the CEI server.

    Listing 17.

    EmitterFactory emitterFactory = (EmitterFactory)javax.rmi.PortableRemoteObject.narrow
    	(initialContext.lookup("com/ibm/events/configuration/emitter/Default"), 
    	EmitterFactory.class);
    
    Emitter emitter = emitterFactory.getEmitter();
    
    emitter.sendEvent(newOrderEvent);
    emitter.sendEvent(importantCustomer);

The example above uses the WebSphere-specific EventFactory, which automatically completes the SourceComponentId and CreationTime. The code below shows how this information could be completed if the generic EventFactory had been used:

Listing 18.

/* Specify the CreationTime */
newOrderEvent.setCreationTime((new Date()).getTime());
importantCustomer.setCreationTime((new Date()).getTime());

/* Specify the ComponentIdentification */
ComponentIdentification componentID = eventFactory.createComponentIdenticiation();
componentID.setComponentIdType(ComponentIdentification.COMPONENT_ID_TYPE_PRODUCT_NAME);
componentID.setComponent("WebSphere 5.1");
componentID.setComponentType("WebSphereApplicationServer");
componentID.setSubComponent("OrderEJB");
componentID.setLocationType(ComponentIdentification.LOCATION_TYPE_HOSTNAME);
componentID.setLocation("Machine2");
componentID.setInstanceId("123");
componentID.setExecutionEnvironment("Windows 2000");
componentID.setProcessId("4657A3");
componentID.setThreadId("564");

/* Set the ComponentIdentification for each of the CBEs using the setSourceComponentId method */
newOrderEvent.setSourceComponentId(componentID);
importantCustomer.setSourceComponentId(ComponentID);

Conclusion

The technical preview release of the Common Event Infrastructure provides a taste of how business and system information can be captured, persisted, and distributed as Common Base Events. Although the programming API requires specific fields to be populated, the API enables users to capture data that is specific and unique to their own business requirements. This introductory article illustrated some of the important fields that can be used to describe system and business information, and described the different methods of obtaining and populating events. The production release of the Common Event Infrastructure will take these concepts to an exciting new level, enabling users to correlate and integrate information across their systems.

Resources

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=14617
ArticleTitle=IBM WebSphere Developer Technical Journal: Using the Common Base Event in the Common Event Infrastructure
publish-date=08042004