New correlator-integrated messaging for JMS features
In Apama 5.0, the correlator-integrated messaging for JMS feature has been enhanced as follows:
In addition to specifying static senders and receivers in the adapter's configuration file, Apama has a new event API that allows senders and receivers to be added and removed dynamically from EPL code. This provides the ability to receive from a topic or queue, the name of which is known only at runtime. For advanced users, it provides a way to allow an application to implement dynamic scaling of the number of sender and receiver threads in order to improve performance, based on any policy specific to the application's use case.
JMS durable topic subscriptions are supported for dynamic and static receivers. This enables an Apama application to persistently register interest in a topic's messages with the JMS broker such that even if a correlator is down, messages sent to the queue will be held and be ready for delivery when the correlator recovers.
Status notification events (such as
OK,
CONNECTING,
ERROR,
FATAL_ERROR, and
REMOVED) are now sent for each JMS connection, receiver, and sender.
The
maxExtraMappingThreads property has been added to
ReceiverSettings. This supports scaling receive-side mapping work (especially expensive XML parsing) across multiple cores without needing to add extra JMS receivers, which often adds a considerable extra burden, and breaks message ordering). By default it is set to 0 (that is, do mapping on the same thread as receiving). While this property should be used with extreme care, it provides a very useful tool for cases where performance needs to be improved.
Receive message mapping conditional expression improvements:
The
jms.body.type conditional expression has been added. This provides for discriminating between TextMessage, MapMessage, etc
Added support for
empty JUEL keyword, and checking the values of properties and headers that might not have been set.
Periodic "JMS Status:" INFO log messages, similar to the existing correlator status log messages, are now logged for correlators with correlator-integrated messaging for JMS enabled. The JMS Status messages include diagnostic info such as number of outstanding sent events, totals send/received, used JVM memory, etc.
A new receiver/sender settings property called
logPerformanceBreakdown can be enabled to provide detailed information highlighting where performance bottlenecks may be occurring.
The
JMSSender.getOutstandingEvents action has been added to the event API. This can be useful for throttling the rate at which messages are emitted from an EPL application in order to avoid the JMS sender getting too far behind (and using up excessive memory as a result).
A new
receiverFlowControl property has been added to provide EPL applications with control over the rate at which events are taken from the JMS queue or topic by each JMS receiver.
Many limitations on convention-based mapping have been removed. For example
Element names containing hyphens and dots can be represented using
$002d and
$002e, respectively.
Mapping both text and attribute/child node data from the same XML node is supported.
Mapping attribute values to EPL
integer,
float, and
boolean fields is supported.
Apama provides new sample applications that illustrate the use of correlator-integrated messaging for JMS. The
apama_dir\samples\correlator_jms directory contains the following sample applications:
simple-send-receive - This application demonstrates simple sending and receiving. It sends a sample event to a JMS queue or topic as a JMS TextMessage using the automatically configured default sender and receives the message using a statically-configured receiver.
dynamic-event-api - This application demonstrates how to use the event API to dynamically add and remove JMS senders and receivers. In addition, it shows how to monitor senders and receivers for errors and availability.
flow-control - This application demonstrates how to use the event API to avoid sending events faster than JMS can cope with and a separate demonstration of how to avoid receiving messages from JMS faster than the EPL application can cope with.
For information on these features, see
Using Correlator-Integrated Messaging for JMS and the ApamaDoc, which is available at
apama_install_doc\doc\ApamaDoc\index.htmlMIGRATION NOTES
If you are migrating an application from Apama 4.3 then the following changes to correlator-integrated messaging for JMS may require changes to your application.
It is possible in some cases that customers may have created a configuration in which senders or receivers share the same receiver or sender id. As of Apama 5.0, this is no longer allowed, so any such ids should be renamed.
The recommended
jms-global-spring.xml file now uses bean classes
com.apama.correlator.jms.config.JmsReceiverSettings and
com.apama.correlator.jms.config.SenderSettings instead of
com.progress.adapters.config.jms.JmsReceiverSettings and
com.progress.adapters.config.jms.JmsSenderSettings. Apama recommends that customers manually edit the
jms-global-spring.xml file and change the bean classes in order to benefit from new features.
Various JMS status events are now enqueued to the correlator by the JMS runtime, which may result in '
Failed to parse the event' WARN messages. Applications and deployment scripts that use correlator-integrated messaging for JMS should be updated to inject
CorrelatorJMSEvents.mon. Applications developed within Apama Studio will automatically have this file accessible to them.
The format of the
uniqueMessageId that is generated by correlator-integrated messaging has changed since 4.3.4.0 (if not overridden explicitly with a user-supplied identifier). This means there is a slight chance that messages sent by 4.3.4.0 and redelivered after recovery in a 5.0 correlator might not be duplicate detected correctly by the downstream system. If this rare condition is a concern, ensure your application pauses emitting messages to JMS before beginning the upgrade.
Direct use of the JMSPlugin in EPL code is now deprecated. Use the
com.apama.correlator.jms.JMS event type instead.