EngineClientBean (Apama API Documentation)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.apama.engine.beans
Class EngineClientBean

java.lang.Object
  com.apama.engine.beans.EngineClientBean

All Implemented Interfaces:: ConnectOperationsInterface, DeleteOperationsInterface, EngineClientInterface, InjectOperationsInterface, InspectOperationsInterface, ReceiveConsumerOperationsInterface, SendOperationsInterface, WatchOperationsInterface, BaseClientInterface, PingClientInterface, PingOperationsInterface

public class EngineClientBean
extends java.lang.Object
implements EngineClientInterface
extends java.lang.Object
implements EngineClientInterface

EngineClientBean is a JavaBean 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.

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, and are defined by ReceiveConsumerOperationsInterface.

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

Use EventType and its associated classes to parse and generate 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. setPort(int), setHost(String)), a connection can be established either synchronously using connectNow() (which throws an exception on error) or asynchronously using connectInBackground() (which automatically retries until a connection is established - see setConnectionPollingInterval(int) and setReconnectPeriod(long)).

Once the bean connected successfully, a background thread will keep pinging it to ensure the connection is still up (see setConnectionPollingInterval(int)). If the entire bean connection is lost, the BaseClientInterface.PROPERTY_BEAN_CONNECTED and ReceiveConsumerOperationsInterface.PROPERTY_ALL_CONSUMERS_CONNECTED 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 setConnectionPollingInterval(int)). 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 IEventService instead). To prevent reconnecting slow consumers too soon after disconnection, a minimum time between reconnection attempts can be configured using setReconnectPeriod(long).

The engine client can be disconnected using disconnect() whenever required, however once it is no longer needed any more, final cleanup should be performed by calling 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 synchronization problems, clients should not synchronize on the object nor call methods on the object within consumer callbacks. If they wish to do so, the consumer should be added as asynchronous (see addConsumer method). Please also avoid synchronously calling the engine client from within property change listeners, especially the ReceiveConsumerOperationsInterface.PROPERTY_ALL_CONSUMERS_CONNECTED property (the IEventService may be a better fit for applications that need to do this).

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

Field Summary

Fields inherited from interface com.apama.engine.beans.interfaces.EngineClientInterface
`DEFAULT_MONITOR_ONLY, DEFAULT_RECEIVE_ONLY, PROPERTY_MONITOR_ONLY, PROPERTY_RECEIVE_ONLY`

Fields inherited from interface com.apama.net.beans.interfaces.BaseClientInterface
`COPYRIGHT, DEFAULT_CONNECTION_POLLING_INTERVAL, DEFAULT_HOST, DEFAULT_PORT, DEFAULT_PROCESS_NAME, PRODUCTNAME, PROPERTY_BEAN_CONNECTED, PROPERTY_CONNECTION_POLLING_INTERVAL, PROPERTY_HOST, PROPERTY_PORT, PROPERTY_PROCESS_NAME, PROPERTY_VERBOSE, VERSION`

Fields inherited from interface com.apama.engine.beans.interfaces.InspectOperationsInterface
`DEFAULT_INSPECT_POLLING_INTERVAL, PROPERTY_ENGINE_INFO, PROPERTY_INSPECT_POLLING_INTERVAL`

Fields inherited from interface com.apama.engine.beans.interfaces.WatchOperationsInterface
`DEFAULT_STATUS_POLLING_INTERVAL, PROPERTY_STATUS, PROPERTY_STATUS_POLLING_INTERVAL`

Fields inherited from interface com.apama.engine.beans.interfaces.ReceiveConsumerOperationsInterface
`PROPERTY_ALL_CONSUMERS_CONNECTED`

Constructor Summary
`EngineClientBean()` Default constructor - as required to be a bean.

Method Summary
`ConsumerOperationsInterface`	`addConsumer(java.lang.String uniqueName, java.lang.String... channels)` Add a new uniquely-named synchronous consumer that listens on a specified set of channels.
`ConsumerOperationsInterface`	`addConsumer(java.lang.String uniqueName, java.lang.String[] channels, boolean disconnectSlow)` Add a new uniquely-named consumer that listens on a specified set of channels.
`ConsumerOperationsInterface`	`addConsumer(java.lang.String uniqueName, java.lang.String[] channels, boolean disconnectSlow, boolean async)` Add a new uniquely-named consumer that listens on a specified set of channels.
`void`	`addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Add a property change listener (without blocking concurrent calls to operations on this bean instance).
`void`	`addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)` Add a property change listener for a specific named property (without blocking concurrent calls to operations on this bean instance).
`void`	`attachAsConsumerOfEngine(EngineClientBean sourceEngineBean, java.lang.String[] channels)` Connect this engine to another (non-persisently) so that it receives events emitted on the specified channels.
`void`	`attachAsConsumerOfEngine(java.lang.String sourceHost, int sourcePort, java.lang.String[] channels)` Connect this engine to another (non-persistently) so that it receives events emitted on the specified channels.
`void`	`attachAsConsumerOfEngine(java.lang.String sourceHost, int sourcePort, java.lang.String[] channels, boolean persistent)` Connect this engine to another so that it receives events emitted on the specified channels.
`void`	`attachAsConsumerOfEngine(java.lang.String sourceHost, int sourcePort, java.lang.String[] channels, boolean persistent, boolean disconnectSlow)` Connect this engine to another so that it receives events emitted on the specified channels.
`void`	`connectInBackground()` Requests that the bean begins to establish a connection automatically in the background.
`void`	`connectNow()` Manually request that the bean connects to the remote server.
`void`	`deleteAll()` Deletes everything from the engine.
`void`	`deleteName(java.lang.String name, boolean force)` Delete a name from the engine.
`void`	`deleteNames(java.util.List<java.lang.String> names, boolean force)` Delete a number of names.
`void`	`deleteNamesFromFile(java.util.List<java.lang.String> filenames, boolean force)` Delete a number of names from a file or stdin.
`void`	`deleteNamesFromFile(java.util.List<java.lang.String> filenames, boolean force, boolean utf8)` Delete a number of names from a file or stdin.
`void`	`detachAsConsumerOfEngine(EngineClientBean sourceEngineBean, java.lang.String[] channels)` Disconnect this engine from another so that it not longer receives events emitted on the specified channels.
`void`	`detachAsConsumerOfEngine(java.lang.String sourceHost, int sourcePort, java.lang.String[] channels)` Disconnect this engine from another so that it not longer receives events emitted on the specified channels.
`void`	`detachAsConsumerOfEngine(java.lang.String sourceHost, int sourcePort, java.lang.String[] channels, boolean persistent)` Disconnect this engine from another so that it not longer receives events emitted on the specified channels.
`void`	`disconnect()` Sets the desired state of the bean to disconnected instead of connected, disconnects consumers and stops pinging the remote correlator to keep the connection alive.
`void`	`dispose()` Disconnects the client and also waits to ensure that all background threads and other resources associated with this object have been terminated or freed.
`void`	`flushEvents()` Wait for any outstanding events from previous `SendOperationsInterface.sendEvents(Event...)` or `SendOperationsInterface.sendEvents(boolean, Event...)` (where the boolean is true) calls into the Engine, and then return.
`ConsumerOperationsInterface[]`	`getAllConsumers()` Get all existing uniquely-named consumers.
`boolean`	`getBeanConnected()` Get the beanConnected property value.
`int`	`getConnectionPollingInterval()` Get the polling interval (in milliseconds) for the background connection and ping thread.
`ConsumerOperationsInterface`	`getConsumer(java.lang.String uniqueName)` Get an existing uniquely-named consumer.
`EngineInfo`	`getEngineInfo()` Get the most recently recorded inspection information.
`java.lang.String`	`getHost()` Get the name of the host to be connected to.
`int`	`getInspectPollingInterval()` Get the inspectPollingInterval (in milliseconds) that the background thread should wait between calls for new information.
`boolean`	`getMonitorOnly()` Getter for the monitorOnly property.
`int`	`getPort()` Get the port number to be connected to.
`java.lang.String`	`getProcessName()` Get the process Name in use This is the process name in use for this bean The process name is a display name to identify which application is responsible for this connection to the Correlator (this name is included in log files for diagnostic purposes)
`boolean`	`getReceiveOnly()` Getter for the receiveOnly property.
`EngineInfo`	`getRemoteEngineInfo()` Request the remote Engine inspection info.
`EngineStatus`	`getRemoteStatus()` Request the remote Engine status.
`EngineStatus`	`getStatus()` Get the most recently recorded status.
`int`	`getStatusPollingInterval()` Get the statusPollingInterval (in milliseconds) that the background thread should wait between calls for new status information.
`boolean`	`getVerbose()` Getter for the verbose property.
`java.lang.String[]`	`injectCDP(byte[] cdpBytes)` Send the bytes of a CDP (Correlator Deployment Package) to the engine without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectCDP(byte[] cdpBytes, java.lang.String filename)` Send the bytes of a CDP (Correlator Deployment Package) to the engine without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectCDPsFromFile(java.util.List<java.lang.String> filenames)` Inject a collection of CDPs read from files (or stdin), without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectJavaApplication(byte[] jarBytes)` Send the bytes of a JMon application jar to the engine without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectJavaApplicationsFromFile(java.util.List<java.lang.String> filenames)` Inject a collection of JMon application jars read from files (or stdin), without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectMonitorScript(MonitorScript script)` Send MonitorScript text to the engine without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectMonitorScript(MonitorScript script, java.lang.String filename)` Send a MonitorScript object to the engine.
`java.lang.String[]`	`injectMonitorScriptFromFile(java.util.List<java.lang.String> filenames)` Inject a collection of MonitorScript text read from files (or stdin), without blocking concurrent calls to operations on this bean instance.
`java.lang.String[]`	`injectMonitorScriptFromFile(java.util.List<java.lang.String> filenames, boolean utf8)` Inject a number of monitors from a file or stdin.
`java.lang.String[]`	`injectMonitorScriptFromFile(java.lang.String... filenames)` Inject a collection of MonitorScript text read from files (or stdin), without blocking concurrent calls to operations on this bean instance.
`boolean`	`isAllConsumersConnected()` Determine if the bean and existing uniquely-named consumers are connected.
`boolean`	`isBeanConnected()` Another name for the getBeanConnected() method.
`boolean`	`isMonitorOnly()` Another name for getMonitorOnly()
`boolean`	`isReceiveOnly()` Another name for getReceiveOnly()
`void`	`killName(java.lang.String name)` Kill a name from the engine.
`void`	`killNames(java.util.List<java.lang.String> names)` Kill a number of names.
`void`	`killNamesFromFile(java.util.List<java.lang.String> filenames)` Kill a number of names from a file or stdin.
`void`	`killNamesFromFile(java.util.List<java.lang.String> filenames, boolean utf8)` Kill a number of names from a file or stdin.
`void`	`pingServer()` Manually test if the remote engine process is alive and responding to client requests.
`void`	`removeAllConsumers()` Disconnect, Destroy, and Remove all existing consumers.
`void`	`removeConsumer(java.lang.String uniqueName)` Remove and disconnect an existing uniquely-named consumer.
`void`	`removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Remove a property change listener (without blocking concurrent calls to operations on this bean instance).
`void`	`removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)` Remove a property change listener for a specific named property (without blocking concurrent calls to operations on this bean instance).
`void`	`sendEvents(boolean autoBatch, Event... events)` Send events into the Engine, optionally not performing auto-batching.
`void`	`sendEvents(Event... events)` Send an array of Event objects to the engine (automatically rebatching the actual event sending for efficiency).
`void`	`sendEventsFromFile(java.util.List<java.lang.String> filenames, int loop)` Send a number of events from a file or stdin.
`void`	`sendEventsFromFile(java.util.List<java.lang.String> filenames, int loop, boolean utf8)` Send a number of events from a file or stdin.
`void`	`sendEventsFromFile(java.util.List<java.lang.String> filenames, int loop, boolean utf8, boolean 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.
`void`	`setCancelDeleteFileRead(boolean newCancelFileReadValue)` Setter for the cancelFileRead property for the Delete / Kill operations.
`void`	`setCancelInjectFileRead(boolean newCancelFileReadValue)` Setter for the cancelFileRead property for the Inject operations.
`void`	`setCancelSendFileRead(boolean newCancelFileReadValue)` Setter for the cancelFileRead property for the Send operations.
`void`	`setConnectionPollingInterval(int milliseconds)` Set the polling interval (in milliseconds) for the background connection and ping thread.
`void`	`setHost(java.lang.String newHostValue)` Setter for the host property.
`void`	`setInspectPollingInterval(int newInspectPollingInterval)` Set the inspectPollingInterval (in milliseconds) that the background thread should wait between calls for new information.
`void`	`setMonitorOnly(boolean newMonitorOnlyValue)` Setter for the monitorOnly property.
`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).
`void`	`setPort(int newPortValue)` Setter for the port property.
`void`	`setProcessName(java.lang.String newProcessName)` Setter for the process Name This is the process name property to use.
`void`	`setReceiveOnly(boolean newReceiveOnlyValue)` Setter for the receiveOnly property.
`void`	`setReconnectPeriod(long t)` Set the minimum period between attempts to reconnect the bean and/or any of the bean's named consumers that have been disconnected (e.g.
`void`	`setReconnectPolicy(ReconnectPolicyInterface p)` Set a singleton reconnection policy that will be used to limit when reconnection can be attempted for the bean, and/or any of the bean's named consumers that have been disconnected (e.g.
`void`	`setStatusPollingInterval(int newStatusPollingInterval)` Set the statusPollingInterval (in milliseconds) that the background thread should wait between calls for new status information.
`void`	`setVerbose(boolean newVerboseValue)` Setter for the verbose property.
`void`	`startInspectPollingThread()` Start the local inspect polling thread.
`void`	`startStatusPollingThread()` Start the local status polling thread.
`void`	`stopInspectPollingThread()` Stop the local inspect polling thread.
`void`	`stopStatusPollingThread()` Stop the local status polling thread.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

EngineClientBean

public EngineClientBean()

Default constructor - as required to be a bean. Initialises the bean with default values for the properties. This default constructor does not make a connection to an Engine.

If a bean class is not required, we recommend using the EngineClientFactory and the associated interfaces instead.

Method Detail

connectNow

public void connectNow()
                throws com.apama.util.CompoundException

Manually request that the bean connects to the remote server. Repeated calls are permitted, and attempting to connect a bean that is already connected is identical to calling pingServer() from the PingOperationsInterface.

Specified by:: connectNow in interface BaseClientInterface

Throws:: com.apama.util.CompoundException - Thrown if any exceptions occur in the Client SDK.

connectInBackground

public void connectInBackground()

Requests that the bean begins to establish a connection automatically in the background.

Calling disconnect() will bring connection attempts to an end. Repeated calls to this method, or calling this method after a connection has already been established will have no effect.

Specified by:: connectInBackground in interface EngineClientInterface

pingServer

public void pingServer()
                throws com.apama.util.CompoundException

Manually test if the remote engine process is alive and responding to client requests. This method makes a no-arg, void return, method call on the client interface of the engine. 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 (which is a subclass of CompoundException) will be raised.

Specified by:: pingServer in interface PingOperationsInterface

Throws:: com.apama.util.CompoundException - when the ping fails.

getHost

public java.lang.String getHost()

Get the name of the host to be connected to. This is the name of the host on which the correlator to be monitored is running.

Specified by:: getHost in interface BaseClientInterface

Returns:: Name of the host where the correlator to be monitored is running.

setHost

public void setHost(java.lang.String newHostValue)
             throws EngineException

Setter for the host property. This is the name of the host on which the correlator to be monitored is running. Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created.

Specified by:: setHost in interface BaseClientInterface

Parameters:: newHostValue - The new value for the Host property.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

getPort

public int getPort()

Get the port number to be connected to. This is the port number on which the correlator to be monitored is listening.

Specified by:: getPort in interface BaseClientInterface

Returns:: Port number on which the correlator to be monitored is listening.

setPort

public void setPort(int newPortValue)
             throws EngineException

Setter for the port property. This is the port number on which the correlator to be monitored is listening. Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created.

Specified by:: setPort in interface BaseClientInterface

Parameters:: newPortValue - The new value for the Port property.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

getProcessName

public java.lang.String getProcessName()

Get the process Name in use This is the process name in use for this bean The process name is a display name to identify which application is responsible for this connection to the Correlator (this name is included in log files for diagnostic purposes)

Specified by:: getProcessName in interface BaseClientInterface

Returns:: Process name in use

setProcessName

public void setProcessName(java.lang.String newProcessName)
                    throws EngineException

Setter for the process Name This is the process name property to use. The process name is a display name to identify which application is responsible for this connection to the Correlator (this name is included in log files for diagnostic purposes) Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created.

Specified by:: setProcessName in interface BaseClientInterface

Parameters:: newProcessName - The new value for the process name property.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

getMonitorOnly

public boolean getMonitorOnly()

Getter for the monitorOnly property. A bean 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.

Returns:: The value for the monitorOnly property.

isMonitorOnly

public boolean isMonitorOnly()

Another name for getMonitorOnly()

Returns:: The value for the monitorOnly property.

setMonitorOnly

public void setMonitorOnly(boolean newMonitorOnlyValue)
                    throws EngineException

Setter for the monitorOnly property. A bean 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. Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created. Setting this property to true will reset the receiveOnly property to false.

Parameters:: newMonitorOnlyValue - The new value for the monitorOnly property.
Throws:: EngineException - If any exceptions occur in the Client SDK.

getReceiveOnly

public boolean getReceiveOnly()

Getter for the receiveOnly property. A bean running in "receive only" mode cannot perform any state-changing operations on the remote component, but it can receive events from it.

Returns:: The value for the receiveOnly property.

isReceiveOnly

public boolean isReceiveOnly()

Another name for getReceiveOnly()

Returns:: The value for the receiveOnly property.

setReceiveOnly

public void setReceiveOnly(boolean newReceiveOnlyValue)
                    throws EngineException

Setter for the receiveOnly property. A bean running in "receive only" mode cannot perform any state-changing operations on the remote component, but it can receive events from it. Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created. Setting this property to true will reset the monitorOnly property to false.

Parameters:: newReceiveOnlyValue - The new value for the receiveOnly property.
Throws:: EngineException - If any exceptions occur in the Client SDK.

isBeanConnected

public boolean isBeanConnected()

Another name for the getBeanConnected() method.

Specified by:: isBeanConnected in interface BaseClientInterface

Returns:: true if the bean has a connection to an engine, false if not.

getBeanConnected

public boolean getBeanConnected()

Get the beanConnected property value. This is the status of the bean - connected, or not connected. It indicates if the EngineClientBean has a valid instance of the EngineManagement interface.

Specified by:: getBeanConnected in interface BaseClientInterface

Returns:: true if the bean has a connection to an engine, false if not.

getConnectionPollingInterval

public int getConnectionPollingInterval()

Get the polling interval (in milliseconds) for the background connection and ping thread.

Specified by:: getConnectionPollingInterval in interface BaseClientInterface

Returns:: the current interval in milliseconds

setConnectionPollingInterval

public void setConnectionPollingInterval(int milliseconds)

Set the polling interval (in milliseconds) for the background connection and ping thread.

This controls how often the bean pings the engine, and updates the BaseClientInterface.PROPERTY_BEAN_CONNECTED property.

If connectInBackground() is used, if the bean lost its connection to the engine, or if any named consumers were disconnected (e.g. due to being slow), the polling interval also controls how often the bean attempts to automatically reconnect the bean and/or its registered consumers, subject to the minimum reconnect period specified by setReconnectPeriod(long).

Specified by:: setConnectionPollingInterval in interface BaseClientInterface

Parameters:: milliseconds - The polling interval in milliseconds. If negative, then the default value will be used instead.

getVerbose

public boolean getVerbose()

Getter for the verbose property. When verbose is set to true, some methods (in subclasses) will print progress messages on stdout.

Returns:: Current value of the verbose property.

setVerbose

public void setVerbose(boolean newVerboseValue)

Setter for the verbose property. When verbose is set to true, some methods (in subclasses) will print progress messages on stdout.

Parameters:: newVerboseValue - Set to true for more verbose status output.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a property change listener (without blocking concurrent calls to operations on this bean instance).

Specified by:: removePropertyChangeListener in interface BaseClientInterface

Parameters:: listener - the listener to be removed.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a property change listener (without blocking concurrent calls to operations on this bean instance). Use this method to be informed whenever the a property value is changed.

Specified by:: addPropertyChangeListener in interface BaseClientInterface

Parameters:: listener - the listener to be added.

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)

Remove a property change listener for a specific named property (without blocking concurrent calls to operations on this bean instance).

Specified by:: removePropertyChangeListener in interface BaseClientInterface

Parameters:: propertyName - the name of the property that was listened on.; listener - the listener to be removed.

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)

Add a property change listener for a specific named property (without blocking concurrent calls to operations on this bean instance).

Specified by:: addPropertyChangeListener in interface BaseClientInterface

Parameters:: propertyName - the name of the property to listen on.; listener - the listener to be added.

toString

public java.lang.String toString()

Overrides:: toString in class java.lang.Object

disconnect

public void disconnect()
                throws EngineException

Sets the desired state of the bean to disconnected instead of connected, disconnects consumers and stops pinging the remote correlator to keep the connection alive.

Specified by:: disconnect in interface BaseClientInterface

Throws:: EngineException - Thrown if any exceptions occur in the Client SDK, specifically during de-registration of the internal EventConsumer.

dispose

public void dispose()

Description copied from interface: BaseClientInterface

Disconnects the client and also waits to ensure that all background threads and other resources associated with this object have been terminated or freed. This method should always be called before quitting the program. Never call this method while the target object is locked, or from a thread that is receiving events or handling a property change notification event from the target object.

Specified by:: dispose in interface BaseClientInterface

setReconnectPolicy

public void setReconnectPolicy(ReconnectPolicyInterface p)

Description copied from interface: EngineClientInterface

Set a singleton reconnection policy that will be used to limit when reconnection can be attempted for the bean, and/or any of the bean's named consumers that have been disconnected (e.g. as a slow consumer).

In most cases, we recommend using EngineClientInterface.setReconnectPeriod(long) instead of writing a custom policy object.

Specified by:: setReconnectPolicy in interface EngineClientInterface

See Also:: ReconnectPolicyInterface

setReconnectPeriod

public void setReconnectPeriod(long t)

Description copied from interface: EngineClientInterface

Set the minimum period between attempts to reconnect the bean and/or any of the bean's named consumers that have been disconnected (e.g. as a slow consumer).

By default there is no minimum reconnection period defined, and if any consumers have been disconnected by the engine, the bean will attempt to reconnect them at least as often as the bean's connection polling interval.

Any previously set reconnect policy will be overwritten when this method is called.

Specified by:: setReconnectPeriod in interface EngineClientInterface

Parameters:: t - The minimum reconnection period in milliseconds, or 0 to place no limit on how often we can attempt to reconnect.
See Also:: EngineClientInterface.setReconnectPolicy(ReconnectPolicyInterface)

sendEventsFromFile

public void sendEventsFromFile(java.util.List<java.lang.String> filenames,
                               int loop)
                        throws EngineException

Description copied from interface: SendOperationsInterface

Send a number of events from a file or stdin.

If a connection is not yet established, this method will request a connection.

The current implementation of this method does not perform automatic batching of the events, but a future release may change this behaviour, so please use the overloaded SendOperationsInterface.sendEventsFromFile(List, int, boolean, boolean) method if you require control over this. Auto-batching will usually provide better throughput.

NOTE: Change in behaviour at Apama 3.0 - previously we ignored any missing files, now an exception is thrown.

Specified by:: sendEventsFromFile in interface SendOperationsInterface

Parameters:: filenames - Names of files to read event descriptions from. A file name "-" is taken to be stdin.; loop - Loop count for repeated reading of input data.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

sendEventsFromFile

public void sendEventsFromFile(java.util.List<java.lang.String> filenames,
                               int loop,
                               boolean utf8)
                        throws EngineException

Description copied from interface: SendOperationsInterface

Send a number of events from a file or stdin.

If a connection is not yet established, this method will request a connection.

NOTE: Change in behaviour at Apama 3.0 - previously we ignored any missing files, now an exception is thrown.

Specified by:: sendEventsFromFile in interface SendOperationsInterface

Parameters:: filenames - Names of files to read event descriptions from. A file name "-" is taken to be stdin.; loop - Loop count for repeated reading of input data.; utf8 - If true, the specified files will be read as UTF-8; otherwise they will be read using the system default encoding unless they begin with a unicode Byte Order Mark (BOM) character.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

sendEventsFromFile

public void sendEventsFromFile(java.util.List<java.lang.String> filenames,
                               int loop,
                               boolean utf8,
                               boolean autoBatch)
                        throws EngineException

Description copied from interface: SendOperationsInterface

Send a number of events from a file or stdin, specifying the file encoding detection mode and whether to auto-batch events or not.

If a connection is not yet established, this method will request a connection.

NOTE: Change in behaviour at Apama 3.0 - previously we ignored any missing files, now an exception is thrown.

Specified by:: sendEventsFromFile in interface SendOperationsInterface

Parameters:: filenames - Names of files to read event descriptions from. A file name "-" is taken to be stdin.; loop - Loop count for repeated reading of input data.; utf8 - If true, the specified files will be read as UTF-8; otherwise they will be read using the system default encoding unless they begin with a unicode Byte Order Mark (BOM) character.; autoBatch - If true, events will be automatically rebatched to improve throughput
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

sendEvents

public void sendEvents(boolean autoBatch,
                       Event... events)
                throws EngineException

Send events into the Engine, optionally not performing auto-batching. If a connection is not yet established, this method will request a connection.

Specified by:: sendEvents in interface SendOperationsInterface

Parameters:: autoBatch - If true, events will be automatically rebatched to improve throughput (across separate sendEvents calls); events - The array of Events to be sent.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.
See Also:: SendOperationsInterface.flushEvents()

sendEvents

public void sendEvents(Event... events)
                throws EngineException

Description copied from interface: SendOperationsInterface

Send an array of Event objects to the engine (automatically rebatching the actual event sending for efficiency). Please use the overloaded SendOperationsInterface.sendEvents(boolean, Event...) method if you require control over the rebatching. If a connection is not yet established, this method will request a connection.

Specified by:: sendEvents in interface SendOperationsInterface

Parameters:: events - An array with one or more Events to be sent.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.
See Also:: SendOperationsInterface.flushEvents()

flushEvents

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

Wait for any outstanding events from previous SendOperationsInterface.sendEvents(Event...) or SendOperationsInterface.sendEvents(boolean, Event...) (where the boolean is true) calls into the Engine, and then return.

Specified by:: flushEvents in interface SendOperationsInterface

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:: SendOperationsInterface.sendEvents(boolean, Event...)

setCancelSendFileRead

public void setCancelSendFileRead(boolean newCancelFileReadValue)

Setter for the cancelFileRead property for the Send operations. The purpose of the cancelFileRead property is to provide a mechanism to cleanly terminate the processing of events from file, when the sendEventsFromFile() method is in progress. When cancelFileRead is set to true, the event sending loop will terminate at the next iteration.

Specified by:: setCancelSendFileRead in interface SendOperationsInterface

Parameters:: newCancelFileReadValue - New value for the cancelFileRead property.

deleteNames

public void deleteNames(java.util.List<java.lang.String> names,
                        boolean force)
                 throws EngineException

Delete a number of names. If a connection is not yet established, this method will request a connection.

Specified by:: deleteNames in interface DeleteOperationsInterface

Parameters:: names - Names to be deleted.; force - Set to true to forcably delete the names even if in use.
Throws:: EngineException

deleteNamesFromFile

public void deleteNamesFromFile(java.util.List<java.lang.String> filenames,
                                boolean force)
                         throws EngineException

Delete a number of names from a file or stdin. If a connection is not yet established, this method will request a connection.

Specified by:: deleteNamesFromFile in interface DeleteOperationsInterface

Parameters:: filenames - Names of files to read Names from. A file name "-" is taken to be stdin.; force - Set to true to forcably delete the names even if in use.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

deleteNamesFromFile

public void deleteNamesFromFile(java.util.List<java.lang.String> filenames,
                                boolean force,
                                boolean utf8)
                         throws EngineException

Description copied from interface: DeleteOperationsInterface

Delete a number of names from a file or stdin. If a connection is not yet established, this method will request a connection.

Specified by:: deleteNamesFromFile in interface DeleteOperationsInterface

Parameters:: filenames - Names of files to read Names from. A file name "-" is taken to be stdin.; force - Set to true to forcably delete the names even if in use.; utf8 - If true, the specified files will be read as UTF-8; otherwise they will be read using the system default encoding unless they begin with a unicode Byte Order Mark (BOM) character.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

deleteAll

public void deleteAll()
               throws EngineException

Deletes everything from the engine.

Specified by:: deleteAll in interface DeleteOperationsInterface

Throws:: EngineException

deleteName

public void deleteName(java.lang.String name,
                       boolean force)
                throws EngineException

Delete a name from the engine. If a connection is not yet established, this method will request a connection.

Specified by:: deleteName in interface DeleteOperationsInterface

Parameters:: name - The name to be deleted.; force - Set to true to forcably delete the name even if in use.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

killNames

public void killNames(java.util.List<java.lang.String> names)
               throws EngineException

Kill a number of names. 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.

Specified by:: killNames in interface DeleteOperationsInterface

Parameters:: names - Names to be deleted.
Throws:: EngineException

killNamesFromFile

public void killNamesFromFile(java.util.List<java.lang.String> filenames)
                       throws EngineException

Kill a number of names 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.

Specified by:: killNamesFromFile in interface DeleteOperationsInterface

Parameters:: filenames - Names of files to read Names from. A file name "-" is taken to be stdin.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

killNamesFromFile

public void killNamesFromFile(java.util.List<java.lang.String> filenames,
                              boolean utf8)
                       throws EngineException

Description copied from interface: DeleteOperationsInterface

Specified by:: killNamesFromFile in interface DeleteOperationsInterface

Parameters:: filenames - Names of files to read Names from. A file name "-" is taken to be stdin.; utf8 - If true, the specified files will be read as UTF-8; otherwise they will be read using the system default encoding unless they begin with a unicode Byte Order Mark (BOM) character.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

killName

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

Kill a name 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.

Specified by:: killName in interface DeleteOperationsInterface

Parameters:: name - The name to be deleted.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

setCancelDeleteFileRead

public void setCancelDeleteFileRead(boolean newCancelFileReadValue)

Setter for the cancelFileRead property for the Delete / 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.

Specified by:: setCancelDeleteFileRead in interface DeleteOperationsInterface

Parameters:: newCancelFileReadValue - New value for the cancelFileRead property.

injectMonitorScriptFromFile

public java.lang.String[] injectMonitorScriptFromFile(java.lang.String... filenames)
                                               throws EngineException

Inject a collection of MonitorScript text read from files (or stdin), without blocking concurrent calls to operations on this bean instance. If a connection to the engine is not yet established, this method will attempt to make a connection.

Specified by:: injectMonitorScriptFromFile in interface InjectOperationsInterface

Parameters:: filenames - Names of files containing MonitorScript text to be injected. Standard input is represented by a filename "-". This special filename should only occur no more than once in the filename list.
Returns:: An array of warnings (may be zero length)
Throws:: EngineException - If any of the named files cannot be injected, either because the file could not be read or because a call to injectMonitorScriptUnlocked() failed.

injectMonitorScriptFromFile

public java.lang.String[] injectMonitorScriptFromFile(java.util.List<java.lang.String> filenames)
                                               throws EngineException

Specified by:: injectMonitorScriptFromFile in interface InjectOperationsInterface

Parameters:: filenames - Names of files containing MonitorScript text to be injected. Standard input is represented by a filename "-". This special filename should only occur once in the filename vector.
Returns:: An array of warnings (may be zero length)
Throws:: EngineException - If any of the named files cannot be injected, either because the file could not be read or because a call to injectMonitorScriptUnlocked() failed.

injectMonitorScriptFromFile

public java.lang.String[] injectMonitorScriptFromFile(java.util.List<java.lang.String> filenames,
                                                      boolean utf8)
                                               throws EngineException

Description copied from interface: InjectOperationsInterface

Inject a number of monitors from a file or stdin. If a connection is not yet established, this method will request a connection.

Specified by:: injectMonitorScriptFromFile in interface InjectOperationsInterface

Parameters:: filenames - Names of files to read MonitorScript text from. A file name "-" is taken to be stdin.; utf8 - If true, the specified files will be read as UTF-8; otherwise they will be read using the system default encoding unless they begin with a unicode Byte Order Mark (BOM) character.
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.

injectMonitorScript

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

Send MonitorScript text to the engine without blocking concurrent calls to operations on this bean instance. If a connection to the engine is not yet established, this method will attempt to make a connection.

Specified by:: injectMonitorScript in interface InjectOperationsInterface

Parameters:: script - The MonitorScript object to be injected into the engine.
Returns:: An array of warnings (may be zero length).
Throws:: EngineException - If the MonitorScript is rejected by the engine, or there is a problem sending the script.

injectMonitorScript

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

Description copied from interface: InjectOperationsInterface

Send a MonitorScript object to the engine. If a connection is not yet established, this method will request a connection.

Specified by:: injectMonitorScript in interface InjectOperationsInterface

Parameters:: script - The MonitorScript object to be sent.; filename - The file the monitorscript came from (may be null)
Returns:: An array of strings which are the set of warnings generated by the MonitorScript compiler. May be zero length.
Throws:: EngineException - When failures happen. This exception may contain warnings.

injectJavaApplicationsFromFile

public java.lang.String[] injectJavaApplicationsFromFile(java.util.List<java.lang.String> filenames)
                                                  throws EngineException

Inject a collection of JMon application jars read from files (or stdin), without blocking concurrent calls to operations on this bean instance. If a connection to the engine is not yet established, this method will attempt to make a connection.

Specified by:: injectJavaApplicationsFromFile in interface InjectOperationsInterface

Parameters:: filenames - Names of files containing JMon applications to be injected. Standard input is represented by a filename "-". This special filename should only occur once in the filename vector.
Returns:: An array of warnings
Throws:: EngineException - If any of the named files cannot be injected, either because the file could not be read or because a call to injectJavaApplicationUnlocked() failed.

injectJavaApplication

public java.lang.String[] injectJavaApplication(byte[] jarBytes)
                                         throws EngineException

Send the bytes of a JMon application jar to the engine without blocking concurrent calls to operations on this bean instance. If a connection to the engine is not yet established, this method will attempt to make a connection.

Specified by:: injectJavaApplication in interface InjectOperationsInterface

Parameters:: jarBytes - The contents of the JMon jar to be sent to the engine.
Returns:: An array of strings which are the set of warnings about the JMon application. May be zero length.
Throws:: EngineException - If the JMon application is rejected by the engine, or there is a problem sending the data.

injectCDPsFromFile

public java.lang.String[] injectCDPsFromFile(java.util.List<java.lang.String> filenames)
                                      throws EngineException

Inject a collection of CDPs read from files (or stdin), without blocking concurrent calls to operations on this bean instance. If a connection to the engine is not yet established, this method will attempt to make a connection.

Specified by:: injectCDPsFromFile in interface InjectOperationsInterface

Parameters:: filenames - Names of files containing CDP files to be injected. Standard input is represented by a filename "-". This special filename should only occur once in the filename vector.
Returns:: An array of warnings
Throws:: EngineException - If any of the named files cannot be injected, either because the file could not be read or because a call to injectJavaApplicationUnlocked() failed.

injectCDP

public java.lang.String[] injectCDP(byte[] cdpBytes)
                             throws EngineException

Send the bytes of a CDP (Correlator Deployment Package) to the engine without blocking concurrent calls to operations on this bean instance. If a connection to the engine is not yet established, this method will attempt to make a connection.

Parameters:: cdpBytes - The contents of the CDP file to be sent to the engine.
Returns:: An array of warnings (may be zero length).
Throws:: EngineException - If the CDP file is rejected by the engine, or there is a problem sending the data.

injectCDP

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

Specified by:: injectCDP in interface InjectOperationsInterface

Parameters:: cdpBytes - The contents of the CDP file to be sent to the engine.; filename - The name of the file we are injecting from.
Returns:: An array of strings which are the set of warnings about the CDP. May be zero length.
Throws:: EngineException - If the CDP file is rejected by the engine, or there is a problem sending the data.

setCancelInjectFileRead

public void setCancelInjectFileRead(boolean newCancelFileReadValue)

Setter for the cancelFileRead property for the Inject operations. The purpose of the cancelFileRead property is to provide a mechanism to cleanly terminate the processing of MonitorScripts from file, when the injectMonitorScriptFromFile() method is in progress. When cancelFileRead is set to true, the MonitorScript injecting loop will terminate at the next iteration.

Specified by:: setCancelInjectFileRead in interface InjectOperationsInterface

Parameters:: newCancelFileReadValue - New value for the cancelFileRead property.

startInspectPollingThread

public void startInspectPollingThread()
                               throws EngineException

Start the local inspect polling thread. If a connection is not yet established, this method will request a connection.

Specified by:: startInspectPollingThread in interface InspectOperationsInterface

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

stopInspectPollingThread

public void stopInspectPollingThread()

Stop the local inspect polling thread.

Specified by:: stopInspectPollingThread in interface InspectOperationsInterface

getRemoteEngineInfo

public EngineInfo getRemoteEngineInfo()
                               throws EngineException

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.

Specified by:: getRemoteEngineInfo in interface InspectOperationsInterface

Returns:: the information found as obtained by directly inspecting the Engine.
Throws:: EngineException - Thrown if any exceptions occur in the Client SDK.

setInspectPollingInterval

public void setInspectPollingInterval(int newInspectPollingInterval)

Set the inspectPollingInterval (in milliseconds) that the background thread should wait between calls for new information.

Specified by:: setInspectPollingInterval in interface InspectOperationsInterface

Parameters:: newInspectPollingInterval - Polling interval in milliseconds.

getInspectPollingInterval

public int getInspectPollingInterval()

Get the inspectPollingInterval (in milliseconds) that the background thread should wait between calls for new information.

Specified by:: getInspectPollingInterval in interface InspectOperationsInterface

Returns:: Polling interval in milliseconds.