Step 1 is to initialize the client-side library. This must be done only once during the lifetime of the client-side code.

Next, one must connect to a remote correlator. If the method fails an EngineException would be thrown.

If the client code is to receive any events back from the event correlator it must register itself as an event receiver with the event correlator. In order to do this, the developer must create an object that inherits from EventConsumer, and implement its sendEvents method,

In this example, the developer-defined receive_consumer constructor is establishing the connection with the event correlator. The EventSupplier returned is a handle to private resources allocated by the event correlator to service this consumer. These resources handle event filtering for this connection. These must be freed by the developer, and in this example they are being freed by calling deleteEventSupplier() in the destructor for this class.

Once initialization is complete the example starts interacting with the event correlator. First it creates a MonitorScript object and defines an EPL monitor and associated event type within it,

For a description of monitors and EPL syntax, please see Getting Started with Apama EPL in Writing Apama EPL Applications.

Then the EPL code is injected into the event correlator,

Finally, the now utilized MonitorScript object must be deleted. It is important to point out that the developer is responsible for calling this operation in order to free resources.

The monitor is now active within the event correlator. To verify this, the example requests operational status from the event correlator. It then prints this out; after which it de-allocates the resources used by the EngineStatus object by calling deleteStatus.

The next step is to send some events to the event correlator. The events here have been chosen to trigger the now active listener of the monitor injected earlier. Although events can only be represented as strings, nevertheless, the string format must still be equivalent to the TestEvent event type definition as contained within the Echo monitor injected into the event correlator earlier. Otherwise, the event instances will be rejected by the event correlator. In this example, the event type TestEvent only contains a single parameter of type string.

Note that since sendEvents takes an array of Event references, the last element needs to be NULL. As before, the developer is responsible for deleting the Event objects after they have been passed to the event correlator.

If one wanted to pass in more complex events the procedure is identical. Consider the following event type definition in EPL,

This time the Event instance as passed to createEvent needs to look as in the following example,

The Echo monitor’s active listener will be triggered by each of the TestEvent events passed into the event correlator. On every match it will execute the action specified; which is to create a new TestEvent containing a string parameter equivalent to the one matched upon. Clearly this is not very useful in practice, but here it serves as a good example.

The sendEvent method of the developer-defined receive_consumer should now have been invoked twice.

Finally, some cleanup is necessary before terminating.

First, disconnect and destroy the event consumer:

then disconnect from the event correlator:

and finally clean up the client library: