Package org.copperengine.core

Class Workflow<D>

  • Type Parameters:
    D - workflow's data class
    All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    PersistentWorkflow
    public abstract class Workflow<D>
extends java.lang.Object
implements java.io.Serializable
    Abstract COPPER workflow base class. Workflows must inherit from this class. If your workflow requires (or maybe requires) persistence, then it has to inherit from PersistentWorkflow.
    See Also:
    Serialized Form

    • Constructor Detail

      • Workflow

        protected Workflow()
        Creates a new instance

    • Method Detail

      • getProcessingState

        public ProcessingState getProcessingState()
        Returns:
        the processing state

      • getPriority

        public int getPriority()
        Returns:
        the workflow instance priority

      • setPriority

        public void setPriority​(int priority)
        Sets the priority for this workflow instance. A smaller value is a higher priority, e.g. a priority of 1 is higher than 2.
        Parameters:
        priority - new priority (Takes effect after next checkpoint (wait/resubmit/savepoint) for prioritizing waiting..

      • setEngine

        public void setEngine​(ProcessingEngine engine)
        For internal use only
        Parameters:
        engine - engine which (currently) owns this workflow. [For a distributed setup it might happen that another engine takes over the workflow for computation. But the workflow can always call getEngine() and receives the current owning engine.]

      • setId

        public void setId​(java.lang.String id)

      • getEngine

        public ProcessingEngine getEngine()
        Returns:
        the processing engine currently executing this workflow instance

      • getId

        public java.lang.String getId()
        Returns:
        the id of this workflow instance. The id of a workflow instance is at least unique within one processing engine.

      • createCallback

        protected <E> Callback<E> createCallback()
        Creates a Callback object used for the asynchronous wait for some reponse.
        Type Parameters:
        E - type of response for the new callback
        Returns:
        the created callback

      • waitForAll

        protected final void waitForAll​(java.lang.String... correlationIds)
                         throws Interrupt
        waits/sleeps until a response for every correlation id occurs
        Parameters:
        correlationIds - one or more correlation ids
        Throws:
        Interrupt - for internal use of COPPER. When wait is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • waitForAll

        protected final void waitForAll​(Callback<?>... callbacks)
                         throws Interrupt
        waits/sleeps until a response for every callback occurs
        Parameters:
        callbacks - one or more callback objects
        Throws:
        Interrupt - for internal use of COPPER. When wait is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • wait

        protected final void wait​(WaitMode mode,
                          int timeoutMsec,
                          java.lang.String... correlationIds)
                   throws Interrupt
        Generic wait/sleep. In case of WaitMode FIRST, it waits until at least one response for the specified correlation ids occurs. In case of WaitMode ALL, it waits until a response for every specified correlation id occurs.
        Parameters:
        mode - WaitMode
        timeoutMsec - timeout in milliseconds or NO_TIMEOUT (or any value ≤ 0) to wait for ever
        correlationIds - one ore more correlation ids
        Throws:
        Interrupt - for internal use of COPPER. When wait is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • wait

        protected final void wait​(WaitMode mode,
                          long timeout,
                          java.util.concurrent.TimeUnit timeUnit,
                          java.lang.String... correlationIds)
                   throws Interrupt
        Generic wait/sleep. In case of WaitMode FIRST, it waits until at least one response for the specified correlation ids occurs. In case of WaitMode ALL, it waits until a response for every specified correlation id occurs.
        Parameters:
        mode - WaitMode
        timeout - timeout or NO_TIMEOUT (or any value ≤ 0) to wait for ever
        timeUnit - unit of the timeout; ignored, if a negative timeout is specified
        correlationIds - one ore more correlation ids
        Throws:
        Interrupt - for internal use of COPPER. When wait is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • wait

        protected final void wait​(WaitMode mode,
                          long timeout,
                          java.util.concurrent.TimeUnit timeUnit,
                          Callback<?>... callbacks)
                   throws Interrupt
        Generic wait/sleep. In case of WaitMode FIRST, it waits until at least one response for the specified correlation ids occurs. In case of WaitMode ALL, it waits until a response for every specified correlation id occurs.
        Parameters:
        mode - WaitMode
        timeout - timeout or NO_TIMEOUT (or any value ≤ 0) to wait for ever
        timeUnit - unit of the timeout; ignored, if a negative timeout is specified
        callbacks - one ore more callbacks
        Throws:
        Interrupt - for internal use of COPPER. When wait is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • putResponse

        public void putResponse​(Response<?> r)
        Internal use only - called by the processing engine
        Parameters:
        r - response to be put into the response map.

      • getAndRemoveResponse

        protected <T> Response<T> getAndRemoveResponse​(java.lang.String correlationId)
        Gets and removes a response for the specified correlation id.

        Attention: When a workflow instance is resumed after a Workflow.wait call, all corresponding responses for this workflow instance in the storage are read. Each of these responses that you do NOT retrieve using getAndRemoveResponse(String) or getAndRemoveResponses(String) are discarded when calling the next Workflow.wait

        Type Parameters:
        T - type of data holt in the response
        Parameters:
        correlationId - correlation id for which response shall be get
        Returns:
        the response or null, if no response for the specified correlation id is found

      • getAndRemoveResponses

        protected <T> java.util.List<Response<T>> getAndRemoveResponses​(java.lang.String correlationId)
        Gets and removes all responses for the specified correlation id

        Attention: When a workflow instance is resumed after a Workflow.wait call, all corresponding responses for this workflow instance in the storage are read. Each of these responses that you do NOT retrieve using getAndRemoveResponse(String) or getAndRemoveResponses(String) are discarded when calling the next Workflow.wait

        Type Parameters:
        T - type of data holt in the response
        Parameters:
        correlationId - correlation id for which responses shall be get
        Returns:
        the list of responses or an empty list, if no response for the specified correlation id is found

      • getAnyNonTimedOutAndRemoveResponse

        protected <T> Response<T> getAnyNonTimedOutAndRemoveResponse​(java.lang.Class<? extends T> type)
        This method is similar to getAndRemoveResponse but a convenient extension for some usage scenarios. Sometimes, we don't bother which correlation ID is notificated upon but just want one of the notifications. (e.g. we send the same request to multiple services and are happy if one of those answers.) We could also run wait in a timed out loop and handle always those responses only which already got answered (for the next loop iteration we could remove the to be waited correlation ids from the wait list by querying the correlation id via response.getCorrelationID).) In the method, we look up the list of responses and return any of those which didn't run into a timeout (and with the per parameter given type). If multiple correlations didn't run into a timeout, a random one of those is returned and removed. If all given correlation IDs with the given type ran into the timeout, null is returned! This is due to the fact, that we can't find the type of an empty response on runtime and thus not filter accordingly. So if null is returned, you know that the workflow was waken up by timeout. (If all correlation IDs were of the given type) Responses with different types than the specified one are just ignored. Call it like 
             Response<MyResponseType> resp = getAnyNonTimedOutAndRemoveResponse(MyResponseType.class);
        To get any non timed out response, you can just call the method with Object.class as parameter.
        Type Parameters:
        T - type of data holt in the response
        Parameters:
        type - type class for which responses shall be get. (e.g. for getting only Response<String>). Might as well be Object.class to get valid Responses with all types of data.
        Returns:
        the response or null, if no fitting response is found

      • main

        public abstract void main()
                   throws Interrupt
        Entry point for this workflow
        Throws:
        Interrupt - for internal use of COPPER. When main is called, an Interrupt may be thrown, caught by COPPER itself for taking back control over the executed workflow.

      • resubmit

        protected final void resubmit()
                       throws Interrupt
        Causes the engine to stop processing of this workflow instance and to enqueue it again. May be used in case of processor pool change or to create a 'savepoint'.
        Throws:
        Interrupt - for internal use of COPPER. After resubmit is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • savepoint

        protected final void savepoint()
                        throws Interrupt
        Causes the engine to stop processing of this workflow instance and to enqueue it again. May be used in case of processor pool change or to create a 'savepoint' in a persistent engine.

        Same as resubmit()

        Throws:
        Interrupt - for internal use of COPPER. After savepoint is called, an Interrupt is thrown, caught by COPPER itself for taking back control over the executed workflow.

      • notify

        protected final <T> void notify​(Response<T> response)

      • setProcessorPoolId

        public void setProcessorPoolId​(java.lang.String processorPoolId)
        Sets the processor pool id for this workflow instance. Changes get active at the next enqueue of this workflow instance. You may initiate an enqueue using resubmit()
        Parameters:
        processorPoolId - id of the proccesor pool as specified in the configuration

      • getProcessorPoolId

        public java.lang.String getProcessorPoolId()
        Returns:
        the processor pool id

      • get__stack

        public java.util.List<StackEntry> get__stack()
        For internal usage only
        Returns:
        the internally used stack representing the call stack altogether with used local variables.

      • getData

        public D getData()
        Returns:
        the data attached to this workflow instance

      • setData

        public void setData​(D data)
        Sets the data for this workflow instance. Typically invoked at construction time of a workflow instance
        Parameters:
        data - the new data object for this workflow

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • __beforeProcess

        public void __beforeProcess()

      • getCreationTS

        public java.util.Date getCreationTS()
        Returns:
        the creation timestamp for this workflow instance.

      • createCheckpointAcknowledge

        protected Acknowledge createCheckpointAcknowledge()
        We create a quasi empty acknowledge here. It doesn't block at all and has empty callbacks for success and errors.
        Returns:
        a BestEffortAcknowledge

      • registerCheckpointAcknowledge

        protected void registerCheckpointAcknowledge​(Acknowledge ack)

      • registerSavepointAware

        protected void registerSavepointAware​(SavepointAware sa)

      • prettyPrintData

        public java.lang.String prettyPrintData()

      • getLastWaitStackTrace

        public java.lang.String getLastWaitStackTrace()

      • getLastActivityTS

        public java.util.Date getLastActivityTS()

      • getTimeoutTS

        public java.util.Date getTimeoutTS()