It is possible to give an EPL application control over the rate at which events are taken from the JMS queue or topic by each JMS receiver. To enable this option, set the receiverFlowControl property to true in the JmsReceiverSettings bean. The configuration for this bean is found in the jms-global-spring.xml file. To display the file in Apama Studio, select the Advanced tab of the Correlator-JMS configuration editor.

Once receiverFlowControl has been enabled, use the com.apama.correlator.jms.JMSReceiverFlowControlMarker event to enable receiving events from each receiver, by specifying a non-zero window size. For example, to ensure that each receiver will never add more than 5000 events to the input queue of each public context, add the following EPL code

A flow control marker is an opaque event object that is always enqueued (to the correlator's public contexts) when a new receiver is first added and during recovery of a persistent correlator. The message is also enqueued regularly as new messages are received and mapped, which typically happens at the end of each received batch, for example, at least once every 1000 successfully-mapped events if the default setting for maxBatchSize is used. The marker event indicates a specific point in the sequence of events sent from each receiver, and the application must always respond by calling the updateFlowControlWindow action on this marker event. This sets the size of the window of new events the receiver is allowed to take from the JMS queue or topic, relative to the point indicated by the marker.

More advanced applications that need to block JMS receivers until asynchronous application-specific operations arising from the processing of received messages (such as database writes, messaging sending, etc.) have completed can factor the number of pending operations into the flow control window. To reliably do this, it is necessary to stash the marker events for each receiver in a dictionary and add logic to call updateFlowControlWindow when the number of pending operations falls, so that any receivers that were blocked due to those operations can resume receiving. It is the application's responsibility to ensure that receivers do not remain permanently blocked, by calling updateFlowControlWindow sufficiently often. For an example of how receiver flow control can be used together with asynchronous per-event operations, see the Correlator-JMS 'flow-control' sample application located in the apama_dir\samples\correlator_jms directory.

Applications must make sure that they listen for all JMSReceiverFlowControlMarker events, and that their listener for the flow control markers is set up before JMS.onApplicationInitialized is called. Any stale or invalid JMSReceiverFlowControlMarker event, for example, from before a persistent correlator was restarted, cannot be used to update the flow control window, and any calls on such stale events will simply be ignored.

Full ApamaDoc documentation for the JMSReceiverFlowControlMarker event is available together with the rest of the Correlator-JMS event API. See the ApamaDoc documentation.

The current window size for all receivers is indicated by the rWindow item in the "JMS Status" lines that are periodically logged by the Correlator, and this may be a useful debugging aid if receivers appear to be blocked indefinitely.