Package com.apama.engine

Interface EngineManagement

  • All Superinterfaces:
    java.lang.AutoCloseable, EventConsumer
    public interface EngineManagement
extends EventConsumer, java.lang.AutoCloseable
    The EngineManagement interface is the primary low-level interface to the Engine, and allows operations to be carried out on it.

    The static methods of the EngineManagementFactory class are used to create an object implementing this interface.

    Note that for most applications it is recommended to use the higher-level interfaces provided by EngineClientBean or IEventService instead of the low-level EngineManagement interface.

    Because an EngineManagement object is also an EventConsumer, it can have events sent to it (and to the Engine) through its sendEvents() method.

    • Method Detail

      • close

        void close()
        Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement.

        The implementation of this method should perform the same task as disconnect(), thus making it unnecessary to call both close() and disconnect().

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

      • injectMonitorScript

        java.lang.String[] injectMonitorScript​(MonitorScript script)
                                throws EngineException
        Inject MonitorScript text into the Engine.
        Parameters:
        script - MonitorScript text to be injected.
        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.
        InterruptedEngineException - If the calling thread is interrupted

      • injectMonitorScript

        java.lang.String[] injectMonitorScript​(MonitorScript script,
                                       java.lang.String filename)
                                throws EngineException
        Inject MonitorScript text into the Engine.
        Parameters:
        script - MonitorScript text to be injected.
        filename - Filename that the monitorscript came from (or null)
        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.
        InterruptedEngineException - If the calling thread is interrupted

      • deleteName

        void deleteName​(java.lang.String name)
         throws EngineException
        Delete a named object from the Engine.
        Parameters:
        name - The name of the object to be deleted.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.
        InterruptedEngineException - If the calling thread is interrupted

      • forceDeleteName

        void forceDeleteName​(java.lang.String name)
              throws EngineException
        Force deletion of a named object from the Engine.
        Parameters:
        name - The name of the object to be deleted.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • killName

        void killName​(java.lang.String name)
       throws EngineException
        Kill a named object in the Engine. Note that this will kill running monitors in such as way as to break the fault tolerance scheme.
        Parameters:
        name - The name of the object to be killed.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • injectJava

        java.lang.String[] injectJava​(byte[] jarbytes)
                       throws EngineException
        Injects a Java application (a jar) into the engine.
        Parameters:
        jarbytes - the bytes of the Java (Jmon) Application jar to be injected.
        Returns:
        An array of strings which are the set of warnings about the JMon application. May be zero length.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK. This exception may contain warnings.
        InterruptedEngineException - If the calling thread is interrupted

      • injectCDP

        java.lang.String[] injectCDP​(byte[] cdpbytes,
                             java.lang.String filename)
                      throws EngineException
        Injects a CDP (Correlator Deployment Package) into the engine.
        Parameters:
        cdpbytes - the bytes of the CDP file to be injected.
        filename - the name of the file we are injecting from.
        Returns:
        An array of strings which are the set of warnings about the CDP file. May be zero length.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK. This exception may contain warnings.
        InterruptedEngineException - If the calling thread is interrupted

      • inspectEngine

        EngineInfo inspectEngine()
                  throws EngineException
        Ask the Engine for information about the internal state. This provides a minimal "introspection" mechanism to discover for example the names of each of the Monitor defintions and EventType definition that are currently known to the Engine.
        Returns:
        an EngineInfo object contain a "snapshot" of information about the contents of the Engine.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • ping

        void ping()
   throws EngineException
        This method is used to check that the Engine is still alive. If the Engine is alive it returns normally. If there is a problem then reconnection may be attempted, and if that fails, an EngineException is thrown.
        Throws:
        EngineException
        InterruptedEngineException - If the calling thread is interrupted

      • isConnected

        boolean isConnected()
             throws InterruptedEngineException
        This method is used to check that the Engine is still connected. It will not reconnect.
        Returns:
        true if connected, else false.
        Throws:
        InterruptedEngineException - If the calling thread is interrupted

      • connectEventConsumer

        EventSupplier connectEventConsumer​(EventConsumer consumer,
                                   java.lang.String[] channels)
                            throws EngineException
        Connect an event receiver to the Engine.
        Parameters:
        consumer - The EventConsumer to connect to the Engine.
        channels - An array of names representing the channels to subscribe to.
        Returns:
        A reference to an EventSupplier resource.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • connectEventConsumer

        @Deprecated
EventSupplier connectEventConsumer​(EventConsumer consumer,
                                   java.lang.String[] channels,
                                   boolean disconnectSlow)
                            throws EngineException
        Deprecated.
        use connectEventConsumer(EventConsumer, String[]) in combination with EngineManagementFactory.connectToEngine(String, int, String, boolean)}
        Connect an event receiver to the Engine.
        Parameters:
        consumer - The EventConsumer to connect to the Engine.
        channels - An array of names representing the channels to subscribe to.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour.
        Returns:
        A reference to an EventSupplier resource.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • attachAsEventConsumerTo

        void attachAsEventConsumerTo​(EngineManagement eventSupplier,
                             java.lang.String[] channels)
                      throws EngineException
        Connect another Engine to this one as an event supplier, with this engine consuming its events.
        Parameters:
        eventSupplier - The EngineManagement which will supply events to this engine.
        channels - An array of names representing the channels to subscribe to.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • detachAsEventConsumerFrom

        void detachAsEventConsumerFrom​(EngineManagement eventSupplier,
                               java.lang.String[] channels)
                        throws EngineException
        Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
        Parameters:
        eventSupplier - The EngineManagement which is currently supplying events to this engine.
        channels - An array of names representing the channels we were subscribed to.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • detachAsEventConsumerFrom

        void detachAsEventConsumerFrom​(EngineManagement eventSupplier,
                               java.lang.String[] channels,
                               ConnectMode mode)
                        throws EngineException
        Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
        Parameters:
        eventSupplier - The EngineManagement which is currently supplying events to this engine.
        channels - An array of names representing the channels we were subscribed to.
        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 - Thrown if any exceptions occur in the Client SDK.

      • attachAsEventConsumerTo

        void attachAsEventConsumerTo​(EngineManagement eventSupplier,
                             java.lang.String[] channels,
                             boolean disconnectSlow)
                      throws EngineException
        Connect another Engine to this one as an event supplier, with this engine consuming its events.
        Parameters:
        eventSupplier - The EngineManagement which will supply events to this engine.
        channels - An array of names representing the channels to subscribe to.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • attachAsEventConsumerTo

        void attachAsEventConsumerTo​(EngineManagement eventSupplier,
                             java.lang.String[] channels,
                             boolean disconnectSlow,
                             ConnectMode mode)
                      throws EngineException
        Connect another Engine to this one as an event supplier, with this engine consuming its events.
        Parameters:
        eventSupplier - The EngineManagement which will supply events to this engine.
        channels - An array of names representing the channels to subscribe to.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour.
        mode - the connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to PARALLEL for connection per channel and channel values passed through.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • attachAsEventConsumerTo

        void attachAsEventConsumerTo​(java.lang.String host,
                             int port,
                             java.lang.String[] channels)
                      throws EngineException
        Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.
        Parameters:
        host - host of the component which is supplying events
        port - port of the component which is supplying events
        channels - An array of names representing the channels to subscribe to.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • attachAsEventConsumerTo

        void attachAsEventConsumerTo​(java.lang.String host,
                             int port,
                             java.lang.String[] channels,
                             boolean disconnectSlow)
                      throws EngineException
        Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.
        Parameters:
        host - host of the component which is supplying events
        port - port of the component which is supplying events
        channels - An array of names representing the channels to subscribe to.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • attachAsEventConsumerTo

        void attachAsEventConsumerTo​(java.lang.String host,
                             int port,
                             java.lang.String[] channels,
                             boolean disconnectSlow,
                             ConnectMode mode)
                      throws EngineException
        Connect another Engine to this one as an event supplier, with this engine consuming its events, and the receiver should reconnect if it is disconnected.
        Parameters:
        host - host of the component which is supplying events
        port - port of the component which is supplying events
        channels - An array of names representing the channels to subscribe to.
        disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers added to this EngineManagement object share the connection and thus the disconnect behaviour.
        mode - the connection mode to use, defaults to legacy (single connection, all events delivered to the default channel). Set to PARALLEL for connection per channel and channel values passed through.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • detachAsEventConsumerFrom

        void detachAsEventConsumerFrom​(java.lang.String host,
                               int port,
                               java.lang.String[] channels)
                        throws EngineException
        Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
        Parameters:
        host - host of the component which is supplying events
        port - port of the component which is supplying events
        channels - An array of names representing the channels we were subscribed to.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • detachAsEventConsumerFrom

        void detachAsEventConsumerFrom​(java.lang.String host,
                               int port,
                               java.lang.String[] channels,
                               ConnectMode mode)
                        throws EngineException
        Detach another Engine from this one as an event supplier, with this engine no longer consuming its events.
        Parameters:
        host - host of the component which is supplying events
        port - port of the component which is supplying events
        channels - An array of names representing the channels we were subscribed to.
        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 - Thrown if any exceptions occur in the Client SDK.

      • setPersistentReceiveConnections

        @Deprecated
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).
        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

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

      • getReceiverConnections

        EngineConnection[] getReceiverConnections()
                                   throws EngineException
        Get all the persistent connections associated with the engine.
        Returns:
        an array of EngineConnection objects.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • getEngineVersion

        java.lang.String getEngineVersion()
                           throws EngineException
        Get the version of the Engine.
        Returns:
        A string with the version of the Engine connected to.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • sendEvents

        void sendEvents​(Event[] events)
         throws EngineException
        Send events into the Engine (inherited from EventConsumer), automatically rebatching the actual event sending for efficiency.
        Specified by:
        sendEvents in interface EventConsumer
        Parameters:
        events - An array of Event objects containing the events to send into the Engine.
        Throws:
        InterruptedEngineException - If the calling thread is interrupted
        EngineException - Thrown if any exceptions occur in the Client SDK.

      • sendEventsNoBatching

        void sendEventsNoBatching​(Event[] events)
                   throws EngineException
        Send events into the Engine, without rebatching the actual event sending.
        Parameters:
        events - An array of Event objects containing the events to send into the Engine.
        Throws:
        EngineException - Thrown if any exceptions occur in the Client SDK.
        InterruptedEngineException - If the calling thread is interrupted
        See Also:
        flushEvents()

      • flushEvents

        void flushEvents()
          throws EngineException,
                 java.lang.InterruptedException
        Wait for any outstanding events from previous sendEvents(Event[]) calls into the Engine, and then return.
        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:
        sendEvents(Event[])

      • getRemotePhysicalComponentID

        long getRemotePhysicalComponentID()
        Obtain a unique ID for the component that this object is connected to. The physical ID is the same for a given process, so connecting to the same process should yield the same physical component ID. Restarting the process will yield a different ID, even if re-started on the same host and port. (This is the same ID logged in server log files)