The Apama Engine Client API is available in the following languages: Java and .NET.

The Engine Client 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, JMon and CDP files), connect Apama engines together, inspect what was injected into the correlator and monitor the status of the correlator.

For a full reference of the Engine Client API in the different languages, refer to the following:

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

An EngineClient instance can be acquired by calling the createEngineClient method of the EngineClientFactory class. The factory class is the following:

The host and port of the target engine can be provided when creating the EngineClient instance or later using the setHost(string) and setPort(int) methods.

Once the EngineClient instance has been configured as needed, a connection can be established either synchronously using connectNow() (which throws an exception on error) or asynchronously using connectInBackground() (which automatically retries until a connection is established; see setConnectionPollingInterval(int) and setReconnectPeriod(long)). Changes to the values of the host or port will cause the bean to attempt to re-connect to the correlator running on the new host/port.

Once the client connected successfully, a background thread will keep pinging it to ensure that the connection is still up (see the setConnectionPollingInterval(int) method for Java and the ConnectionPollingInterval property for .NET). If the entire client connection is lost, the following properties will change to false to notify the user of the EngineCient:

The client will continue to try to reconnect in the background, with the retry interval that can be configured using the setConnectionPollingInterval(int) method for Java or the ConnectionPollingInterval property for .NET.

If the client itself remains connected but its named consumers are disconnected by the engine (due to being slow if slow consumer disconnection is enabled), then it is the caller's responsibility to force the reconnection of the consumers by disconnecting and reconnecting the client (although applications with this requirement may be better off using the EventService API instead which does this automatically; see Event Service API for more information). To prevent reconnecting slow consumers too soon after a disconnection, a minimum time between the reconnection attempts can be configured using the setReconnectPeriod(long) method for Java or the SetReconnectPeriod property for .NET.

The EngineClient object can be disconnected using disconnect() whenever required.

If the EngineClient object is no longer needed, a final cleanup should be performed by calling close() for Java or Dispose() for .NET, which will disconnect it and also ensure that any background threads started by the client have been terminated.

Clients wishing to use the EngineClient 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.

Clients wishing to use the EngineClient object to receive events should do so by adding one or more named consumers, each of which has its own independent event listener and list of channels to receive from. The named consumer methods generally have the term consumer in their names, and are defined by com.apama.engine.beans.interfaces.ReceiveConsumerOperationsInterface for Java and Apama.Engine.Client.IMessagingClient for .NET.

The Engine Client API provides the capability to inject and delete EPL entities. The methods to inject normally have the term inject in their names. The methods to delete normally have the term delete or kill in their names.

A normal deletion works only if the EPL element being deleted is not referenced by any other element. For example, you cannot delete an event type that is used by any monitors.

The Engine Client API also provides the capability to force the deletion, which deletes the specified element as well as all other elements that refer to it. For example, if monitor A has listeners for B events and C events, and you forcibly delete the C events, the operation also deletes monitor A and thus also the listener for B events.

The Engine Client API 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 the getRemoteEngineInfo() method on the EngineClient object.

The Engine Client API also provides the capability to use a background thread to periodically collect engine information and make available the last known collected information. The polling interval can be configured using the setInspectPollingInterval(integer) method for Java or the InspectPollingInterval property for .NET. The last collected information can be retrieved with the getEngineInfo() method.

The Engine Client API provides the capability to get status information from the remote correlator. The status information can be retrieved by calling the getRemoteStatus() method on the EngineClient object.

The Engine Client API also provides the capability to use a background thread to periodically collect status information and make available the last known collected status. The polling interval can be configured using the setStatusPollingInterval(integer) method for Java or the StatusPollingInterval property for .NET. The last collected status can be retrieved with the getStatus() method for Java or the Status property for .NET.

The Engine Client API also provides the capability to get user-defined status information from a client EPL application. This information can be retrieved using actions such as getUserString() on the EngineStatus object. For more information on these actions, see the corresponding section in Using the Management interface.

The Engine Client API provides the capability to connect one engine to another engine so that it receives events emitted on the specified channels. The methods to connect two engines generally have attachAsConsumerOfEngine in their names.

The Engine Client API provides locking so that concurrent use by multiple threads is safe.

To avoid deadlock problems, clients should be careful not to call methods on the object from within synchronous event listeners. Instead, if this is required, the consumer should be added as asynchronous (see the addConsumer method), or the EventService API should be used instead. However, it is safe to call EngineClient methods (except close or Dispose) from within property change listeners, which are asynchronous by default.