com.apama.engine
Interface EngineManagement

All Superinterfaces:

EventConsumer

public interface EngineManagement
extends EventConsumer

The EngineManagement interface is the primary low-level interface to the Engine, and allows operations to be carried out on it.

The static methods of the EngineManagementFactory class are used to create an object implementing this interface.

Note that for most applications it is recommended to use the higher-level interfaces provided by EngineClientBean or IEventService instead of the low-level EngineManagement interface.

Because an EngineManagement object is also an EventConsumer, it can have events sent to it (and to the Engine) through its sendEvents() method.

Method Summary

void	attachAsEventConsumerTo(EngineManagement eventSupplier, java.lang.String[] channels) Connect another Engine to this one as an event supplier, with this engine consuming its events.
void	attachAsEventConsumerTo(EngineManagement eventSupplier, java.lang.String[] channels, boolean persistent) Connect another Engine to this one as an event supplier, with this engine consuming its events.
void	attachAsEventConsumerTo(EngineManagement eventSupplier, java.lang.String[] channels, boolean persistent, boolean disconnectSlow) Connect another Engine to this one as an event supplier, with this engine consuming its events.
void	attachAsEventConsumerTo(java.lang.String host, int port, java.lang.String[] channels, boolean persistent) Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.
void	attachAsEventConsumerTo(java.lang.String host, int port, java.lang.String[] channels, boolean persistent, boolean disconnectSlow) Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.
EventSupplier	connectEventConsumer(EventConsumer consumer, java.lang.String[] channels) Connect an event receiver to the Engine.
EventSupplier	connectEventConsumer(EventConsumer consumer, java.lang.String[] channels, boolean disconnectSlow) Connect an event receiver to the Engine.
void	deleteAll() Deletes everything from the engine.
void	deleteName(java.lang.String name) Delete a named object from the Engine.
void	detachAsEventConsumerFrom(EngineManagement eventSupplier, java.lang.String[] channels) Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
void	detachAsEventConsumerFrom(EngineManagement eventSupplier, java.lang.String[] channels, boolean persistent) Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
void	detachAsEventConsumerFrom(java.lang.String host, int port, java.lang.String[] channels, boolean persistent) Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
void	disconnect() Disconnect this client completely from the remote component.
void	flushEvents() Wait for any outstanding events from previous sendEvents(Event[]) calls into the Engine, and then return.
void	forceDeleteName(java.lang.String name) Force deletion of a named object from the Engine.
java.lang.String	getEngineVersion() Get the version of the Engine.
long	getRemotePhysicalComponentID() Obtain a unique ID for the component that this object is connected to.
EngineStatus	getStatus() Get the Engine's current operational status.
java.lang.String[]	injectCDP(byte[] cdpbytes, java.lang.String filename) Injects a CDP (Correlator Deployment Package) into the engine.
java.lang.String[]	injectJava(byte[] jarbytes) Injects a Java application (a jar) into the engine.
java.lang.String[]	injectMonitorScript(MonitorScript script) Inject MonitorScript text into the Engine.
java.lang.String[]	injectMonitorScript(MonitorScript script, java.lang.String filename) Inject MonitorScript text into the Engine.
EngineInfo	inspectEngine() Ask the Engine for information about the internal state.
boolean	isConnected() This method is used to check that the Engine is still connected.
void	killName(java.lang.String name) Kill a named object in the Engine.
void	ping() This method is used to check that the Engine is still alive.
void	sendEvents(Event[] events) Send events into the Engine (inherited from EventConsumer), automatically rebatching the actual event sending for efficiency.
void	sendEventsNoBatching(Event[] events) Send events into the Engine, without rebatching the actual event sending.
void	setPersistentReceiveConnections(EngineConnection... connections) Attaches this component as a persistent receiver of the remote components specified in the connections argument, then decrements the reference count of any existing connections (which typically results in their removal).

Method Detail

disconnect

void disconnect()
                throws EngineException

Disconnect this client completely from the remote component.

Throws:

EngineException

injectMonitorScript

java.lang.String[] injectMonitorScript(MonitorScript script)
                                       throws EngineException

Inject MonitorScript text into the Engine.

Parameters:

script - MonitorScript text to be injected.

Returns:

An array of strings which are the set of warnings + * generated by the MonitorScript compiler. May be zero length.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK. This exception may contain warnings.

InterruptedEngineException - If the calling thread is interrupted

injectMonitorScript

java.lang.String[] injectMonitorScript(MonitorScript script,
                                       java.lang.String filename)
                                       throws EngineException

Inject MonitorScript text into the Engine.

Parameters:

script - MonitorScript text to be injected.

filename - Filename that the monitorscript came from (or null)

Returns:

An array of strings which are the set of warnings + * generated by the MonitorScript compiler. May be zero length.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK. This exception may contain warnings.

InterruptedEngineException - If the calling thread is interrupted

deleteName

void deleteName(java.lang.String name)
                throws EngineException

Delete a named object from the Engine.

Parameters:

name - The name of the object to be deleted.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

InterruptedEngineException - If the calling thread is interrupted

forceDeleteName

void forceDeleteName(java.lang.String name)
                     throws EngineException

Force deletion of a named object from the Engine.

Parameters:

name - The name of the object to be deleted.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

killName

void killName(java.lang.String name)
              throws EngineException

Kill a named object in the Engine. Note that this will kill running monitors in such as way as to break the fault tolerance scheme.

Parameters:

name - The name of the object to be killed.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

deleteAll

void deleteAll()
               throws EngineException

Deletes everything from the engine.

Throws:

EngineException

injectJava

java.lang.String[] injectJava(byte[] jarbytes)
                              throws EngineException

Injects a Java application (a jar) into the engine.

Parameters:

jarbytes - the bytes of the Java (Jmon) Application jar to be injected.

Returns:

An array of strings which are the set of warnings about the JMon application. May be zero length.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK. This exception may contain warnings.

InterruptedEngineException - If the calling thread is interrupted

injectCDP

java.lang.String[] injectCDP(byte[] cdpbytes,
                             java.lang.String filename)
                             throws EngineException

Injects a CDP (Correlator Deployment Package) into the engine.

Parameters:

cdpbytes - the bytes of the CDP file to be injected.

filename - the name of the file we are injecting from.

Returns:

An array of strings which are the set of warnings about the CDP file. May be zero length.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK. This exception may contain warnings.

InterruptedEngineException - If the calling thread is interrupted

getStatus

EngineStatus getStatus()
                       throws EngineException

Get the Engine's current operational status.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

inspectEngine

EngineInfo inspectEngine()
                         throws EngineException

Ask the Engine for information about the internal state. This provides a minimal "introspection" mechanism to discover for example the names of each of the Monitor defintions and EventType definition that are currently known to the Engine.

Returns:

an EngineInfo object contain a "snapshot" of information about the contents of the Engine.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

ping

void ping()
          throws EngineException

This method is used to check that the Engine is still alive. If the Engine is alive it returns normally. If there is a problem then reconnection may be attempted, and if that fails, an EngineException is thrown.

Throws:

EngineException

InterruptedEngineException - If the calling thread is interrupted

isConnected

boolean isConnected()
                    throws InterruptedEngineException

This method is used to check that the Engine is still connected. It will not reconnect.

Returns:

true if connected, else false.

Throws:

InterruptedEngineException - If the calling thread is interrupted

connectEventConsumer

EventSupplier connectEventConsumer(EventConsumer consumer,
                                   java.lang.String[] channels)
                                   throws EngineException

Connect an event receiver to the Engine.

Parameters:

consumer - The EventConsumer to connect to the Engine.

channels - An array of names representing the channels to subscribe to.

Returns:

A reference to an EventSupplier resource.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

connectEventConsumer

EventSupplier connectEventConsumer(EventConsumer consumer,
                                   java.lang.String[] channels,
                                   boolean disconnectSlow)
                                   throws EngineException

Connect an event receiver to the Engine.

Parameters:

consumer - The EventConsumer to connect to the Engine.

channels - An array of names representing the channels to subscribe to.

disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.

Returns:

A reference to an EventSupplier resource.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

attachAsEventConsumerTo

void attachAsEventConsumerTo(EngineManagement eventSupplier,
                             java.lang.String[] channels)
                             throws EngineException

Connect another Engine to this one as an event supplier, with this engine consuming its events.

Parameters:

eventSupplier - The EngineManagement which will supply events to this engine.

channels - An array of names representing the channels to subscribe to.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

detachAsEventConsumerFrom

void detachAsEventConsumerFrom(EngineManagement eventSupplier,
                               java.lang.String[] channels)
                               throws EngineException

Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.

Parameters:

eventSupplier - The EngineManagement which is currently supplying events to this engine.

channels - An array of names representing the channels we were subscribed to.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

attachAsEventConsumerTo

void attachAsEventConsumerTo(EngineManagement eventSupplier,
                             java.lang.String[] channels,
                             boolean persistent)
                             throws EngineException

Connect another Engine to this one as an event supplier, with this engine consuming its events.

Parameters:

eventSupplier - The EngineManagement which will supply events to this engine.

channels - An array of names representing the channels to subscribe to.

persistent - Whether this engine should reconnect on disconnection

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

attachAsEventConsumerTo

void attachAsEventConsumerTo(EngineManagement eventSupplier,
                             java.lang.String[] channels,
                             boolean persistent,
                             boolean disconnectSlow)
                             throws EngineException

Connect another Engine to this one as an event supplier, with this engine consuming its events.

Parameters:

eventSupplier - The EngineManagement which will supply events to this engine.

channels - An array of names representing the channels to subscribe to.

persistent - Whether this engine should reconnect on disconnection

disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first connection's disconnectSlow value is used; subsequent connections to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

detachAsEventConsumerFrom

void detachAsEventConsumerFrom(EngineManagement eventSupplier,
                               java.lang.String[] channels,
                               boolean persistent)
                               throws EngineException

Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.

Parameters:

eventSupplier - The EngineManagement which is currently supplying events to this engine.

channels - An array of names representing the channels we were subscribed to.

persistent - Whether this engine should reconnect on disconnection

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

attachAsEventConsumerTo

void attachAsEventConsumerTo(java.lang.String host,
                             int port,
                             java.lang.String[] channels,
                             boolean persistent)
                             throws EngineException

Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.

Parameters:

host - host of the component which is supplying events

port - port of the component which is supplying events

channels - An array of names representing the channels to subscribe to.

persistent - Whether this engine should reconnect on disconnection

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

attachAsEventConsumerTo

void attachAsEventConsumerTo(java.lang.String host,
                             int port,
                             java.lang.String[] channels,
                             boolean persistent,
                             boolean disconnectSlow)
                             throws EngineException

Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.

Parameters:

host - host of the component which is supplying events

port - port of the component which is supplying events

channels - An array of names representing the channels to subscribe to.

persistent - Whether this engine should reconnect on disconnection

disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first connection's disconnectSlow value is used; subsequent connections to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

detachAsEventConsumerFrom

void detachAsEventConsumerFrom(java.lang.String host,
                               int port,
                               java.lang.String[] channels,
                               boolean persistent)
                               throws EngineException

Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.

Parameters:

host - host of the component which is supplying events

port - port of the component which is supplying events

channels - An array of names representing the channels we were subscribed to.

persistent - Whether this engine should reconnect on disconnection

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

setPersistentReceiveConnections

void setPersistentReceiveConnections(EngineConnection... connections)
                                     throws EngineException

Attaches this component as a persistent receiver of the remote components specified in the connections argument, then decrements the reference count of any existing connections (which typically results in their removal).

Parameters:

connections - Must not contain null elements.

Throws:

EngineException - If the change in the persistent connection set failed. Note that no exception is thrown if some of the specified connections could not be established immediately - in this case the receiver will simply keep trying to reconnect in the background.

getEngineVersion

java.lang.String getEngineVersion()
                                  throws EngineException

Get the version of the Engine.

Returns:

A string with the version of the Engine connected to.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

sendEvents

void sendEvents(Event[] events)
                throws EngineException

Send events into the Engine (inherited from EventConsumer), automatically rebatching the actual event sending for efficiency.

Specified by:

sendEvents in interface EventConsumer

Parameters:

events - An array of Event objects containing the events to send into the Engine.

Throws:

InterruptedEngineException - If the calling thread is interrupted

EngineException - Thrown if any exceptions occur in the Client SDK.

sendEventsNoBatching

void sendEventsNoBatching(Event[] events)
                          throws EngineException

Send events into the Engine, without rebatching the actual event sending.

Parameters:

events - An array of Event objects containing the events to send into the Engine.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

InterruptedEngineException - If the calling thread is interrupted

See Also:

flushEvents()

flushEvents

void flushEvents()
                 throws EngineException,
                        java.lang.InterruptedException

Wait for any outstanding events from previous sendEvents(Event[]) calls into the Engine, and then return.

Throws:

EngineException - Thrown if any exceptions occur in the Client SDK.

java.lang.InterruptedException - Thrown if this thread is interrupted while waiting for outstanding events to be sent and acknowledged (see Thread.interrupt().

See Also:

sendEvents(Event[])

getRemotePhysicalComponentID

long getRemotePhysicalComponentID()

Obtain a unique ID for the component that this object is connected to. The physical ID is the same for a given process, so connecting to the same process should yield the same physical component ID. Restarting the process will yield a different ID, even if re-started on the same host and port. (This is the same ID logged in server log files)