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:

Serialized Form

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 Detail

StepContext

public StepContext()

Method Detail

get

@Nullable
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:

BodyInvoker.withContext(java.lang.Object), DynamicContext

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