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:

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::EventSupplier *	connectEventConsumer (com::apama::event::EventConsumer consumer, const char const *channels, bool disconnectSlow)=0
	Connect an event receiver to the Engine. More...

virtual com::apama::event::EventSupplier *	connectEventConsumer (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 EngineInfo *	inspectEngine ()=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::EngineConnection >	getReceiverConnections ()=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

enum com::apama::engine::EngineManagement::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

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

target	The Engine to connect to
channels	An 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.
disconnectSlow	disconnect 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.
mode	the 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

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

host	The hostname of the Engine to connect to
port	The port of the Engine to connect to
channels	An 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.
disconnectSlow	disconnect 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.
mode	the 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

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

consumer	The EventConsumer to connect to the Engine.
channels	An 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.
disconnectSlow	tell 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)

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

consumer	The EventConsumer to connect to the Engine.
channels	An 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

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

pure virtual

Deletes everything from the engine.

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

pure virtual

Delete a named object from the Engine.

Parameters

name	The name of the object to be deleted.

Exceptions

EngineException

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

target	The Engine to unsubscribe from.
channels	An 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.
mode	the 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

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

host	The host of the Engine to unsubscribe from.
port	The port of the Engine to unsubscribe from.
channels	An 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.
mode	the 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

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

pure virtual

Send any outstanding events sent via sendEvents.

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

pure virtual

Force deletion of a named object from the Engine.

Parameters

name	The name of the object to be deleted.

Exceptions

EngineException

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.

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

inline

Get the Engine's current operational status.

Exceptions

EngineException

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

cdpbytes	A pointer to the array of bytes containing the CDP file
size	The size of the CDP
filename	The name of the CDP file

Exceptions

EngineException

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

cdpbytes	A pointer to the array of bytes containing the CDP file
size	The 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,which may contain warnings as well as an error message

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

cdpbytes	A pointer to the array of bytes containing the CDP file
size	The size of the CDP file
filename	The 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,which may contain warnings as well as an error message

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

jarbytes	A pointer to the array of bytes containing the jar
size	The size of the jar

Exceptions

EngineException

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

jarbytes	A pointer to the array of bytes containing the jar
size	The 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,which may contain warnings as well as an error message

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

jarbytes	A pointer to the array of bytes containing the jar
size	The size of the jar
filename	The 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,which may contain warnings as well as an error message

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

pure virtual

Inject EPL text into the Engine.

Parameters

script The EPL text to be injected.

Exceptions

EngineException

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

script EPL 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,which may contain warnings as well as an error message

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

script	The EPL text to be injected.
filename	The 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,which may contain warnings as well as an error message

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

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.

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

pure virtual

Kill a named monitor in the Engine.

Parameters

name	The name of the monitor to be killed.

Exceptions

EngineException

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

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

events An array of pointers to Event objects containing the events to inject into the Engine.

Exceptions

EngineException

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

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

pure virtual

Inject events into the Engine.

Parameters

events An array of pointers to Event objects containing the events to inject into the Engine.

Exceptions

EngineException

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

connections A 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:

engine_client_cpp.hpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation