Getting started with reliable correlator-integrated messaging for JMS

This section describes the steps for creating an Apama application that uses reliable correlator-integrated messaging for JMS in an environment where guaranteed delivery is required. In order to enable reliable JMS messaging, you set specific JMS connection properties.

Note: Correlator persistence is deprecated and will be removed in a future release.

This topic focuses on reliability modes which transparently tie JMS message sending and receiving to the correlator’s persistence feature, which is deprecated. When correlator persistence is enabled, the correlator periodically writes its state to stable storage. There are also features to prevent message loss when not using persistent monitors. See Sending and receiving reliably without correlator persistence.

The steps described in this section build on the example created in Getting started with simple correlator-integrated messaging for JMS.

Note:

If a license file cannot be found, the correlator is limited to BEST_EFFORT only messaging. See Running Apama without a license file.

To enable reliable correlator-integrated messaging for JMS for an Apama project

  1. If necessary, create an Apama project that uses correlator-integrated messaging for JMS as described in Getting started with simple correlator-integrated messaging for JMS.

  2. If necessary, in the Project Explorer expand the project’s Connectivity and Adapters node, expand the correlator-integrated messaging for JMS adapter node, and double-click the adapter instance. This opens the instance’s configuration in the adapter editor.

  3. In the adapter editor, display the Settings tab and in the JMS Connection section, select the JMS connection to use.

  4. Click the Properties section to expand it.

  5. In the Properties section, select EXACTLY_ONCE or AT_LEAST_ONCE for Default receiver reliability. Select EXACTLY_ONCE or AT_LEAST_ONCE for Default sender reliability. Each of these reliability modes prevents message loss. AT_LEAST_ONCE is simpler and offers greater performance. EXACTLY_ONCE adds detection and elimination of duplicate messages (if configured correctly), which may be required for some applications.

  6. If receiving with EXACTLY_ONCE reliability, it is necessary to configure additional mapping rules to specify an application-level unique identifier for each received message that will function as the key for detecting functionally duplicate messages. To add these mapping rules, display the Event Mappings tab and in the source event tree, map the uniqueMessageId and (optionally, but recommended) messageSourceId entities to appropriate values in the JMS message. For example, they could be mapped to JMS message properties called UNIQUE_MESSAGE_ID and MESSAGE_SOURCE_ID (or to nodes within an XML document in the message body). When sending JMS messages, the mapping rules provide a way to expose the uniqueMessageId and messageSourceId that Apama automatically generates for sending messages to whatever JMS client will be receiving them, so that it can perform duplicate detection.

  7. In your application’s EPL code, add the persistent keyword before the monitor declarations for monitors listening for Apama events associated with JMS messages.

  8. In the project’s Run Configuration, enable correlator persistence as follows.

    1. In the Run Configuration dialog, select the Components tab.

    2. Select the default correlator and click Edit. The Correlator Configuration dialog appears.

    3. In the Correlator Configuration dialog, select the Persistence Options tab, select Enable correlator persistence, and click OK.

    Running a correlator in this way causes the it to periodically write its state to stable storage.

    For more information on correlator persistence, see Using correlator persistence.