A J2EE event consumer is implemented as a message-driven bean,
which is associated with a JMS destination and connection factory at deployment
time. To receive events, follow these steps:
Steps for this task
- Obtain a notification helper. A JMS event consumer uses
a notification helper to identify JMS destinations associated with an event
group, to convert received JMS messages into event notifications, and to perform
filtering of received events. To obtain a notification helper, use a notification
helper factory, which is an instance of NotificationHelperFactory that has
been bound into a JNDI namespace. The following code fragment
uses a notification helper factory to obtain a notification helper.
// Get notification helper factory from JNDI
InitialContext context = new InitialContext();
Object notificationHelperFactoryObject =
context.lookup("com/ibm/events/NotificationHelperFactory");
NotificationHelperFactory nhFactory = (NotificationHelperFactory)
PortableRemoteObject.narrow(notificationHelperFactoryObject,
NotificationHelperFactory.class);
// Create notification helper
NotificationHelper notificationHelper =
nhFactory.getNotificationHelper();
- Optional: Specify the event selector. If
you want to filter received events, you can use the setEventSelector() method
to set an event selector on the notification helper. Your event consumer can
then use the notification helper to check received events against the event
selector. The following code fragment sets an event selector
specifying events with severity greater than 30 (warning).
notificationHelper.setEventSelector("CommonBaseEvent[@severity > 30]");
- Convert received messages into event notifications.
In
the onMessage() method of your listener, use the notification helper to convert
each received JMS message into an array containing an event notification.
(If the event does not match the event selector specified on the Notification
Helper, the array is empty.) An event notification is an instance of a class
implementing the EventNotification interface.
public void onMessage(Message msg) {
EventNotification[] notifications =
notificationHelper.getEventNotifications(msg);
// ...
- Check the notification type and retrieve the event data as appropriate. Each event notification has a field representing the notification type
(an integer whose value is one of the notification type constants defined
by the NotificationHelper interface). Three notification types are currently
supported:
Notification type |
Description |
CREATE_EVENT
_NOTIFICATION_TYPE
|
A new event has been created in the event group associated
with the destination. This means either that a new event has been sent, or
that an existing event has changed so that it now matches the event group
definition. The notification also contains the complete event data. |
REMOVE_EVENT
_NOTIFICATION_TYPE
|
An event stored in the event database has been removed
from the event group associated with the destination. This means either that
an event has been deleted from the event database, or that an existing event
has changed so that it no longer matches the event group definition. The notification
also contains the global instance identifier of the deleted event. |
UPDATE_EVENT
_NOTIFICATION_TYPE
|
An event stored in the event database has been updated
in a way that does not change its membership in the event group associated
with the destination. The notification also contains the complete event data. |
Use the getNotificationType() method of EventNotification to check
the notification type of each received notification. Based on the notification
type, you can determine whether your event consumer should process the notification
further, and what kind of event data the notification contains:
- If the notification type is CREATE_EVENT_NOTIFICATION_TYPE or UPDATE_EVENT_NOTIFICATION_TYPE,
your consumer can use EventNotification.getEvent() to attempt to retrieve
the new or updated event. This method is valid only for notifications of new
or updated events.
- If the notification is REMOVE_EVENT_NOTIFICATION_TYPE, your consumer can
use EventNotification.getGlobalInstanceId() to retrieve the global instance
identifier of the deleted event. This method is valid only for notifications
of deleted events.
for (int i = 0; i < notifications.length; i++)
{
int notifType = notifications[i].getNotificationType();
if(notifType == NotificationHelper.CREATE_EVENT_NOTIFICATION_TYPE)
{
CommonBaseEvent event = notifications[i].getEvent();
if (event != null) {
// process the new event
// ...
}
}
else if(notifType == NotificationHelper.UPDATE_EVENT_NOTIFICATION_TYPE)
{
CommonBaseEvent event = notifications[i].getEvent();
if (event != null) {
// process the updated event
// ...
}
}
else if(notifType == NotificationHelper.REMOVE_EVENT_NOTIFICATION_TYPE)
{
String eventId = notifications.[i].getGlobalInstanceId();
// process the event deletion
// ...
}
}
What to do next
In its deployment descriptor, a message-driven bean must be associated
with a listener port, which specifies a JMS destination and connection factory.
You must create a listener port for your event consumer before deploying the
MDB, specifying the destination and connection factory associated with the
event group from which you want to receive events (these are defined in the
event group profile).
Note: Do not use the CommonEventInfrastructure_ListenerPort
listener port when deploying your MDB. This listener port is used by the event
server and is not intended for use by event consumers.