Package org.copperengine.core

Interface ProcessingEngine

  • All Known Subinterfaces:
    PersistentProcessingEngine
    All Known Implementing Classes:
    AbstractProcessingEngine, PersistentScottyEngine, TransientScottyEngine
    public interface ProcessingEngine
    Runtime container for COPPER workflows and main entry point for running COPPER workflow instances. The engine may be transient or persistent - this depends on the concrete implementation. An engine is running in a single process (JVM). A process may run/contain several engines.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addShutdownObserver​(java.lang.Runnable observer)
      Adds a shutdown observer/hook to the engine.
      void addWaitHook​(java.lang.String wfInstanceId, WaitHook waitHook)
      Adds the specified WaitHook for the workflow instance with the specified id.
      java.lang.String createUUID()  
      java.lang.String getEngineId()
      returns the engines id
      EngineState getEngineState()
      returns the engines current state
      void notify​(Response<?> response, Acknowledge ack)
      Adds a response to the engine.
      void registerCallbacks​(Workflow<?> w, WaitMode mode, long timeoutMsec, java.lang.String... correlationIds)
      Registers a workflow instance to we waiting for a number of correlation ids.
      java.lang.String run​(java.lang.String wfname, java.lang.Object data)
      Enqueues the specified workflow instance into the engine for execution.
      java.lang.String run​(WorkflowInstanceDescr<?> wfInstanceDescr)
      Enqueues the specified workflow instance description into the engine for execution.
      void runBatch​(java.util.List<WorkflowInstanceDescr<?>> wfInstanceDescr)
      Enqueues the specified batch of workflow instance descriptions into the engine for execution.
      void shutdown()
      Triggers the shutdown of the engine.
      void startup()
      Starts up the engine.

    • Method Detail

      • startup

        void startup()
      throws CopperRuntimeException
        Starts up the engine. The invocation of this method blocks until the startup procedure is finished. This method might even throw an Error, if something fundamentally wents wrong like starting up the workflow repository or database storage.
        Throws:
        CopperRuntimeException - Depending on the configured engine (Type of engine, processor pool manager, (Storage), workflow repository, ...) a lot of things can go wrong. If any Exception is thrown in the startup process, this will be transformed to a CopperRuntimeException. All other RuntimeExceptions (like NullPointerException) are just rethrown. Fundamental startup problems might even throw an Error.

      • shutdown

        void shutdown()
       throws CopperRuntimeException
        Triggers the shutdown of the engine. The engine tries to end running workflow instances gracefully. The invocation of this method returns immediately.
        Throws:
        CopperRuntimeException - - wraps Exceptions which could happen in different types of configured engines into RuntimeExceptions. Further RuntimeExceptions like IllegalStateException might also be thrown.

      • addShutdownObserver

        void addShutdownObserver​(java.lang.Runnable observer)
        Adds a shutdown observer/hook to the engine. During shutdown of the engine, Runnable.run() of each registered observer is called subsequently.
        Parameters:
        observer - the observer/hook to add

      • registerCallbacks

        void registerCallbacks​(Workflow<?> w,
                       WaitMode mode,
                       long timeoutMsec,
                       java.lang.String... correlationIds)
                throws CopperRuntimeException
        Registers a workflow instance to we waiting for a number of correlation ids.
        Parameters:
        w - the workflow instance waiting for one or more response
        mode - the wait mode
        timeoutMsec - the relative timeout in milliseconds or 0 for no an infinite timeout
        correlationIds - the correlation ids of the expected responses
        Throws:
        CopperRuntimeException - - Should not be thrown at the moment but might happen in future engine implementations.

      • notify

        void notify​(Response<?> response,
            Acknowledge ack)
     throws CopperRuntimeException
        Adds a response to the engine. The engine will subsequently try to find the corresponding workflow instance that is waiting for the response. Depending on the workflow instances waitmode and the number of open responses, the workflow may or may not be resumed.
        Parameters:
        response - the reponse
        ack - the object to notify upon processing of the message. Note: The ack.waitForAcknowledge returns when the response is processed by the COPPER engine, not when the workflow was waked up with this response.
        Throws:
        CopperRuntimeException - All exceptions thrown in the attempt of notification (e.g. for persistent engine storing in database) are wrapped into CopperRuntimeException and rethrown.

      • createUUID

        java.lang.String createUUID()
        Returns:
        Creates and returns a Universally Unique Identifier (UUID). The UUID may be used for workflow ids or correlation ids.

      • run

        java.lang.String run​(java.lang.String wfname,
                     java.lang.Object data)
              throws CopperException,
                     DuplicateIdException
        Enqueues the specified workflow instance into the engine for execution.
        Parameters:
        wfname - name or alias of the workflows class
        data - the data to pass to the workflow
        Returns:
        workflow instance Id
        Throws:
        CopperException - if the engine can not run the workflow for some reason, e.g. in case of an unknown processor pool id.
        DuplicateIdException - if a workflow instance with the same id already exists [Collision in unique-id-creator]

      • run

        java.lang.String run​(WorkflowInstanceDescr<?> wfInstanceDescr)
              throws CopperException,
                     DuplicateIdException
        Enqueues the specified workflow instance description into the engine for execution.
        Parameters:
        wfInstanceDescr - the workflow instance description out of which a workflow is generated and put into the engine for execution
        Returns:
        workflow instance Id
        Throws:
        CopperException - if the engine can not run the workflow for some reason, e.g. in case of an unknown processor pool id.
        DuplicateIdException - if a workflow instance with the same id already exists

      • runBatch

        void runBatch​(java.util.List<WorkflowInstanceDescr<?>> wfInstanceDescr)
       throws CopperException,
              DuplicateIdException
        Enqueues the specified batch of workflow instance descriptions into the engine for execution.
        Parameters:
        wfInstanceDescr - batch or workflow instance descriptions to be put into the engine for execution
        Throws:
        CopperException - if the engine can not run the workflows for some reason, e.g. in case of an unknown processor pool id.
        DuplicateIdException - if a workflow instance with the same id already exists

      • getEngineState

        EngineState getEngineState()
        returns the engines current state
        Returns:
        the engine state

      • getEngineId

        java.lang.String getEngineId()
        returns the engines id
        Returns:
        the engine id

      • addWaitHook

        void addWaitHook​(java.lang.String wfInstanceId,
                 WaitHook waitHook)
        Adds the specified WaitHook for the workflow instance with the specified id. The WaitHook is called once at the next wait invocation of the specified workflow instance.
        Parameters:
        wfInstanceId - workflow instance id
        waitHook - wait hook