Package org.jenkinsci.plugins.workflow.steps

Class StepContext

java.lang.Object
org.jenkinsci.plugins.workflow.steps.StepContext
All Implemented Interfaces:
com.google.common.util.concurrent.FutureCallback<Object>, Serializable
public abstract class StepContext extends Object implements com.google.common.util.concurrent.FutureCallback<Object>, Serializable
An implicit context available to every Step. In a flow, would be created by a FlowExecution. It is serializable so a step which may survive a Jenkins restart is free to save it.

StepContext is only valid until the result is set via FutureCallback. Beyond that point, callers are not allowed to call any of the methods.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    StepContext()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract boolean
    equals(Object o)
    StepContexts get persisted, so they may not have the identity equality, but equals method would allow two instances to be compared.
    abstract <T> T
    get(Class<T> key)
    Tries to find a contextually available object.
    boolean
    hasBody()
    Checks if this step was called with a body.
    abstract int
    hashCode()
    Needs to be overridden as the equals(Object) method is overridden.
    abstract boolean
    isReady()
    Whether get(java.lang.Class<T>) is ready to return values.
    abstract BodyInvoker
    newBodyInvoker()
    Prepares for an asynchronous invocation of the body block that's given as an argument to this step invocation (in a host language dependent manner.)
    abstract void
    onSuccess(Object result)
     
    abstract com.google.common.util.concurrent.ListenableFuture<Void>
    saveState()
    Requests that any state held by the StepExecution be saved to disk.
    abstract void
    setResult(Result r)
    Sets the overall result of the flow.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.google.common.util.concurrent.FutureCallback

    onFailure

  • Constructor Details

    • StepContext

      public StepContext()

  • Method Details

    • get

      public abstract <T> T get(Class<T> key) throws IOException, InterruptedException
      Tries to find a contextually available object. Some types known to be in use:
      Launcher
      a way to fork processes
      EnvVars
      read access to environment variables associated with a run, typically used for launchers
      FilePath
      a “workspace” to use for example as from Launcher.ProcStarter.pwd(hudson.FilePath)
      Computer
      an agent we are running on
      Executor
      an executor slot on an agent we are running on
      TaskListener
      a place to send output (see LogAction for a flow)
      Run
      a running build
      FlowExecution
      a running flow
      FlowNode
      a running node in a flow
      Parameters:
      key - the kind of thing we want
      Returns:
      that service, if available (which it should be if StepDescriptor.getRequiredContext() includes it), else null
      Throws:
      IOException - If StepContext gets serialized, Jenkins restarts, deserialized later, and Step tries to get additional context objects, it can be that the corresponding FlowExecution could be non-existent (for example, the run that was driving the flow could have failed to load.) This exception is thrown in such situations just like FlowExecutionOwner.get throws IOException.
      InterruptedException
      See Also:

    • onSuccess

      public abstract void onSuccess(@Nullable Object result)
      Specified by:
      onSuccess in interface com.google.common.util.concurrent.FutureCallback<Object>

    • isReady

      public abstract boolean isReady()
      Whether get(java.lang.Class<T>) is ready to return values. May be called to break deadlocks during reloading.
      Returns:
      true normally, false if we are still reloading the context, for example during unpickling

    • saveState

      public abstract com.google.common.util.concurrent.ListenableFuture<Void> saveState()
      Requests that any state held by the StepExecution be saved to disk. Useful when a long-running step has changed some instance fields (or the content of a final field) and needs these changes to be recorded. An implementation might in fact save more state than just the associated step execution, but it must save at least that much.
      Returns:
      a future letting you know if and when the state was in fact saved

    • setResult

      public abstract void setResult(Result r)
      Sets the overall result of the flow. Like Run.setResult(hudson.model.Result), can only make the result worse than it already is. Since some flows may have try-catch semantics, if a step fails to complete normally it is better to use FutureCallback.onFailure(Throwable) instead. (For example with FlowInterruptedException.)
      Parameters:
      r - Result.UNSTABLE, typically

    • newBodyInvoker

      public abstract BodyInvoker newBodyInvoker() throws IllegalStateException
      Prepares for an asynchronous invocation of the body block that's given as an argument to this step invocation (in a host language dependent manner.)

      When the block is completed normally or abnormally, you can have have the callback invoked. The invocation will not get scheduled until you start it.

      StepDescriptor.takesImplicitBlockArgument() must be true.

      Throws:
      IllegalStateException - if hasBody() is false

    • hasBody

      public boolean hasBody()
      Checks if this step was called with a body.
      Returns:
      true if StepDescriptor.takesImplicitBlockArgument() is true, and such a body was in fact passed in; false otherwise

    • equals

      public abstract boolean equals(Object o)
      StepContexts get persisted, so they may not have the identity equality, but equals method would allow two instances to be compared.
      Overrides:
      equals in class Object
      Returns:
      true if StepContexts are for the same context for the same execution.

    • hashCode

      public abstract int hashCode()
      Needs to be overridden as the equals(Object) method is overridden.
      Overrides:
      hashCode in class Object