Subscribing to channels

Adapters and clients can specify the channel to deliver events to. In EPL, you can send an event to a specified channel. To obtain the events delivered to particular channels, monitor instances and external receivers can subscribe to those channels.

In a monitor instance, to receive events sent to a particular channel, call the subscribe() method on the monitor pseudo-type by using the following format:

Replace channel_name with a string expression that indicates the name of the channel you want to subscribe to. You cannot specify a com.apama.Channel object that contains a string.

Call the subscribe() method from inside an action. Any monitor instance in any context can call monitor.subscribe().

The subscribe() method subscribes the calling context to the specified channel. When a context is subscribed to a channel events delivered to that channel are processed by the context, and can match against any listeners in that context. This includes listeners from monitor instances other than the instance that called subscribe(). However, the subscription is owned by the monitor instance that called monitor.subscribe(). If that monitor instance terminates, then any subscriptions it owned also terminate.

A subscription ends when the monitor instance that subscribed to the channel terminates or executes monitor.unsubscribe.

Whether an event is coming into the correlator or is generated inside the correlator, it is delivered to everything that is subscribed to the channel. If the target channel has no subscriptions from monitor instances nor external receivers then the event is discarded.

monitor pairtrade
{
action onload()
{
on all PairTrade() as pt {
spawn start_trade(pt.left, pt.right) to context(pt.toString());
}
}

action start_trade(string sym1, string sym2)
{
monitor.subscribe("ticks-"+sym1);
monitor.subscribe("ticks-"+sym2);
// Next, set up listeners for sym1 and sym2.
. . .
}
}

This code spawns a monitor for each trade pair. The spawned monitor subscribes to just the ticks for the symbols passed to it. If a symbol in one pair is slow to process, any unrelated pairs of symbols are unaffected. See Event association with a channel.

In a context, any number of monitor instances can subscribe to the same channel. When multiple monitors in a context require data from a channel the recommendation is for each monitor to subscribe to that channel. This ensures that the termination of one monitor does not affect the events received by other monitors. Subscriptions are reference counted. The result of multiple subscriptions to the same channel from the same context is that each event is delivered once as long as any of the subscriptions are active. An event is not delivered once for each subscription.

Suppose that in one monitor instance you unsubscribe from a channel but another monitor instance in the same context is subscribed to that channel. In the monitor instance that unsubscribed, be sure to terminate any listeners for the events from the unsubscribed channel. Events from the unsubscribed channel continue to come in because of the subscription from the other monitor instance.

To explicitly terminate a subscription, call monitor.unsubscribe(channel_name). In a given context, if you terminate the last subscription to a particular channel then the context no longer receives events from that channel. If events from the previously subscribed channel were delivered but not yet processed (they are waiting on the input queue) those events will be processed. This could include the processing of any listener matches. It is an error to unsubscribe from a channel that the calling monitor instance does not have a subscription to, and this will throw an exception.

If a monitor is going to terminate anyway there is neither requirement nor advantage to calling unsubscribe(). Calling unsubscribe() can be useful when a monitor listens to configuration data during startup but does not need to listen to it during normal processing.

The subscribe() and unsubscribe() methods are static methods on the monitor type. However, it is not possible to use instances of the monitor type. For example, there cannot be variables or event members of type monitor.