New feature for addressing contexts with channels in 5.2
Apama 5.2 extends the ability to send events to named channels by providing a more powerful and general feature for using channels. In your application, each context, external receiver, correlator plug-in, or Apama client application can subscribe to one or more channels to receive the events sent on that channel. Adapter configurations can also now specify the channels on which the adapter sends events to correlators.
When a monitor instance subscribes to a channel it receives events delivered to that channel from adapters and other contexts. All monitor instances in the same context as the subscribing monitor instance receive the events delivered to the subscribed channel. Within a context, there can be subscriptions to different channels. The delivery of events from adapters, over multiple channels, to multiple contexts, is parallel from adapter to processing context, and does not impose any serial bottlenecks.
To achieve the best performance, the way in which data is organized for delivery from adapters to multiple channels must be determined. Typically, this organization matches the way you distribute the work of your application into contexts. Data sent to a particular channel should have no ordering dependency on data sent to any other channel.
The new channel features include the following enhancements and changes as well as additions to Apama Studio that support the use of channels.
EPL
The new
send...to statement sends the specified event to the specified channel. Use the
send...to statement in place of the
enqueue...to or
emit..to statement. The
enqueue...to and
emit..to statements will be removed in a future release.
The new
monitor.subscribe() and
monitor.unsubscribe() statements subscribe/unsubscribe a context to the specified channel. The monitor that contains the statement and any other monitors in the same context are subscribed/unsubscribed. Note that this is a special use of the
monitor keyword.
The new
com.apama.Channel type holds a string or a context. You can send events to
com.apama.Channel objects. If the
Channel object contains a string then the event is sent to the channel of that name. If the
Channel object contains a context then the event is sent to that context.
Correlator utilities
The
engine_send utility and
engine_receive utilities can send/receive a file that associates events with channels. For details, see "Event association with a channel" in
Deploying and Managing Apama Applications.
The
engine_connect utility has a new parallel mode (
-m parallel or
--mode parallel) that uses a connection per channel between correlators and delivers events to the target correlator on the channel the events were sent from in the source correlator. Previous behavior of
engine_connect is preserved in legacy mode (
-m legacy or
--mode legacy), which uses one connection between two correlators and delivers all events to the default channel.
All connections to the correlator are now persistent. Consequently, the engine_connect utility no longer needs to provide the --persistent option and this option has been removed.
The
engine_inspect utility now provides information about channels being used and about receivers.
When the correlator sends status to its log it now provides information for the following new status indicators:
srn — Slowest receiver name is the name of the receiver whose queue has the largest number of entries. If no receivers have queue entries then this value is
"<none>".
srq — Slowest receiver queue. For the receiver identified by
srn, the slowest receiver, this is the number of entries on its queue.
Apama client APIs
In C, C++, Java and .NET, there is a new enumeration called ConnectMode with values CONNECT_LEGACY or CONNECT_PARALLEL. This is used by new overloadings for the existing methods attachAsEventConsumerTo(), detachAsEventConsumerFrom(), attachAsConsumerOfEngine() and detachAsConsumerOfEngine().
There is now a separate connection for each EngineManagement object (EngineClientBean object, EventService object, or ScenarioService object) that you create in a client application. In previous releases, multiple EngineManagement objects shared a connection to the same Apama component.
For events that have a channel attribute set, the value of that attribute is now used when the event is sent to a correlator. In previous releases, the value of a channel attribute was ignored. For events that do not have a channel attribute set, the behavior is unchanged. That is, the event is delivered on the default channel (the empty string) to all public contexts.
The setEngineParams() method no longer accepts the LogicalID argument.
Correlator plug-in APIs
Correlator plug-ins must be rebuilt against the new header files.
When writing a correlator plug-in in C++, the following new methods are defined by
AP_CorrelatorInterface:
virtual void sendEventTo(const char* event, AP_uint64 targetContext,
AP_uint64 sourceContext)
void subscribe(const AP_EventHandlerInterface::ptr_t &handler,
std::initializer_list<const char *> channels)
template<typename ITER>
void subscribe(const AP_EventHandlerInterface::ptr_t &handler,
const ITER &start, const ITER &end)
void subscribe(const AP_EventHandlerInterface::ptr_t &handler,
const T &channel)
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler,
std::initializer_list<const char *> channels)
template<typename ITER>
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler,
const ITER &start, const ITER &end)
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler,
const T &channel)
virtual void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler)
When writing a correlator plug-in in Java, the following new methods are available on
com.apama.epl.plugin.Correlatorpublic static native void sendTo(String evt, String chan);
public static native void sendTo(String evt, Context ctx);
public static native void sendTo(String evt, Context[] ctxs);
public static native void subscribe(EventHandler handler,
String[] channels);
public static native void unsubscribe(EventHandler handler,
String[] channels);
public static native void unsubscribe(EventHandler handler);
Adapter configurations
When specifying connections to correlators, you can specify the optional
parallelConnectionLimit attribute in a
<sinks> element. Normally, you do not need to specify this attribute. The default behavior is that the IAF limits itself to an internally set number of connections with each specified sink. This number scales according to the number of CPUs that the IAF detects on the host that is running the IAF. While this number is usually sufficient, there are some situations in which you might want to change it. For example, if you are trying to conserve resources you might want to limit the number of connections to 1, or if you want to prevent multiple threads from sharing a connection you might allow a higher number of connections than the default allows.
When specifying the mapping between an Apama correlator event type and a kind of external message, you can now specify the attributes
transportChannel and/or
presetChannel to support getting and setting the channel of each normalized event that passes through the IAF adapter.
Application upgrade considerations arising from channels improvements
After you install Apama 5.2, you will need to make some modifications to your applications to take advantage of the new channel features. Before you make these modifications, consider the following:
Does your application depend on event ordering? Applications that use multiple channels might re-order events.
How many channels do you need? Which events would use which channels? What is your naming convention for channels? Typically, the way your application organizes work into contexts is a good indicator for how to use channels.
In multi-correlator deployments, can you use fewer correlators? By using channels, a correlator provides greater parallel processing, which might render some additional correlators unnecessary. Using fewer correlators reduces the complexity of your deployment and can improve performance.
To start using channels:
In EPL monitors,
subscribe to receive events delivered to particular channels. Also, use
send statements to send events to particular channels.
In correlator plug-ins, use the new methods for subscribing to receive events sent on particular channels and for sending events to particular channels. These methods are provided by:
C++:
AP_CorrelatorInterfaceJava:
com.apama.epl.plugin.CorrelatorTo upgrade multi-correlator deployments, the additional recommended steps are:
In
engine_connect command lines, specify the
-m parallel or
--mode parallel option. In parallel mode, for each specified channel, Apama will create a separate connection between the sending and target correlators.
In event files to be sent by the
engine_send utility, specify channels. For details, see "Event association with a channel" in
Deploying and Managing Apama Applications.
In the parts of your application that receive output from the
engine_receive utility, make any changes needed to accommodate the new channel specification associated with events.