Engine Management API

Apama 10.15.1 | Connecting Apama Applications to External Components | Developing Custom Clients | Engine Management API

The Apama Engine Management API is available in the following languages: C++, Java and .NET.

The Engine Management API provides capabilities to interact with an Apama engine, typically a correlator. It provides the ability to send and receive events, inject and delete EPL entities (such as EPL and CDP files), connect Apama engines together, inspect what was injected into the correlator and monitor the status of the correlator.

Note:

We recommend that where possible Java and .NET developers should use the Engine Client API instead of the more basic low-level Engine Management API. Also consider using the higher-level Event Service API for clients that primarily involve sending and receiving events.

For a full reference of the Engine Management API in the different languages, refer to the following in your Apama installation directory:

For C++, refer to the header file engine_client_cpp.hpp in the include directory.

For Java, refer to the API Reference for Java (Javadoc).

For .NET, refer to the API Reference for .NET.

For examples of using the Engine Management API, see the following directories of your Apama installation:

samples\engine_client\cpp

samples\engine_client\java\EngineManagement

samples\engine_client\dotnet\EngineManagement

Differences between the different API languages

The APIs for C++, Java and .NET are packaged through a set of classes that model a set of entities.

The C++ API differs slightly from the Java and .NET APIs in the way it supports construction and destruction of objects. While the C++ API provides a set of static library methods that must be called to create and delete objects of the main classes, the Java and .NET APIs either provide factory classes or else have no restrictions on directly constructing objects. The C++ API generally has to manually delete the objects (structure instances) created using the methods provided. The methods to create objects (structure instances) in the C++ API generally have the term create in their names, and methods to delete objects (structure instances) have the term delete in their names.

Note:

In C++ applications, any strings passed by the application to the correlator need to be encoded as UTF-8 (or as pure 7-bit ASCII, which is a subset of UTF-8). If the application environment is something other than UTF-8, you have to use the methods provided by the C++ Engine Management API for the conversion to/from UTF-8 encoding. The methods for UTF-8 conversion generally have the term UTF8 in their names.

The APIs for Java and .NET are almost identical except for the naming/capitalization of classes, methods and packages.

Using the Engine Management API

Before using the API for C++ or .NET Engine Management, the API must be initialized exactly once:

The C++ API can be initialized by calling the com::apama::engine::engineInit() function.

The .NET API can be initialized by calling the Apama.Engine.Api.EngineInit() method.

The Java API does not need to be initialized before using it.

The key object of the API is the EngineManagement object. The EngineManagement object connects to the engine and allows clients to interact with it. In each language, the API provides a mechanism to create an EngineManagement object:

In the C++ API, the EngineManagement object is an instance of the com::apama::engine::EngineManagement class.

In the Java API, it is an instance of the com.apama.engine.EngineManagement interface.

In the .NET API, it is an instance of the Apama.Engine.EngineManagement interface.

The following method needs to be called to get an EngineManagement object:

For the C++ client, you have to call com::apama::engine::connectToEngine().

For the Java client, you have to call the static connectToEngine() method of the com.apama.engine.EngineManagementFactory class.

For the .NET client, you have to call the static ConnectToEngine() method of the Apama.Engine.Api class.

Once the EngineManagement object is created, it can be used to send/receive events, inject/delete EPL entities, monitor and inspect engines, and connect two engines together.

If an EngineManagement object is no longer needed, it should be disconnected. The methods for disconnecting generally have the term disconnect in their names.

Once done with the Engine Management API, it should be shut down if using the API for C++ or .NET. The API for Java does not need to be shut down. The methods for shutting down the API generally have the term shutdown, close or dispose in their names.

Sending events

Clients wishing to use the EngineManagement object to send events into the engine should use various methods provided by it. The methods to send events generally have the term send in their names. The send methods/functions require an event object as input.

Receiving events

Clients wishing to use the EngineManagement object to receive events should do so by adding one or more consumers with channels from which it wants to receive events. A consumer with multiple subscriptions to the same channel will receive only a single copy of each event emitted to the subscribed channel. The methods to add consumers generally have the term consumer in their names.

In the C++ API, consumers are instances of the com::apama::event::EventConsumer class.

In the Java API, consumers are instances of the com.apama.event.EventConsumer interface.

In the .NET API, consumers are instances of the Apama.Event.EventConsumer class.

The methods/functions to add consumers return an EventSupplier object which acts as the unique interface between the correlator and that particular EventConsumer instance. The supplier should be disconnected and disposed before the consumer is disconnect and disposed.

If a consumer needs to be notified when it is disconnected, DisconnectableEventConsumer should be used when adding a consumer. The disconnect() method of the consumer will be called when the connection to the engine is lost.

Note:

If you need more advanced send/receive functionality, you should also consider using the higher-level EventService API (for Java and .NET) rather than the Engine Management API.

Injecting and deleting EPL

The EngineManagement object provides the capability to gather information from a remote correlator about the set of monitors and event types that it is currently working with. This information can be retrieved by calling inspectEngine() or a similar method on the EngineManagement object.

The inspectEngine method/function returns the EngineInfo object which encapsulates various information about the engine such as the number of monitors, the number of event types, or the number of contexts.

Status monitoring

The EngineManagement object provides the capability to get status information from the engine. The status information can be retrieved by calling getStatus() or a similar method on the EngineManagement object.

The getStatus() function returns an EngineStatus object which encapsulates various status information about the engine such as uptime, the number of consumers, or input and output queue sizes. For more information, see List of correlator status statistics.

Connecting correlators

The EngineManagement object provides the capability to connect one engine to another engine so that it receives events emitted on the specified channels. The methods to attach/detach two engines generally have the term attach or detach in their names.