Apama  10.15.1.2
com::apama::engine::EngineManagement Class Referenceabstract

The Engine Management class acts as the interface to the Engine, and allows operations to be carried out on it. More...

#include <engine_client_cpp.hpp>

Inheritance diagram for com::apama::engine::EngineManagement:
com::apama::event::EventConsumer

Public Types

enum  ConnectMode { CONNECT_LEGACY, CONNECT_PARALLEL }
 The mode that attachAsEventConsumerTo and detachAsEventConsumerFrom operate in. More...
 

Public Member Functions

virtual void injectMonitorScript (MonitorScript &script)=0
 Inject EPL text into the Engine. More...
 
virtual const char *const * injectMonitorScriptWithWarnings (MonitorScript &script)=0
 Inject EPL text into the Engine, returning any warnings produced by the correlator; maintained for compatibility only, please use injectMonitorScriptWithWarningsFilename instead of this function. More...
 
virtual const char *const * injectMonitorScriptWithWarningsFilename (MonitorScript &script, const char *filename)=0
 Inject EPL text into the Engine, supplying the filename it was injected from and returning any warnings produced by the correlator. More...
 
virtual void deleteName (const char *name)=0
 Delete a named object from the Engine. More...
 
virtual void forceDeleteName (const char *name)=0
 Force deletion of a named object from the Engine. More...
 
virtual void killName (const char *name)=0
 Kill a named monitor in the Engine. More...
 
virtual void deleteAll ()=0
 Deletes everything from the engine. More...
 
virtual void injectJava (const AP_uint8 *jarbytes, AP_uint32 size)=0
 Injects a Java application (a jar) into the engine. More...
 
virtual const char *const * injectJavaWithWarnings (const AP_uint8 *jarbytes, AP_uint32 size)=0
 Injects a Java application (a jar) into the engine; maintained for compatibility only, please use injectJavaWithWarningsFilename instead of this function. More...
 
virtual const char *const * injectJavaWithWarningsFilename (const AP_uint8 *jarbytes, AP_uint32 size, const char *filename)=0
 Injects a Java application (a jar) into the engine. More...
 
virtual void injectCDP (const AP_uint8 *cdpbytes, AP_uint32 size, const char *filename=NULL)=0
 Injects a CDP (Correlator Deployment Package file) into the engine. More...
 
virtual const char *const * injectCDPWithWarnings (const AP_uint8 *cdpbytes, AP_uint32 size)=0
 Injects a CDP (Correlator Deployment Package file) into the engine; maintained for compatibility only, please use injectCDPWithWarningsFilename instead of this function. More...
 
virtual const char *const * injectCDPWithWarningsFilename (const AP_uint8 *cdpbytes, AP_uint32 size, const char *filename)=0
 Injects a CDP (Correlator Deployment Package file) into the engine. More...
 
EngineStatus getStatus ()
 Get the Engine's current operational status. More...
 
virtual com::apama::event::EventSupplierconnectEventConsumer (com::apama::event::EventConsumer *consumer, const char *const *channels, bool disconnectSlow)=0
 Connect an event receiver to the Engine. More...
 
virtual com::apama::event::EventSupplierconnectEventConsumer (com::apama::event::EventConsumer *consumer, const char *const *channels)=0
 Connect an event receiver to the Engine. More...
 
virtual bool attachAsEventConsumerTo (EngineManagement *target, const char *const *channels, bool disconnectSlow=false, ConnectMode mode=CONNECT_LEGACY)=0
 Connect this Engine as an event receiver to another Engine. More...
 
virtual bool attachAsEventConsumerTo (const char *host, int port, const char *const *channels, bool disconnectSlow=false, ConnectMode mode=CONNECT_LEGACY)=0
 Connect this Engine as an event receiver to another Engine. More...
 
virtual void detachAsEventConsumerFrom (EngineManagement *target, const char *const *channels, ConnectMode mode=CONNECT_LEGACY)=0
 Unsubscribe as an event receiver from another engine. More...
 
virtual void detachAsEventConsumerFrom (const char *host, int port, const char *const *channels, ConnectMode mode=CONNECT_LEGACY)=0
 Unsubscribe as an event receiver from another engine. More...
 
virtual void sendEvents (const com::apama::event::Event *const *events)=0
 Inject events into the Engine (inherited from EventConsumer), automatically batching messages on a separate thread. More...
 
virtual void sendEventsNoBatching (const com::apama::event::Event *const *events)=0
 Inject events into the Engine. More...
 
virtual void flushEvents ()=0
 Send any outstanding events sent via sendEvents. More...
 
virtual EngineInfoinspectEngine ()=0
 Returns information about the monitors, event types and container types which exist in the engine. More...
 
virtual void ping ()=0
 This method is used to check that the Engine is still alive. More...
 
virtual bool isConnected ()=0
 This method is used to check that this object is still connected to the Engine. More...
 
virtual void setReceiverConnections (const std::vector< com::apama::engine::EngineConnection > &connections)=0
 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). More...
 
virtual const std::vector< com::apama::engine::EngineConnectiongetReceiverConnections ()=0
 Get all the persistent connections associated with the engine. More...
 

Detailed Description

The Engine Management class acts as the interface to the Engine, and allows operations to be carried out on it.

It is not possible to construct an object of this class. The static methods supplied below in the engine namespace must be used instead.

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

EngineManagement objects are not copiable. EngineManagement objects are created using com::apama::engine::connectToEngine, com::apama::engine::connectToEngineReceiveOnly or com::apama::engine::connectToEngineMonitorOnly. EngineManagement objects are deleted using com::apama::engine::disconnectFromEngine.

Member Enumeration Documentation

◆ ConnectMode

The mode that attachAsEventConsumerTo and detachAsEventConsumerFrom operate in.

Enumerator
CONNECT_LEGACY 

For backwards compatibility, single serial connection.

CONNECT_PARALLEL 

Allow parallel connections on multiple channels.

Member Function Documentation

◆ attachAsEventConsumerTo() [1/2]

virtual bool com::apama::engine::EngineManagement::attachAsEventConsumerTo ( EngineManagement target,
const char *const *  channels,
bool  disconnectSlow = false,
ConnectMode  mode = CONNECT_LEGACY 
)
pure virtual

Connect this Engine as an event receiver to another Engine.

Parameters
targetThe Engine to connect to
channelsAn array of names representing the channels to subscribe to. This is a null-terminated array of pointers to zero-terminated char arrays. If this is null or empty, subscribe to all channels. Note that these channel names should be encoded in UTF-8.
disconnectSlowdisconnect if slow. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour. Default is false.
modethe connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to CONNECT_PARALLEL for connection per channel and channel values passed through.
Returns
true if successful
Exceptions
EngineException

◆ attachAsEventConsumerTo() [2/2]

virtual bool com::apama::engine::EngineManagement::attachAsEventConsumerTo ( const char *  host,
int  port,
const char *const *  channels,
bool  disconnectSlow = false,
ConnectMode  mode = CONNECT_LEGACY 
)
pure virtual

Connect this Engine as an event receiver to another Engine.

Parameters
hostThe hostname of the Engine to connect to
portThe port of the Engine to connect to
channelsAn array of names representing the channels to subscribe to. This is a null-terminated array of pointers to zero-terminated char arrays. If this is null or empty, subscribe to all channels. Note that these channel names should be encoded in UTF-8.
disconnectSlowdisconnect if slow. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour.
modethe connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to CONNECT_PARALLEL for connection per channel and channel values passed through.
Returns
true if successful
Exceptions
EngineException

◆ connectEventConsumer() [1/2]

virtual com::apama::event::EventSupplier* com::apama::engine::EngineManagement::connectEventConsumer ( com::apama::event::EventConsumer consumer,
const char *const *  channels,
bool  disconnectSlow 
)
pure virtual

Connect an event receiver to the Engine.

Parameters
consumerThe EventConsumer to connect to the Engine.
channelsAn array of names representing the channels to subscribe to. This is a null-terminated array of pointers to zero-terminated char arrays. If it is null or empty subscribe to all channels. Note that these channel names should be encoded in UTF-8.
disconnectSlowtell the correlator it can disconnect this receiver if it is slow. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour. Defaults to false.
Returns
A reference to an EventSupplier resource, which the caller is responsible for freeing, using com::apama::event::deleteEventSupplier(). Each EventSupplier resource must be explicitly disconnected or deleted before disconnecting this EngineManagement object.
Exceptions
EngineException
Deprecated:
This method is deprecated. Instead use EngineManagement::connectEventConsumer(com::apama::event::EventConsumer*, const char* const*) with com::apama::engine::connectToEngine(const char*, unsigned short, bool)

◆ connectEventConsumer() [2/2]

virtual com::apama::event::EventSupplier* com::apama::engine::EngineManagement::connectEventConsumer ( com::apama::event::EventConsumer consumer,
const char *const *  channels 
)
pure virtual

Connect an event receiver to the Engine.

Parameters
consumerThe EventConsumer to connect to the Engine.
channelsAn array of names representing the channels to subscribe to. This is a null-terminated array of pointers to zero-terminated char arrays. If it is null or empty subscribe to all channels. Note that these channel names should be encoded in UTF-8.
Returns
A reference to an EventSupplier resource, which the caller is responsible for freeing, using com::apama::event::deleteEventSupplier(). Each EventSupplier resource must be explicitly disconnected or deleted before disconnecting this EngineManagement object.
Exceptions
EngineException

◆ deleteAll()

virtual void com::apama::engine::EngineManagement::deleteAll ( )
pure virtual

Deletes everything from the engine.

◆ deleteName()

virtual void com::apama::engine::EngineManagement::deleteName ( const char *  name)
pure virtual

Delete a named object from the Engine.

Parameters
nameThe name of the object to be deleted.
Exceptions
EngineException

◆ detachAsEventConsumerFrom() [1/2]

virtual void com::apama::engine::EngineManagement::detachAsEventConsumerFrom ( EngineManagement target,
const char *const *  channels,
ConnectMode  mode = CONNECT_LEGACY 
)
pure virtual

Unsubscribe as an event receiver from another engine.

Parameters
targetThe Engine to unsubscribe from.
channelsAn array of names representing the channels to unsubscribe from. This is a null-terminated array of pointers to zero-terminated char arrays. If this is null or empty unsubscribe from all channels.
modethe connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to CONNECT_PARALLEL for connection per channel and channel values passed through.
Exceptions
EngineException

◆ detachAsEventConsumerFrom() [2/2]

virtual void com::apama::engine::EngineManagement::detachAsEventConsumerFrom ( const char *  host,
int  port,
const char *const *  channels,
ConnectMode  mode = CONNECT_LEGACY 
)
pure virtual

Unsubscribe as an event receiver from another engine.

Parameters
hostThe host of the Engine to unsubscribe from.
portThe port of the Engine to unsubscribe from.
channelsAn array of names representing the channels to unsubscribe from. This is a null-terminated array of pointers to zero-terminated char arrays. If this is null or empty unsubscribe from all channels.
modethe connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to CONNECT_PARALLEL for connection per channel and channel values passed through.
Exceptions
EngineException

◆ flushEvents()

virtual void com::apama::engine::EngineManagement::flushEvents ( )
pure virtual

Send any outstanding events sent via sendEvents.

◆ forceDeleteName()

virtual void com::apama::engine::EngineManagement::forceDeleteName ( const char *  name)
pure virtual

Force deletion of a named object from the Engine.

Parameters
nameThe name of the object to be deleted.
Exceptions
EngineException

◆ getReceiverConnections()

virtual const std::vector<com::apama::engine::EngineConnection> com::apama::engine::EngineManagement::getReceiverConnections ( )
pure virtual

Get all the persistent connections associated with the engine.

Returns
an array of EngineConnection objects.

◆ getStatus()

EngineStatus com::apama::engine::EngineManagement::getStatus ( )
inline

Get the Engine's current operational status.

Exceptions
EngineException

◆ injectCDP()

virtual void com::apama::engine::EngineManagement::injectCDP ( const AP_uint8 *  cdpbytes,
AP_uint32  size,
const char *  filename = NULL 
)
pure virtual

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

Parameters
cdpbytesA pointer to the array of bytes containing the CDP file
sizeThe size of the CDP
filenameThe name of the CDP file
Exceptions
EngineException

◆ injectCDPWithWarnings()

virtual const char* const* com::apama::engine::EngineManagement::injectCDPWithWarnings ( const AP_uint8 *  cdpbytes,
AP_uint32  size 
)
pure virtual

Injects a CDP (Correlator Deployment Package file) into the engine; maintained for compatibility only, please use injectCDPWithWarningsFilename instead of this function.

Parameters
cdpbytesA pointer to the array of bytes containing the CDP file
sizeThe size of the CDP file
Returns
A pointer to a NULL terminated array of warnings which must be deleted with the deleteWarnings() function, or NULL if there are none
Exceptions
EngineException,whichmay contain warnings as well as an error message

◆ injectCDPWithWarningsFilename()

virtual const char* const* com::apama::engine::EngineManagement::injectCDPWithWarningsFilename ( const AP_uint8 *  cdpbytes,
AP_uint32  size,
const char *  filename 
)
pure virtual

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

Parameters
cdpbytesA pointer to the array of bytes containing the CDP file
sizeThe size of the CDP file
filenameThe name of the CDP file
Returns
A pointer to a NULL terminated array of warnings which must be deleted with the deleteWarnings() function, or NULL if there are none
Exceptions
EngineException,whichmay contain warnings as well as an error message

◆ injectJava()

virtual void com::apama::engine::EngineManagement::injectJava ( const AP_uint8 *  jarbytes,
AP_uint32  size 
)
pure virtual

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

Parameters
jarbytesA pointer to the array of bytes containing the jar
sizeThe size of the jar
Exceptions
EngineException

◆ injectJavaWithWarnings()

virtual const char* const* com::apama::engine::EngineManagement::injectJavaWithWarnings ( const AP_uint8 *  jarbytes,
AP_uint32  size 
)
pure virtual

Injects a Java application (a jar) into the engine; maintained for compatibility only, please use injectJavaWithWarningsFilename instead of this function.

Parameters
jarbytesA pointer to the array of bytes containing the jar
sizeThe size of the jar
Returns
A pointer to a NULL terminated array of warnings which must be deleted with the deleteWarnings() function, or NULL if there are none
Exceptions
EngineException,whichmay contain warnings as well as an error message

◆ injectJavaWithWarningsFilename()

virtual const char* const* com::apama::engine::EngineManagement::injectJavaWithWarningsFilename ( const AP_uint8 *  jarbytes,
AP_uint32  size,
const char *  filename 
)
pure virtual

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

Parameters
jarbytesA pointer to the array of bytes containing the jar
sizeThe size of the jar
filenameThe name of the jar file
Returns
A pointer to a NULL terminated array of warnings which must be deleted with the deleteWarnings() function, or NULL if there are none
Exceptions
EngineException,whichmay contain warnings as well as an error message

◆ injectMonitorScript()

virtual void com::apama::engine::EngineManagement::injectMonitorScript ( MonitorScript script)
pure virtual

Inject EPL text into the Engine.

Parameters
scriptThe EPL text to be injected.
Exceptions
EngineException

◆ injectMonitorScriptWithWarnings()

virtual const char* const* com::apama::engine::EngineManagement::injectMonitorScriptWithWarnings ( MonitorScript script)
pure virtual

Inject EPL text into the Engine, returning any warnings produced by the correlator; maintained for compatibility only, please use injectMonitorScriptWithWarningsFilename instead of this function.

Parameters
scriptEPL text to be injected.
Returns
A pointer to a NULL terminated array of warnings which must be deleted with the deleteWarnings() function, or NULL if there are none
Exceptions
EngineException,whichmay contain warnings as well as an error message

◆ injectMonitorScriptWithWarningsFilename()

virtual const char* const* com::apama::engine::EngineManagement::injectMonitorScriptWithWarningsFilename ( MonitorScript script,
const char *  filename 
)
pure virtual

Inject EPL text into the Engine, supplying the filename it was injected from and returning any warnings produced by the correlator.

Parameters
scriptThe EPL text to be injected.
filenameThe filename the EPL text was injected from
Returns
A pointer to a NULL terminated array of warnings which must be deleted with the deleteWarnings() function, or NULL if there are none
Exceptions
EngineException,whichmay contain warnings as well as an error message

◆ inspectEngine()

virtual EngineInfo* com::apama::engine::EngineManagement::inspectEngine ( )
pure virtual

Returns information about the monitors, event types and container types which exist in the engine.

Use deleteInfo to delete the returned object when it is no longer needed.

Returns
Information about the engine.
Exceptions
EngineException

◆ isConnected()

virtual bool com::apama::engine::EngineManagement::isConnected ( )
pure virtual

This method is used to check that this object is still connected to the Engine.

It will never reconnect. Returns true if connected.

◆ killName()

virtual void com::apama::engine::EngineManagement::killName ( const char *  name)
pure virtual

Kill a named monitor in the Engine.

Parameters
nameThe name of the monitor to be killed.
Exceptions
EngineException

◆ ping()

virtual void com::apama::engine::EngineManagement::ping ( )
pure virtual

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 an EngineException is thrown.

At present, ping() will not attempt to reconnect, and will therefore always throw an exception once the connection is lost. A new management object should be created and the old one cleaned up (disconnected) when reconnection is needed.

Exceptions
EngineException

◆ sendEvents()

virtual void com::apama::engine::EngineManagement::sendEvents ( const com::apama::event::Event *const *  events)
pure virtual

Inject events into the Engine (inherited from EventConsumer), automatically batching messages on a separate thread.

May return before events are sent - call flushEvents before exiting.

Parameters
eventsAn array of pointers to Event objects containing the events to inject into the Engine.
Exceptions
EngineException

Implements com::apama::event::EventConsumer.

◆ sendEventsNoBatching()

virtual void com::apama::engine::EngineManagement::sendEventsNoBatching ( const com::apama::event::Event *const *  events)
pure virtual

Inject events into the Engine.

Parameters
eventsAn array of pointers to Event objects containing the events to inject into the Engine.
Exceptions
EngineException

◆ setReceiverConnections()

virtual void com::apama::engine::EngineManagement::setReceiverConnections ( const std::vector< com::apama::engine::EngineConnection > &  connections)
pure virtual

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
connectionsA vector of EngineConnection objects. The method call doesn't modify the vector.

This method 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.

Exceptions
EngineException

The documentation for this class was generated from the following file: