Apama.Engine.Client.IEngineClient Interface Reference

Provides a convenient interface for interacting with an Apama engine, typically a Correlator. This includes the ability to send and receive events, inject and delete EPL/MonitorScript, connect Apama engines together, inspect what was injected into correlator and more. More...

Inherits Apama.Engine.Client.IMessagingClient, Apama.Engine.Client.ICorrelatorManagement, and Apama.Engine.Client.IConnectOperations.

Additional Inherited Members
Public Member Functions inherited from Apama.Engine.Client.IMessagingClient
IConsumerOperations	AddConsumer (string uniqueName, params string[] channels)
	Add a new uniquely-named consumer that listens on a specified set of channels. More...
IConsumerOperations	AddConsumer (string uniqueName, string[] channels, bool disconnectSlow)
	Add a new uniquely-named consumer that listens on a specified set of channels. More...
IConsumerOperations	AddConsumer (string uniqueName, string[] channels, bool disconnectSlow, bool async)
	Add a new uniquely-named consumer that listens on a specified set of channels. More...
void	CancelDeleteFileRead ()
	The purpose of the CancelFileRead property is to provide a mechanism to cleanly terminate the processing of events from file, when the DeleteNamesFromFile() or KillNamesFromFile() method is in progress. When CancelFileRead is set to true, the Name deleting loop will terminate at the next iteration. More...
void	CancelInjectFileRead ()
	The purpose of the CancelInjectFileRead property is to provide a mechanism to cleanly terminate the processing of MonitorScripts from file, when the InjectMonitorScriptFromFile() method is in progress. When CancelInjectFileRead is set to true, the MonitorScript injecting loop will terminate at the next iteration. More...
void	CancelSendFileRead ()
	The purpose of the CancelSendFileRead property is to provide a mechanism to cleanly terminate the processing of events from file, when the IMessagingClient.SendEventsFromFile(string[], int) method is in progress. When CancelFileRead is set to true, the event sending loop will terminate at the next iteration. More...
void	ConnectInBackground ()
	Requests that the client begins to establish a connection automatically in the background. More...
void	DeleteAll ()
	Deletes everything from the engine. More...
void	DeleteName (string name, bool force)
	Delete a name from the engine. If a connection is not yet established, this method will request a connection. More...
void	DeleteNames (string[] names, bool force)
	Delete a number of names. If a connection is not yet established, this method will request a connection. More...
void	DeleteNamesFromFile (string[] fileNames, bool force)
	Delete a number of names from a file or stdin. If a connection is not yet established, this method will request a connection. More...
void	DeleteNamesFromFile (string[] fileNames, bool force, bool utf8)
	Delete a number of names from a file or stdin. If a connection is not yet established, this method will request a connection. More...
void	FlushEvents ()
	Wait for any outstanding events from previous Apama.Engine.EngineManagement.SendEvents(Apama.Event.Event[]) or SendEvents(bool, Apama.Event.Event[]) (where the Boolean is true) calls into the Engine, and then return. More...
IConsumerOperations[]	GetAllConsumers ()
	Get all existing uniquely-named consumers. More...
IConsumerOperations	GetConsumer (string uniqueName)
	Get an existing uniquely-named consumer. More...
void	InjectCDP (byte[] cdpBytes, String filename)
	Send the bytes of a CDP (Correlator Deployment Package) to the engine. If a connection is not yet established, this method will request a connection. More...
void	InjectCDPsFromFile (params string[] fileNames)
	Inject a number of CDP (Correlator Deployment Package)(s) from a file or stdin. If a connection is not yet established, this method will request a connection. More...
void	InjectJavaApplication (byte[] jarBytes)
	Send the bytes of a Java (JMon) Application jar to the engine. If a connection is not yet established, this method will request a connection. More...
void	InjectJavaApplicationsFromFile (params string[] fileNames)
	Inject a number of Java (JMon) Application(s) from a file or stdin. If a connection is not yet established, this method will request a connection. More...
void	InjectMonitorScript (MonitorScript script)
	Send MonitorScript text to the engine (using the obsolete MonitorScript object) without blocking concurrent calls to operations on this bean instance. More...
void	InjectMonitorScript (string eplString)
	Send MonitorScript text to the engine without blocking concurrent calls to operations on this bean instance. More...
void	InjectMonitorScript (string eplString, string fileName)
	Send MonitorScript text to the engine without blocking concurrent calls to operations on this bean instance. More...
void	InjectMonitorScriptFromFile (params string[] fileNames)
	Inject a number of monitors from a file or stdin. If a connection is not yet established, this method will request a connection. More...
void	InjectMonitorScriptFromFile (string[] fileNames, bool utf8)
	Inject a number of monitors from a file or stdin. If a connection is not yet established, this method will request a connection. More...
void	RemoveAllConsumers ()
	Remove and disconnect all existing uniquely-named consumers. If a consumer is asynchronous, it may still be called after this method has returned; otherwise, the RemoveConsumer will wait for any calls into the consumer to complete. More...
void	RemoveConsumer (string uniqueName)
	Remove and disconnect any existing uniquely-named consumer. If a consumer is asynchronous, it may still be called after this method has returned; otherwise, the RemoveConsumer will wait for any calls into the consumer to complete. More...
void	SendEvents (params Apama.Event.Event[] events)
	Send an array of Event objects to the Engine, performing auto-batching. More...
void	SendEvents (bool autoBatch, params Apama.Event.Event[] events)
	Send an array of Event objects to the Engine, optionally not performing auto-batching. More...
void	SendEventsFromFile (string[] fileNames, int loopCount)
	Send a number of events from a file or stdin. More...
void	SendEventsFromFile (string[] fileNames, int loopCount, bool utf8)
	Send a number of events from a file or stdin. More...
void	SendEventsFromFile (string[] fileNames, int loopCount, bool utf8, bool autoBatch)
	Send a number of events from a file or stdin, specifying the file encoding detection mode and whether to auto-batch events or not. More...
void	SetReconnectPeriod (long reconnectPeriodMillis)
	Set the minimum period between attempts to reconnect the client and/or any of the its named consumers that have been disconnected (e.g. as a slow consumer). More...
void	SetReconnectPolicy (IReconnectPolicy policy)
	Set a singleton reconnection policy that will be used to limit when reconnection can be attempted for the client, and/or any of its named consumers that have been disconnected (e.g. as a slow consumer). More...
Public Member Functions inherited from Apama.Net.Client.IBaseClient
void	AddPropertyChangeListener (PropertyChangedEventHandler listener)
	Add a property change listener. Use this method to be informed whenever the a property value is changed. More...
void	AddPropertyChangeListener (string propertyName, PropertyChangedEventHandler listener)
	Add a property change listener for a specific named property. More...
void	AddPropertyChangeListenerSync (PropertyChangedEventHandler listener)
	Add a property change listener. Use this method to be informed whenever the a property value is changed. More...
void	AddPropertyChangeListenerSync (string propertyName, PropertyChangedEventHandler listener)
	Add a property change listener for a specific named property. More...
void	ConnectNow ()
	Manually request that the client connects to the remote server. Repeated calls are permitted, and attempting to connect a client that is already connected is identical to calling this PingServer(). More...
void	Disconnect ()
	Disconnect from the server and terminate background threads; equivalent to Dispose(). More...
void	FlushListeners ()
	Utility method that blocks until all pending property change listeners that have already fired have finished executing. More...
void	PingServer ()
	Manually test if the remote server process is alive and responding to client requests. This method makes a no-arg, void return, method call on the client interface of the server. If a connection is not yet established, this method will request a connection. In the event that a connection cannot be established, or an error during the ping, an EngineException will be thrown. More...
void	RemovePropertyChangeListener (PropertyChangedEventHandler listener)
	Remove a property change listener. More...
void	RemovePropertyChangeListener (string propertyName, PropertyChangedEventHandler listener)
	Remove a property change listener for a specific named property. More...
void	RemovePropertyChangeListenerSync (PropertyChangedEventHandler listener)
	Remove a property change listener registered with AddPropertyChangeListenerSync(). More...
void	RemovePropertyChangeListenerSync (string propertyName, PropertyChangedEventHandler listener)
	Remove a property change listener for a specific named property registered with AddPropertyChangeListenerSync(). More...
Public Member Functions inherited from Apama.Engine.Client.ICorrelatorManagement
void	CancelDeleteFileRead ()
	Setter for the cancelFileRead property for the Kill operations. The purpose of the cancelFileRead property is to provide a mechanism to cleanly terminate the processing of events from file, when the deleteNamesFromFile() or killNamesFromFile() method is in progress. When cancelFileRead is set to true, the Name deleting loop will terminate at the next iteration. More...
EngineInfo	GetEngineInfo ()
	Get the most recently recorded inspection information. Note that calling this method does NOT invoke a remote call to a correlator, but simply returns the last known information as collected by the internal worker thread, if that thread is running. More...
EngineInfo	GetRemoteEngineInfo ()
	Request the remote Engine inspection info. This method will not store the inspection result, and is available as an alternative to the background polling service. If a connection is not yet established, this method will request a connection. More...
EngineStatus	GetRemoteStatus ()
	Request the remote Engine status. This method will not store the status result, and is available as an alternative to the background polling service. If a connection is not yet established, this method will request a connection. More...
void	KillName (string name)
	Kill a named monitor from the engine. Note that this will kill running monitors in such as way as to break the fault tolerance scheme. If a connection is not yet established, this method will request a connection. More...
void	KillNames (params string[] names)
	Kill a number of named monitors. Note that this will kill running monitors in such as way as to break the fault tolerance scheme. If a connection is not yet established, this method will request a connection. More...
void	KillNamesFromFile (params string[] fileNames)
	Kill a number of named monitors from a file or stdin. Note that this will kill running monitors in such as way as to break the fault tolerance scheme. If a connection is not yet established, this method will request a connection. More...
void	KillNamesFromFile (string[] fileNames, bool utf8)
	Kill a number of named monitors from a file or stdin. Note that this will kill running monitors in such as way as to break the fault tolerance scheme. If a connection is not yet established, this method will request a connection. More...
void	StartInspectPollingThread ()
	Start the local inspect polling thread. If a connection is not yet established, this method will request a connection. More...
void	StartStatusPollingThread ()
	Start the local status polling thread. If a connection is not yet established, this method will request a connection. More...
void	StopInspectPollingThread ()
	Stop the local inspect polling thread. More...
void	StopStatusPollingThread ()
	Stop the local status polling thread. More...
Public Member Functions inherited from Apama.Engine.Client.IConnectOperations
void	AttachAsConsumerOfEngine (IMessagingClient sourceEngine, string[] channels)
	Connect this engine to another (non-persisently) so that it receives events emitted on the specified channels. This is equivalent to the engine_connect command. More...
void	AttachAsConsumerOfEngine (string sourceHost, int sourcePort, string[] channels)
	Connect this engine to another (non-persistently) so that it receives events emitted on the specified channels. This is equivalent to the engine_connect command. More...
void	AttachAsConsumerOfEngine (string sourceHost, int sourcePort, string[] channels, bool persistent)
	Connect this engine to another so that it receives events emitted on the specified channels. This is equivalent to the engine_connect command. More...
void	AttachAsConsumerOfEngine (string sourceHost, int sourcePort, string[] channels, bool persistent, bool disconnectSlow, EngineManagement.ConnectMode mode)
	Connect this engine to another so that it receives events emitted on the specified channels. This is equivalent to the engine_connect command. More...
void	DetachAsConsumerOfEngine (IMessagingClient sourceEngine, string[] channels)
	Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the More...
void	DetachAsConsumerOfEngine (string sourceHost, int sourcePort, string[] channels)
	Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the More...
void	DetachAsConsumerOfEngine (string sourceHost, int sourcePort, string[] channels, bool persistent)
	Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the More...
void	DetachAsConsumerOfEngine (string sourceHost, int sourcePort, string[] channels, bool persistent, EngineManagement.ConnectMode mode)
	Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the More...
Properties inherited from Apama.Engine.Client.IMessagingClient
bool	AllConsumersConnected [get]
	Determine if the client and all of the existing uniquely-named consumers are connected. More...
Properties inherited from Apama.Net.Client.IBaseClient
int	ConnectionPollingInterval [get, set]
	Gets/sets the polling interval (in milliseconds) for the internal connection test thread. When setting the parameter, if the value of the parameter is negative, then the default value will be used instead. More...
string	Host [get, set]
	Get the name of the host to be connected to. This is the name of the host on which the server to be monitored is running. More...
bool	IsConnected [get]
	Get the connected property value. This is the status of the client - connected, or not connected. It indicates if the client has a valid instance of the underlying RPC interface. More...
bool	IsMonitorOnly [get, set]
	Get/set the MonitorOnly property. An engine client running in "monitor only" mode cannot perform any state-changing operations on the remote component, nor can it receive events from it. Essentially it is limited to using the ping, inspect and watch operations only. More...
bool	IsReceiveOnly [get, set]
	Get/set the ReceiveOnly property. An engine client running in "receive only" mode cannot perform any state-changing operations on the remote component, but it can receive events from it. More...
int	Port [get, set]
	Get the port number to be connected to. This is the port number on which the server to be monitored is listening. More...
Properties inherited from Apama.Engine.Client.ICorrelatorManagement
int	InspectPollingInterval [get, set]
	Get/set the inspectPollingInterval (in milliseconds) that the background thread should wait between calls for new information. More...
EngineStatus	Status [get]
	Get the most recently recorded status. Note that calling this method does NOT invoke a remote call to a correlator, but simply returns the last known status as collected by the internal worker thread. More...
int	StatusPollingInterval [get, set]
	Get/set the statusPollingInterval (in milliseconds) that the background thread should wait between calls for new status information. More...

Detailed Description

Provides a convenient interface for interacting with an Apama engine, typically a Correlator. This includes the ability to send and receive events, inject and delete EPL/MonitorScript, connect Apama engines together, inspect what was injected into correlator and more.

See Apama.Engine.Client.EngineClientConstants for constants used by this interface.

Receiving events using the engine client:

Clients wishing to use the engine client 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 "consumer" in their name.

Users needing more advanced send/receive functionality should also consider using the higher level Apama.Services.Event.IEventService rather than the engine client.

Use Apama.Event.Parser.EventType and its associated classes to parse and generate Apama.Event.Event objects for receiving and sending using this class.

Lifecycle of the engine client:

Once this engine client has been configured as needed (e.g. Apama.Net.Client.IBaseClient.Port, Apama.Net.Client.IBaseClient.Host), a connection can be established either synchronously using Apama.Net.Client.IBaseClient.ConnectNow (which throws an exception on error) or asynchronously using Apama.Engine.Client.IMessagingClient.ConnectInBackground (which automatically retries until a connection is established - see Apama.Net.Client.IBaseClient.ConnectionPollingInterval and Apama.Engine.Client.IMessagingClient.SetReconnectPeriod).

Once the client connected successfully, a background thread will keep pinging it to ensure the connection is still up (see Apama.Net.Client.IBaseClient.ConnectionPollingInterval). If the entire client connection is lost, the Apama.Net.Client.Interfaces.BaseClientConstants.PropertyConnected and Apama.Engine.Client.EngineClientConstants.PropertyAllConsumersConnected properties will change to false to notify the user of the engine client, and the client will continue to try to reconnect in the background (with the retry interval configurable using Apama.Net.Client.IBaseClient.ConnectionPollingInterval). 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 reconnection of the consumers by disconnecting and reconnecting the client (although applications with this requirement may be better off using the Apama.Services.Event.IEventService instead). To prevent reconnecting slow consumers too soon after disconnection, a minimum time between reconnection attempts can be configured using Apama.Engine.Client.IMessagingClient.SetReconnectPeriod.

The engine client can be disconnected using Apama.Net.Client.IBaseClient.Disconnect whenever required, however once it is no longer needed any more, final cleanup should be performed by calling System.IDisposable.Dispose which will disconnect it and also ensure that any background threads started by the client have been terminated.

Thread-safety:

This class has locking so that concurrent use by multiple threads is safe.

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

Note that the deprecated "simple receiver" feature (IMessagingClient.IsReceiveEnabled) was removed in the 5.1 release; the named consumer interface should now be used instead.