Special considerations for event processing

This section contains the following information about event processing:

Processing Delete events

An application can support one of the following types of delete operations:

It may be tempting to implement delete event processing in a manner that is consistent with the application. For example, when an application entity is deleted, a connector poll method for an application that supports physical deletes might publish a business object with the Delete verb. A connector poll method for an application that supports logical deletes might publish a business object with the Update verb and the status value changed to inactive.

Problems can arise with this approach when a source application and a destination application support different delete models. Suppose that the source application supports logical delete and the destination application supports physical delete. Assume that an enterprise is synchronizing between the source and destination applications. If the source connector sends a change in status (in other words, a delete event) as a business object with the Update verb, the destination connector might be unable to determine that the business object actually represents a delete event.

Therefore, event publishing must be designed so that source connectors for both types of applications can publish delete events in such a way that destination connectors can handle the events appropriately. The Delete verb in an event notification business object should represent an event where data was deleted, whether the delete operation was a physical or logical delete. This ensures that destination connectors will be correctly informed about a delete event.

This section provides the following information on how to implement event processing for delete events:

Setting the verb in the event record

The event detection mechanism for both logical and physical delete connectors should set the verb in the event record to Delete:

Setting the verb in the business object

The poll method for both logical and physical delete connectors should generate a business object with the Delete verb:

Setting the verb during mapping

WebSphere InterChange Server

Mapping between the application-specific business object and the generic business object should map the verb as Delete. This ensures that the correct information about an event is sent to the collaboration, which may perform special processing based on the verb.

Follow these recommendations for relationship tables:

Using guaranteed event delivery

The guaranteed-event-delivery feature enables the connector framework to guarantee that events are never sent twice between the connector's event store and the integration broker.

Important:
This feature is available only for JMS-enabled connectors; that is, those connectors that use Java Messaging Service (JMS) to handle queues for their message transport. A JMS-enabled connector always has its DeliveryTransport connector property set to JMS. When the connector starts, it uses the JMS transport; all subsequent communication between the connector and the integration broker occurs through this transport. The JMS transport ensures that the messages are eventually delivered to their destination.

Without use of the guaranteed-event-delivery feature, a small window of possible failure exists between the time that the connector publishes an event (when the connector calls the gotApplEvent() method within its pollForEvents() method) and the time it updates the event store by deleting the event record (or perhaps updating it with an "event posted" status). If a failure occurs in this window, the event has been sent but its event record remains in the event store with a "ready for poll" status. When the connector restarts, it finds this event record still in the event store and sends it, resulting in the event being sent twice.

You can provide the guaranteed-event-delivery feature to a JMS-enabled connector in one of the following ways:

Guaranteed event delivery for connectors with JMS event stores

If the JMS-enabled connector uses JMS queues to implement its event store, the connector framework can act as a "container" and manage the JMS event store (the JMS source queue). One of the roles of JMS is to ensure that once a transactional queue session starts, the messages are cached there until a commit is issued; if a failure occurs or a rollback is issued, the messages are discarded. Therefore, in a single JMS transaction, the connector framework can remove a message from a source queue and place it on the destination queue. This container-managed-events feature of guaranteed event delivery enables the connector framework to guarantee that events are never sent twice between the JMS event store and the destination's JMS queue.

This section provides the following information about use of the guaranteed-event-delivery feature for a JMS-enabled connector that has a JMS event store:

Enabling the feature for connectors with JMS event stores

To enable the guaranteed-event-delivery feature for a JMS-enabled connector that has a JMS event store, set the connector configuration properties shown in Table 50..

Table 50. Guaranteed-event-delivery connector properties for a connector with a JMS event store

Connector property Value
DeliveryTransport
JMS
ContainerManagedEvents
JMS
PollQuantity
The number of events to processing in a single poll of the event store
SourceQueue

Name of the JMS source queue (event store) which the connector framework polls and from which it retrieves events for processing

Note:
The source queue and other JMS queues should be part of the same queue manager. If the connector's application generates events that are stored in a different queue manager, you must define a remote queue definition on the remote queue manager. WebSphere MQ can then transfer the events from the remote queue to the queue manager that the JMS-enabled connector uses for transmission to the integration broker. For information on how to configure a remote queue definition, see your IBM WebSphere MQ documentation.
Note:
A connector can use only one of these guaranteed-event-delivery features: container managed events or duplicate event elimination.Therefore, you cannot set the ContainerManagedEvents property to JMS and the DuplicateEventElimination property to true.

In addition to configuring the connector, you must also configure the data handler that converts between the event in the JMS store and a business object. This data-handler information consists of the connector configuration properties that Table 51 summarizes.

Table 51. Data-handler properties for guaranteed event delivery

Data-handler property Value Required?
MimeType
The MIME type that the data handler handles. This MIME type identifies which data handler to call. Yes
DHClass
The full name of the Java class that implements the data handler Yes
DataHandlerConfigMOName
The name of the top-level meta-object that associates MIME types and their data handlers Optional
Note:
The data-handler configuration properties reside in the connector configuration file with the other connector configuration properties.

End users that configure a connector that has a JMS event store to use guaranteed event delivery must be instructed to set the connector properties as described in Table 50 and Table 51.. To set these connector configuration properties, use the Connector Configurator tool. Connector Configurator displays the connector properties in Table 50 on its Standard Properties tab. It displays the connector properties in Table 51 on its Data Handler tab.

Note:
Connector Configurator activates the fields on its Data Handler tab only when the DeliveryTransport connector configuration property is set to JMS and ContainerManagedEvents is set to JMS.

For information on Connector Configurator, see Appendix B, Connector Configurator.Appendix B, "Connector Configurator," on page 527.

Effect on event polling

If a connector uses guaranteed event delivery by setting ContainedManagedEvents to JMS, it behaves slightly differently from a connector that does not use this feature. To provide container-managed events, the connector framework takes the following steps to poll the event store:

  1. Start a JMS transaction.
  2. Read a JMS message from the event store.

    The event store is implemented as a JMS source queue. The JMS message contains an event record. The name of the JMS source queue is obtained from the SourceQueue connector configuration property.

  3. Call the appropriate data handler to convert the event to a business object.

    The connector framework calls the data handler that has been configured with the properties in Table 51..

  4. When a WebSphere message broker (WebSphere MQ Integrator, WebSphere MQ Integrator Broker, WebSphere Business Integration Message Broker) or WebSphere Application Server is the integration broker, convert the business object to a message based on the configured wire format (XML).
  5. Send the resulting message to the JMS destination queue.
    WebSphere InterChange Server

    The message sent to the JMS destination queue is the business object.

    Other integration brokers

    The message sent to the JMS destination queue is an XML message.

  6. Commit the JMS transaction.

    When the JMS transaction commits, the message is written to the JMS destination queue and removed from the JMS source queue in the same transaction.

  7. Repeat step 1 through 6 in a loop. The PollQuantity connector property determines the number of repetitions in this loop.
Important:
A connector that sets the ContainerManagedEvents property is set to JMS does not call the pollForEvents() method to perform event polling. If the connector's base class includes a pollForEvents() method, this method is not invoked.

Guaranteed event delivery for connectors with non-JMS event stores

The connector framework can use duplicate event elimination to ensure that duplicate events do not occur. This feature is usually enabled for JMS-enabled connectors that use a non-JMS solution to implement an event store (such as a JDBC event table, Email mailbox, or flat files). This duplicate-event-elimination feature of guaranteed event delivery enables the connector framework to guarantee that events are never sent twice between the event store and the destination's JMS queue.

Note:
JMS-enabled connectors that use a JMS event store usually use the container-managed-events feature. However, they can use duplicate event elimination instead of container managed events.

This section provides the following information about use of the guaranteed-event-delivery feature with a JMS-enabled connector that has a non-JMS event store:

Enabling the feature for connectors with non-JMS event stores

To enable the guaranteed-event-delivery feature for a JMS-enabled connector that has a non-JMS event store, you must set the connector configuration properties shown in Table 52..

Table 52. Guaranteed-event-delivery connector properties for a connector with a non-JMS event store

Connector property Value
DeliveryTransport
JMS
DuplicateEventElimination
true
MonitorQueue

Name of the JMS monitor queue, in which the connector framework stores the ObjectEventId of processed business objects

Note:
A connector can use only one of these guaranteed-event-delivery features: container managed events or duplicate event elimination.Therefore, you cannot set the DuplicateEventElimination property to true and the ContainerManagedEvents property to JMS.

End users that configure a connector to use guaranteed event delivery must be instructed to set the connector properties as described in Table 52.. To set these connector configuration properties, use the Connector Configurator tool. It displays these connector properties on its Standard Properties tab. For information on Connector Configurator, see Appendix B, Connector Configurator.Appendix B, "Connector Configurator," on page 527.

Effect on event polling

If a connector uses guaranteed event delivery by setting DuplicateEventElimination to true, it behaves slightly differently from a connector that does not use this feature. To provide the duplicate event elimination, the connector framework uses a JMS monitor queue to track a business object. The name of the JMS monitor queue is obtained from the MonitorQueue connector configuration property.

After the connector framework receives the business object from the application-specific component (through a call to gotApplEvent() in the pollForEvents() method), it must determine if the current business object (received from gotApplEvents()) represents a duplicate event. To make this determination, the connector framework retrieves the business object from the JMS monitor queue and compares its ObjectEventId with the ObjectEventId of the current business object:

For a JMS-enabled connector to support duplicate event elimination, you must make sure that the connector's pollForEvents() method includes the following steps:

Copyright IBM Corp. 1997, 2003