Package org.jenkinsci.plugins.workflow.steps

Class StepExecution

java.lang.Object
org.jenkinsci.plugins.workflow.steps.StepExecution
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AbstractStepExecutionImpl, GeneralNonBlockingStepExecution, SynchronousNonBlockingStepExecution, SynchronousStepExecution
public abstract class StepExecution extends Object implements Serializable
Scoped to a single execution of Step, and provides insights into what's going on asynchronously and aborting the activity if need be.

StepExecutions are persisted whenever used to run an asynchronous operation.

Author:
Kohsuke Kawaguchi, Jesse Glick
See Also:

  • Constructor Details

  • Method Details

    • getContext

      @NonNull public StepContext getContext()

    • start

      public abstract boolean start() throws Exception
      Start execution of something and report the end result back to the given callback.

      Arguments are passed when instantiating steps.

      This method will run in the CPS VM thread and as such should not perform I/O or block. Use SynchronousNonBlockingStepExecution or GeneralNonBlockingStepExecution as needed.

      Returns:
      true if the execution of this step has synchronously completed before this method returns. It is the callee's responsibility to set the return value via StepContext.onSuccess(Object) or FutureCallback.onFailure(Throwable). false if the asynchronous execution has started and that StepContext will be notified when the result comes in. (Note that the nature of asynchrony is such that it is possible for the StepContext to be already notified before this method returns.)
      Throws:
      Exception - if any exception is thrown, Step is assumed to have completed abnormally synchronously (as if FutureCallback.onFailure(java.lang.Throwable) is called and the method returned true.)

    • stop

      public void stop(@NonNull Throwable cause) throws Exception
      May be called if someone asks a running step to abort.

      Just like Thread.interrupt(), the step might not honor the request immediately. Multiple stop requests might be sent. It is always responsible for calling StepContext.onSuccess(Object) or (more likely) FutureCallback.onFailure(Throwable) eventually, whether or not it was asked to stop.

      The default behavior is to call FutureCallback.onFailure(java.lang.Throwable) immediately. This may be overridden by non-block-scoped steps which wish to halt some processing prior to failing the step, or even to send a cancellation signal to some process but leave the step running until that is handled gracefully. Block-scoped steps which merely call their bodies generally need not override this method, as the interrupt will be sent to the step(s) actually running at the time (so no special call to BodyExecution.cancel(Throwable) is needed), though an override may be necessary if it is possible for there to be no body currently running.

      This method is meant to be used by FlowExecution, not called from UI or other human requests to pause. Use BodyExecution.cancel(Throwable) for programmatic cancellation of bodies.

      Parameters:
      cause - Contextual information that lets the step know what resulted in stopping an executing step, passed in the hope that this will assist diagnostics.
      Throws:
      Exception

    • onResume

      public void onResume()
      Called when StepExecution is brought back into memory after restart. Convenient for re-establishing the polling.

      Currently not permitted to throw exceptions, but may report errors via FutureCallback.onFailure(java.lang.Throwable).

      See Also:

    • getStatus

      @CheckForNull public String getStatus()
      May be overridden to provide specific information about what a step is currently doing, for diagnostic purposes. Typical format should be a short, lowercase phrase. It should not be localized as this is intended for use by developers as well as users. May include technical details about Jenkins internals if relevant.
      Returns:
      current status, or null if unimplemented
      See Also:

    • blocksRestart

      public boolean blocksRestart()
      Allows a step to indicate that AsynchronousExecution.blocksRestart() should be true. Typically this would be true if getStatus() indicates that the step is in the middle of something active, as opposed to waiting for an external event or a body to complete.

      Note that activity in the CPS VM thread automatically blocks restart, so overriding this is only necessary for steps using a background thread, such as SynchronousNonBlockingStepExecution or GeneralNonBlockingStepExecution.

      Returns:
      false by default

    • getStatusBounded

      @CheckForNull public final String getStatusBounded(long timeout, TimeUnit unit)
      Like getStatus() but more robust. Waits a most a given amount of time for the result, and handles RuntimeExceptions.
      Parameters:
      timeout - maximum amount of time to spend
      unit - time unit

    • applyAll

      public static com.google.common.util.concurrent.ListenableFuture<?> applyAll(com.google.common.base.Function<StepExecution,Void> f)
      Apply the given function to all the active running StepExecutions in the system.
      Returns:
      Future object that signals when the function application is complete.
      See Also:

    • applyAll

      public static <T extends StepExecution> com.google.common.util.concurrent.ListenableFuture<?> applyAll(Class<T> type, com.google.common.base.Function<T,Void> f)
      Applies only to the specific subtypes.