Receiver flow control

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 Plugin for Eclipse, select the Advanced tab in the adapter 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:

using com.apama.correlator.jms.JMSReceiverFlowControlMarker;
...
on all JMSReceiverFlowControlMarker() as flowControlMarker
{
    flowControlMarker.updateFlowControlWindow(5000);
}

A flow control marker is an opaque event object that is always sent to the correlator’s public contexts when a new receiver is first added and during recovery of a persistent correlator. The message is also sent 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 and messaging sending) 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 flow-control sample application in APAMA_HOME\samples\correlator_jms.

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.

Documentation in ApamaDoc format is available for the com.apama.correlator.jms.JMSReceiverFlowControlMarker event along with documentation for the rest of the API for correlator-integrated messaging for JMS. See API reference for EPL (ApamaDoc).

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.