Package com.apama.engine.beans

Class EngineClientBean

  • All Implemented Interfaces:
    ConnectOperationsInterface, DeleteOperationsInterface, EngineClientInterface, InjectOperationsInterface, InspectOperationsInterface, ReceiveConsumerOperationsInterface, SendOperationsInterface, WatchOperationsInterface, BaseClientInterface, PingClientInterface, PingOperationsInterface, java.lang.AutoCloseable
    public class EngineClientBean
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 close() 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 bean receiver" (and ReceiveOperationsInterface) feature was removed in the 5.1 release; the named consumer interface should now be used instead.

    • 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

      • 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 EngineException
        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 EngineClientInterface
        Specified by:
        pingServer in interface PingOperationsInterface
        Throws:
        EngineException - 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
        Specified by:
        setHost in interface EngineClientInterface
        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
        Specified by:
        setPort in interface EngineClientInterface
        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
        Specified by:
        setProcessName in interface EngineClientInterface
        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.

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Description copied from interface: EngineClientInterface
        Add a property change listener. Use this method to be informed whenever a property value is changed. Since Apama 5.2, listeners registered with this method will be called back asynchronously on a dedicated thread, which means it is permissible to call any engine client method from the listener - though be aware that the property value could have changed since the property change notification was fired, so may be different to the specified 'new value'. Applications that need the previous synchronous notification behaviour can use addPropertyChangeListenerSync to help with migration.
        Specified by:
        addPropertyChangeListener in interface BaseClientInterface
        Specified by:
        addPropertyChangeListener in interface EngineClientInterface
        Parameters:
        listener - the listener to be added.

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)
        Description copied from interface: EngineClientInterface
        Add a property change listener for a specific named property. Since Apama 5.2, listeners registered with this method will be called back asynchronously on a dedicated thread, which means it is permissible to call any engine client method from the listener - though be aware that the property value could have changed since the property change notification was fired, so may be different to the specified 'new value'. Applications that need the previous synchronous notification behaviour can use addPropertyChangeListenerSync to help with migration.
        Specified by:
        addPropertyChangeListener in interface BaseClientInterface
        Specified by:
        addPropertyChangeListener in interface EngineClientInterface
        Parameters:
        propertyName - the name of the property to listen on.
        listener - the listener to be added.

      • addPropertyChangeListenerSync

        public void addPropertyChangeListenerSync​(java.beans.PropertyChangeListener listener)
        Description copied from interface: EngineClientInterface
        Add a property change listener (with synchronous notifications). This method is deprecated and applications should use addPropertyChangeListener instead wherever possible, however this method is provided to simplify migration from pre-5.2 Apama releases which provided synchronous listener behaviour by default. To avoid the possibility of deadlock, it is essential that listeners registered using this method do not attempt to make calls back into the engine client (or any other service that uses it).
        Specified by:
        addPropertyChangeListenerSync in interface EngineClientInterface
        Parameters:
        listener - the listener to be added.

      • removePropertyChangeListenerSync

        public void removePropertyChangeListenerSync​(java.beans.PropertyChangeListener listener)
        Description copied from interface: EngineClientInterface
        Remove a property change listener registered with addPropertyChangeListenerSync.
        Specified by:
        removePropertyChangeListenerSync in interface EngineClientInterface
        Parameters:
        listener - the listener to be removed.

      • addPropertyChangeListenerSync

        public void addPropertyChangeListenerSync​(java.lang.String propertyName,
                                          java.beans.PropertyChangeListener listener)
        Description copied from interface: EngineClientInterface
        Add a property change listener for a specific named property. This method is deprecated and applications should use addPropertyChangeListener instead wherever possible, however this method is provided to simplify migration from pre-5.2 Apama releases which provided synchronous listener behaviour by default. To avoid the possibility of deadlock, it is essential that listeners registered using this method do not attempt to make calls back into the engine client (or any other service that uses it).
        Specified by:
        addPropertyChangeListenerSync in interface EngineClientInterface
        Parameters:
        propertyName - the name of the property to listen on.
        listener - the listener to be added.

      • removePropertyChangeListenerSync

        public void removePropertyChangeListenerSync​(java.lang.String propertyName,
                                             java.beans.PropertyChangeListener listener)
        Description copied from interface: EngineClientInterface
        Remove a property change listener for a specific named property registered with addPropertyChangeListenerSync.
        Specified by:
        removePropertyChangeListenerSync in interface EngineClientInterface
        Parameters:
        propertyName - the name of the property that was listened on.
        listener - the listener to be removed.

      • flushListeners

        public void flushListeners()
        Description copied from interface: EngineClientInterface
        Utility method that blocks until all pending property change listeners that have already fired have finished executing. Mostly useful for testing.
        Specified by:
        flushListeners in interface EngineClientInterface

      • 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
        Specified by:
        disconnect in interface EngineClientInterface
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK, specifically during de-registration of the internal EventConsumer.

      • close

        public void close()
        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.

        This method is invoked automatically on objects managed by the try-with-resources statement.

        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface BaseClientInterface
        See Also:
        AutoCloseable.close()

      • dispose

        @Deprecated
public void dispose()
        Deprecated.
        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

      • 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.

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

      • sendEventsFromFile

        public void sendEventsFromFile​(java.util.List<java.lang.String> filenames,
                               int loop,
                               boolean utf8,
                               boolean autoBatch,
                               java.lang.String defaultChannel)
                        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
        defaultChannel - Channel to use for events which aren't specified in the input file
        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()

      • 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.

      • 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 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.
        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 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.
        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
        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.
        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 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.
        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
        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 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 for another reason.

      • 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 for another reason.

      • 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
        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.
        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.

      • 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.

      • attachAsConsumerOfEngine

        public void attachAsConsumerOfEngine​(EngineClientBean sourceEngineBean,
                                     java.lang.String[] channels)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        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.

        Note: If you do not already have a connected EngineClientBean instance for the source engine, it is usually more efficient to call the overloaded ConnectOperationsInterface#attachAsConsumerOfEngine(String, int, String[]) method which takes a source host and port instead.
        Specified by:
        attachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceEngineBean - The EngineClientBean instance for the engine to receive from.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        Throws:
        EngineException - if the engines cannot be connected, or if the channels parameter is invalid.

      • attachAsConsumerOfEngine

        public void attachAsConsumerOfEngine​(java.lang.String sourceHost,
                                     int sourcePort,
                                     java.lang.String[] channels)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        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.
        Specified by:
        attachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceHost - The host of the engine to receive from.
        sourcePort - The port of the engine to receive from.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        Throws:
        EngineException - if the engines cannot be connected, or if the channels parameter is invalid.

      • attachAsConsumerOfEngine

        public void attachAsConsumerOfEngine​(java.lang.String sourceHost,
                                     int sourcePort,
                                     java.lang.String[] channels,
                                     boolean disconnectSlow)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        Connect this engine to another so that it receives events emitted on the specified channels. This is equivalent to the engine_connect command.
        Specified by:
        attachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceHost - The host of the engine to receive from.
        sourcePort - The port of the engine to receive from.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first connection's disconnectSlow value is used; subsequent connections to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.
        Throws:
        EngineException - if the engines cannot be connected, or if the channels parameter is invalid.

      • attachAsConsumerOfEngine

        public void attachAsConsumerOfEngine​(java.lang.String sourceHost,
                                     int sourcePort,
                                     java.lang.String[] channels,
                                     boolean disconnectSlow,
                                     ConnectMode mode)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        Connect this engine to another so that it receives events emitted on the specified channels. This is equivalent to the engine_connect command.
        Specified by:
        attachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceHost - The host of the engine to receive from.
        sourcePort - The port of the engine to receive from.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first connection's disconnectSlow value is used; subsequent connections to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.
        mode - the connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to PARALLEL for connection per channel and channel values passed through.
        Throws:
        EngineException - if the engines cannot be connected, or if the channels parameter is invalid.

      • detachAsConsumerOfEngine

        public void detachAsConsumerOfEngine​(EngineClientBean sourceEngineBean,
                                     java.lang.String[] channels)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the engine_connect --disconnect command, and assumes the connection is non-persistent.
        Specified by:
        detachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceEngineBean - The EngineClientBean instance for the engine this object is currently connected to as a consumer.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        Throws:
        EngineException - if the engines cannot be disconnected, or if the channels parameter is invalid.

      • detachAsConsumerOfEngine

        public void detachAsConsumerOfEngine​(EngineClientBean sourceEngineBean,
                                     java.lang.String[] channels,
                                     ConnectMode mode)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the engine_connect --disconnect command, and assumes the connection is non-persistent.
        Specified by:
        detachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceEngineBean - The EngineClientBean instance for the engine this object is currently connected to as a consumer.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        mode - the connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to PARALLEL for connection per channel and channel values passed through.
        Throws:
        EngineException - if the engines cannot be disconnected, or if the channels parameter is invalid.

      • detachAsConsumerOfEngine

        public void detachAsConsumerOfEngine​(java.lang.String sourceHost,
                                     int sourcePort,
                                     java.lang.String[] channels)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the engine_connect --disconnect command, and assumes the connection is non-persistent.
        Specified by:
        detachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceHost - The host of the engine this object is currently connected to as a consumer.
        sourcePort - The port of the engine this object is currently connected to as a consumer.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        Throws:
        EngineException - if the engines cannot be disconnected, or if the channels parameter is invalid.

      • detachAsConsumerOfEngine

        public void detachAsConsumerOfEngine​(java.lang.String sourceHost,
                                     int sourcePort,
                                     java.lang.String[] channels,
                                     ConnectMode mode)
                              throws EngineException
        Description copied from interface: ConnectOperationsInterface
        Disconnect this engine from another so that it not longer receives events emitted on the specified channels. This is equivalent to the engine_connect --disconnect command, and assumes the connection is non-persistent.
        Specified by:
        detachAsConsumerOfEngine in interface ConnectOperationsInterface
        Parameters:
        sourceHost - The host of the engine this object is currently connected to as a consumer.
        sourcePort - The port of the engine this object is currently connected to as a consumer.
        channels - the list of channels from which the engine should receive events. Must be non-null, and contain no null elements.
        mode - the connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to PARALLEL for connection per channel and channel values passed through.
        Throws:
        EngineException - if the engines cannot be disconnected, or if the channels parameter is invalid.

      • setPersistentReceiveConnections

        @Deprecated
public void setPersistentReceiveConnections​(EngineConnection... connections)
                                     throws EngineException
        Deprecated.
        use setReceiverConnections(EngineConnection... ) instead
        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).
        Specified by:
        setPersistentReceiveConnections in interface ConnectOperationsInterface
        Parameters:
        connections - Must not contain null elements.
        Throws:
        EngineException - If the change in the persistent connection set failed. Note that no exception is thrown if some of the specified connections could not be established immediately - in this case the receiver will simply keep trying to reconnect in the background.

      • setReceiverConnections

        public void setReceiverConnections​(EngineConnection... connections)
                            throws EngineException
        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).
        Specified by:
        setReceiverConnections in interface ConnectOperationsInterface
        Parameters:
        connections - Must not contain null elements.
        Throws:
        EngineException - If the change in the persistent connection set failed. Note that no exception is thrown if some of the specified connections could not be established immediately - in this case the receiver will simply keep trying to reconnect in the background.

      • getEngineInfo

        public 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.
        Specified by:
        getEngineInfo in interface InspectOperationsInterface
        Returns:
        the most recently recorded EngineInfo object. To be informed whenever the information changes, register a property change listener.

      • getRemoteStatus

        public EngineStatus getRemoteStatus()
                             throws EngineException
        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.
        Specified by:
        getRemoteStatus in interface WatchOperationsInterface
        Returns:
        The status as obtained directly from an Engine.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • setStatusPollingInterval

        public void setStatusPollingInterval​(int newStatusPollingInterval)
        Set the statusPollingInterval (in milliseconds) that the background thread should wait between calls for new status information.
        Specified by:
        setStatusPollingInterval in interface WatchOperationsInterface
        Parameters:
        newStatusPollingInterval - Polling interval in milliseconds.

      • getStatusPollingInterval

        public int getStatusPollingInterval()
        Get the statusPollingInterval (in milliseconds) that the background thread should wait between calls for new status information.
        Specified by:
        getStatusPollingInterval in interface WatchOperationsInterface
        Returns:
        Polling interval in milliseconds.

      • getStatus

        public EngineStatus getStatus()
        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.
        Specified by:
        getStatus in interface WatchOperationsInterface
        Returns:
        the most recently status object. To be informed whenever the status changes, register a property change listener.

      • addConsumer

        public ConsumerOperationsInterface addConsumer​(java.lang.String uniqueName,
                                               java.lang.String... channels)
                                        throws EngineException
        Add a new uniquely-named synchronous consumer that listens on a specified set of channels. The consumer will default to being synchronous (i.e. the event listener MUST not call ANY methods on the EngineClientBean, for example sendEvents()). The consumer will disconnect if it is slow, if disconnectSlowReceiver was set to true while creating the EngineClient instance using EngineClientFactory.createEngineClient(String, int, String, boolean)
        Specified by:
        addConsumer in interface ReceiveConsumerOperationsInterface
        Parameters:
        uniqueName - the unique name for the new consumer.
        channels - the list of channels on which the consumer should receive events.
        Returns:
        the new consumer.
        Throws:
        EngineException - if the consumer cannot be added (e.g. if the name is not unique)

      • addAsyncConsumer

        public ConsumerOperationsInterface addAsyncConsumer​(java.lang.String uniqueName,
                                                    java.lang.String... channels)
                                             throws EngineException
        Add a new uniquely-named asynchronous consumer that listens on a specified set of channels. The consumer will be asynchronous (i.e. disconnect() doesn't wait for the consumer. Also the event listener can call any methods on the EngineClientBean, for example sendEvents()). The consumer will disconnect if it is slow, if disconnectSlowReceiver was set to true while creating the EngineClient instance using EngineClientFactory.createEngineClient(String, int, String, boolean)
        Specified by:
        addAsyncConsumer in interface ReceiveConsumerOperationsInterface
        Parameters:
        uniqueName - the unique name for the new consumer.
        channels - the list of channels on which the consumer should receive events.
        Returns:
        the new consumer.
        Throws:
        EngineException - if the consumer cannot be added (e.g. if the name is not unique)

      • getConsumer

        public ConsumerOperationsInterface getConsumer​(java.lang.String uniqueName)
        Get an existing uniquely-named consumer.
        Specified by:
        getConsumer in interface ReceiveConsumerOperationsInterface
        Parameters:
        uniqueName - the unique-name of an existing consumer.
        Returns:
        the existing consumer, or null if one cannot be found with the specified name.

      • isAllConsumersConnected

        public boolean isAllConsumersConnected()
        Description copied from interface: ReceiveConsumerOperationsInterface
        Determine if the bean and existing uniquely-named consumers are connected.

        This is a bound property, so clients may also listen for property changes to ReceiveConsumerOperationsInterface.PROPERTY_ALL_CONSUMERS_CONNECTED. If no named consumers have been added, this property is identical to isBeanConnected.

        The method name may sound odd, but "is" is the accepted method-name prefix for testing boolean properties.

        Specified by:
        isAllConsumersConnected in interface ReceiveConsumerOperationsInterface
        Returns:
        true if the bean and all the named consumers are connected, false otherwise.

      • removeConsumer

        public void removeConsumer​(java.lang.String uniqueName)
                    throws EngineException
        Remove and disconnect an existing uniquely-named consumer. If the 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.
        Specified by:
        removeConsumer in interface ReceiveConsumerOperationsInterface
        Parameters:
        uniqueName - the unique-name of an existing consumer.
        Throws:
        EngineException - if there are problems with removing the consumer.

      • removeAllConsumers

        public void removeAllConsumers()
                        throws EngineException
        Disconnect, Destroy, and Remove all existing consumers. (Assumes a valid connection when doing disconnection logic) If the 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.
        Specified by:
        removeAllConsumers in interface ReceiveConsumerOperationsInterface
        Throws:
        EngineException - if there are problems while removing any of the consumers.