Apama Documentation : Connecting Apama Applications to External Components : Developing Custom Clients : EngineManagement API
EngineManagement API
The Apama EngineManagement API is available in the following languages: C, C++, Java and .NET.
The EngineManagement 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 MonitorScript, JMon 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 EngineClient API instead of the more basic low-level EngineManagement API. Also consider using the higher-level EventService API for clients that primarily involve sending and receiving events.
For a full reference of the EngineManagement API in the different languages, refer to the following in your Apama installation directory:
*For C, refer to the header file engine_client_c.h in the include directory.
*For C++, refer to the header file engine_client_cpp.hpp in the include directory.
*For Java, refer to the Javadoc documentation at doc\javadoc\index.html.
*For .NET, refer to the .NET documentation at doc\dotNet\index.html.
For examples of using the EngineManagement API, see the following directories of your Apama installation:
*samples\engine_client\c
*samples\engine_client\cpp
*samples\engine_client\java\EngineManagement
*samples\engine_client\dotnet\EngineManagement
About the EngineManagement API in C
There may be several reasons for wishing to integrate with the event correlator using C instead of C++ or Java, not least if greater flexibility is required with regards to which compilers you need to work with. The C standard has been mature for considerably longer than C++, so it should be possible to develop, compile and link against the C version of the EngineManagement API with a large variety of C compilers and libraries.
The C EngineManagement API comes in two "flavours": one for pure C-only compilers, and one for C++ compilers. If you need to use the C API because your C++ compiler is not ISO-compatible or is not supported by Apama, then you might find the C++ guise of the C API easier to work with. Both are available in the header file engine_client_c.h. This header file determines what kind of compiler is in use and defines its contents accordingly. The engine_client_c.h file can be found in the APAMA_HOME/include directory.
Note:  
Due to the fact that the underlying Apama libraries are built with and include C++ code, you still need to link against the standard C++ library. Failure to do this might result in your clients failing immediately upon start-up.
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, however, consists of a set of functions organized within structures. The function names are similar to the method names used within the classes. The structures are largely organized to resemble the C++ classes.
The C and C++ APIs differ slightly from the Java and .NET APIs in the way they support construction and destruction of objects. While the C and C++ APIs provide 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 and C++ APIs generally have to manually delete the objects (structure instances) created using the methods provided. The methods to create objects (structure instances) in C and C++ APIs 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 and C++ applications, any strings passed by the application to the event 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 and C++ EngineManagement APIs 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.
Note:  
The documentation below refers to an instance of a structure in the C API also as an object.
Using the EngineManagement API
Before using the API for C, C++ or .NET EngineManagement, the API must be initialized exactly once:
*The C++ API can be initialized by calling the com::apama::engine::engineInit() function.
*The C API can be initialized by calling the AP_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 AP_EngineManagement structure.
*In the C++ API, it 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 AP_ConnectToEngine().
*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 EngineManagement API, it should be shut down if using the API for C, 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 AP_EventConsumer structures.
*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 EngineManagement 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.
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.
Copyright © 2013-2016 Software AG, Darmstadt, Germany.

Product LogoContact Support   |   Community   |   Feedback