Apama API Reference for .NET
9.10.0.4
|
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... | |
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.