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. In addition, reliable JMS messaging makes use of Apama's correlator persistence feature, which specifies that the correlator periodically writes its state to stable storage.
The focus here is on the most widely used reliability modes, which transparently tie JMS message sending and receiving to the correlator's persistence feature. When correlator persistence is enabled the correlator periodically writes its state to stable storage. For more complex applications, there are features to prevent message loss even when not using persistent monitors. See
Sending and receiving reliably without correlator persistence.
To enable reliable correlator-integrated messaging for JMS for an Apama project:
2. If necessary, in the Project Explorer expand the project's 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.
a. In the Run Configuration dialog, select the Components tab.
b. Select Default correlator and click Edit. The Correlator Configuration dialog appears.
c. 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.