Package org.jenkinsci.plugins.workflow.flow

Class FlowExecution

  • All Implemented Interfaces:
    FlowActionStorage, GraphLookupView
    public abstract class FlowExecution
extends Object
implements FlowActionStorage, GraphLookupView
    State of a currently executing workflow.

    This "interface" abstracts away workflow definition language, syntax, or its execution model, but it allows other code to listen on what's going on.

    Persistence

    FlowExecution must support persistence by XStream, which should capture the state of execution at one point. The expectation is that when the object gets deserialized, it'll start re-executing from that point.

    Author:
    Kohsuke Kawaguchi, Jesse Glick

    • Field Detail

      • internalGraphLookup

        protected transient GraphLookupView internalGraphLookup

      • durabilityHint

        @CheckForNull
protected FlowDurabilityHint durabilityHint
        CheckForNull due to loading pre-durability runs.

    • Constructor Detail

      • FlowExecution

        public FlowExecution()

    • Method Detail

      • getInternalGraphLookup

        protected GraphLookupView getInternalGraphLookup()
        Eventually this may be overridden if the FlowExecution has a better source of structural information, such as the FlowNode storage.

      • getDurabilityHint

        @NonNull
public FlowDurabilityHint getDurabilityHint()
        Get the durability level we're aiming for, or a default value if none is set (defaults may change as implementation evolve).
        Returns:
        Durability level we are aiming for with this execution.

      • onLoad

        @Deprecated
public void onLoad()
        Deprecated.

      • getCurrentHeads

        public abstract List<FlowNode> getCurrentHeads()
        In the current flow graph, return all the "head" nodes where the graph is still growing. If you think of a flow graph as a git repository, these heads correspond to branches.

      • getCurrentExecutions

        public com.google.common.util.concurrent.ListenableFuture<List<org.jenkinsci.plugins.workflow.steps.StepExecution>> getCurrentExecutions​(boolean innerMostOnly)
        Yields the StepExecutions that are currently executing.

        StepExecutions are persisted as a part of the program state, so its lifecycle is independent of FlowExecution, hence the asynchrony.

        Think of this as program counters of all the virtual threads.

        The implementation should return results in the order that steps were started, insofar as that makes sense.

        Parameters:
        innerMostOnly - if true, only return the innermost steps; if false, include any block-scoped steps running around them

      • getCurrentExecutions

        @Deprecated
public com.google.common.util.concurrent.ListenableFuture<List<org.jenkinsci.plugins.workflow.steps.StepExecution>> getCurrentExecutions()
        Deprecated.

      • isCurrentHead

        public abstract boolean isCurrentHead​(FlowNode n)
        Short for getCurrentHeads().contains(n) but more efficient.

      • getUrl

        public String getUrl()
              throws IOException
        Returns the URL of this FlowExecution, relative to the context root of Jenkins.
        Returns:
        String like "job/foo/32/execution/" with trailing slash but no leading slash.
        Throws:
        IOException

      • interrupt

        public abstract void interrupt​(Result r,
                               CauseOfInterruption... causes)
                        throws IOException,
                               InterruptedException
        Interrupts the execution of a flow. If any computation is going on synchronously, it will be interrupted/killed/etc. If it's in a suspended state waiting to be resurrected (such as waiting for StepContext.onSuccess(Object)), then it just marks the workflow as done with the specified status.

        If it's evaluating bodies (see StepContext.newBodyInvoker(), then it's callback needs to be invoked.

        Do not use this from a step. Throw FlowInterruptedException or some other exception instead.

        Throws:
        IOException
        InterruptedException
        See Also:
        StepExecution.stop(Throwable), Executor.interrupt(Result)

      • addListener

        public abstract void addListener​(GraphListener listener)
        Add a listener to changes in the flow graph structure.
        Parameters:
        listener - a listener to add

      • isComplete

        public boolean isComplete()
        Checks whether this flow execution has finished executing completely.

      • blocksRestart

        public boolean blocksRestart()
        Determines whether the activity currently being run should block a Jenkins restart.
        Returns:
        by default, true
        See Also:
        AsynchronousExecution.blocksRestart()

      • getCauseOfFailure

        @CheckForNull
public final Throwable getCauseOfFailure()
        If this execution has completed with an error, report that. This is a convenience method to look up the error result from FlowEndNode.

      • getAuthentication

        @NonNull
public abstract Authentication getAuthentication()
        Looks up authentication associated with this flow execution. For example, if a flow is configured to be a trusted agent of a user, that would be set here. A flow run triggered by a user manually might be associated with the runtime, or it might not.
        Returns:
        an authentication; ACL.SYSTEM as a fallback, or Jenkins.ANONYMOUS if the flow is supposed to be limited to a specific user but that user cannot now be looked up

      • afterStepExecutionsResumed

        protected void afterStepExecutionsResumed()
        Called after a restart and any attempts at StepExecution.onResume() have completed. This is a signal that it is safe to resume program execution. By default, does nothing.