Main classes

In C++ a developer needs to get an EngineManagement object by calling the function connectToEngine(const char* host, unsigned short port)

This method takes as parameters a host name and a socket port number. Together these parameters indicate the network location of an event correlator. connectToEngine then returns an EngineManagement object. Similarly, in Java one must call the static method connectToEngine(java.lang.String host, int port)of the factory class com.apama.engine.EngineManagementFactory, which returns an object that implements EngineManagement.

In both C++ and Java this object then allows a developer to:

In order to receive events from an event correlator, the client needs to create a class that, in C++, inherits from com::apama::event::EventConsumer or, in Java, implements the interface com.apama.event.EventConsumer

When this is connected to the correlator, a com::apama::event::EventSupplier object is created to act as the unique interface between the correlator and that particular EventConsumer instance. The Java equivalent is com.apama.event.EventSupplier. In C++ each EventSupplier object which is created for an EventConsumer must be individually disconnected either by calling .disconnect() on it or deleted via the deleteEventSupplier API method before deleting the corresponding EventConsumer and before disconnecting the EngineManagement object from which it was created

Events are emitted onto named channels. For an application to receive events from the correlator it must register itself as an event receiver (an EventConsumer) and subscribe to one or more channels. Then if events are emitted to thosre channels by the correlator’s monitors they will be forwarded to it.

Channels effectively allow both publish-subscribe message delivery, through which one can also achieve point-to-point. Channels can be set up to represent topics. External applications can then subscribe to event messages of the relevant topics. Otherwise a channel can be set up purely to indicate a destination and have only one application connected to it.

Note: A consumer with multiple subscriptions to the same channel will receive only a single copy of each event emitted to the subscribed channel. A consumer that subscribes to a channel without specifying a name will receive events from all channels; this behavior is the same for a subscription with no channel specified.

The developer must inherit from (or implement) EventConsumer in order to provide an implementation for its sendEvents method. This method is then called by the EventSupplier representing the correlator whenever the latter emits events that match the consumer’s channel filter.

In order to send events to the correlator, an application calls methods of the com.apama.engine.EngineManagement instance. The following methods are available:

sentEvents — This method of the com.apama.engine.EngineManagement sends the events passed to it using the calling thread. It automatically rebatches the actual event sending for efficiency. Your client application should call the flushEvents() method of of the com.apama.engine.EngineManagement class before exiting to ensure all events have been sent.

sendEventsNoBatching() — This method of the com.apama.engine.EngineManagement class sends events to the correlator without doing any batching.

flushEvents() — This method of the com.apama.engine.EngineManagement class waits for all events sent by sendEvents() to be acknowledged by the correlator. Note that this can take some time even if the correlator is responsive as acknowledgements are sent intermittently, so avoid calling this within any performance critical loops. flushEvents() is implicitly called before inject and delete requests are sent. This call is cheap if there are no outstanding events.

For C++ clients, if a client wishes to be notified when it is disconnected, it should supply a class that inherits/implements the DisconnectableEventConsumer class/interface. The disconnect() method will be called on the client’s class when the connection to the correlator is lost, with a reason explaining why.

For C clients, if a client wishes to be notified when it is disconnected, it should supply a pointer to an AP_DisconnectableEventConsumer (which contains a pointer to an AP_EventConsumer and function pointer to a disconnect method) to the connectDisconnectableEventConsumer function. The function pointed to by the disconnect function pointer will be called with an explantation of why the consumer was disconnect if the client is disconnected from the correlator.