Enabling Guaranteed event delivery

You can configure the Guaranteed event delivery feature for 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). In a single JMS transaction, the connector can remove a message from a source queue and place it on the destination 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 to values shown in Table 5..

Table 5. 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.

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 information consists of the connector configuration properties that Table 6 summarizes.

Table 6. 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.

If you configure a connector that has a JMS event store to use Guaranteed event delivery, you must set the connector properties as described in Table 5 and Table 6. To set these connector configuration properties, use the Connector Configurator tool. Connector Configurator displays the connector properties in Table 5 on its Standard Properties tab. It displays the connector properties in Table 6 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.

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 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 6.

  4. When WebSphere MQ Integrator Broker 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.
    If you are using the WebSphere ICS integration broker, the message sent to the JMS destination queue is the business object. If you are using WebSphere MQ Integrator broker, the message sent to the JMS destination queue is an XML message (which the data handler generated).
  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

If the JMS-enabled connector uses a non-JMS solution to implement its event store (such as a JDBC event table, Email mailbox, or flat files), the connector framework can use duplicate event elimination to ensure that duplicate events do not occur. 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 to values shown in Table 7.

Table 7. 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

If you configure a connector to use Guaranteed event delivery, you must set the connector properties as described in Table 7. 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.

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 Corporation 2003, 2005. All Rights Reserved.