Receiving events

Plug-ins can subscribe to receive events which are delivered to certain named channels. They will receive events sent to those channels from EPL, from external senders, from connectivity chains or from other plug-ins (see Sending events). To subscribe to events, you need to subclass the EventHandler class and implement the handleEvent() virtual method. Then you need to call registerEventHandler on the CorrelatorInterface returned by getCorrelator() with an instance of your EventHandler. registerEventHandler takes ownership of the handler object.

class MyHandler: public EventHandler
{
virtual void handleEvent(const char *type, data_t &&event,
const char *channel)
{
// do something with event
}
};
MyPlugin(): base_plugin_t("MyPlugin") {
EventHandler::subscription_t handler = getCorrelator().registerEventHandler(
MyHandler::ptr_t(new MyHandler()), "channelName",
/*mode=*/MAP_MODE, /*blocking=*/true);
}

registerEventHandler() has mandatory and optional parameters:

Parameter	Description
handler	Required. The handler object which will process delivery of the events.
channel	Required. The initial channel to subscribe to.
mode	Optional. If set to STRING_MODE, then events are delivered in Apama string form. If set to MAP_MODE (default), events are delivered in map_t form (see Sending events).
blocking	If set to true, then this handler may block the thread. If set to false, the handler will never block (see Blocking behavior of plug-ins).

handleEvent() is called with the following parameters:

Parameter	Description
type	The name of the type of the event.
event	The event itself. The data_t contains a const char * if the handler was subscribed in STRING_MODE or a map_t if it was subscribed in MAP_MODE. You are given ownership of the event so you can move it for further processing without taking a copy.
channel	The channel on which this event was delivered.

registerEventHandler() returns an object of type EventHandler::subscription_t, which can be used to add channels to a subscription, remove channels from a subscription, or remove the handler entirely. You must not call either of the remove methods from inside the handler object.

EventHandler::subscription_t has the following methods:

Method	Description
void addChannel(const char *channel)	Subscribe to an additional channel.
bool removeChannel(const char *channel)	Unsubscribe from the channel, if subscribed to it. If this reduces the subscription count to 0, then it destroys the handler. Returns true if the handler was destroyed.
void removeAllChannels()	Remove all subscriptions and destroy the handler.