jenkins.tasks

Class SimpleBuildWrapper

java.lang.Object

hudson.model.AbstractDescribableImpl<BuildWrapper>

hudson.tasks.BuildWrapper

jenkins.tasks.SimpleBuildWrapper

All Implemented Interfaces:

ExtensionPoint, Describable<BuildWrapper>

public abstract class SimpleBuildWrapper
extends BuildWrapper

A generalization of BuildWrapper that, like SimpleBuildStep, may be called at various points within a build.

Such a build wrapper would typically be written according to make few assumptions about how it is being used. Some hints about this refactoring:

• Replace AbstractBuild.getWorkspace() with the provided path.
• Replace AbstractBuild.getProject() with Run.getParent().
• Use FilePath.toComputer() rather than Computer.currentComputer().
• Do not bother with AbstractBuild.getBuildVariables() if you are not passed an AbstractBuild (treat it like an empty map).
• The SimpleBuildWrapper.Disposer must be safely serializable. This means it should be a static class if nested, and define a serialVersionUID.

Since:

1.599

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SimpleBuildWrapper.Context Parameter passed to setUp(jenkins.tasks.SimpleBuildWrapper.Context, hudson.model.Run<?, ?>, hudson.FilePath, hudson.Launcher, hudson.model.TaskListener, hudson.EnvVars) to allow an implementation to specify its behavior after the initial setup.
static class	SimpleBuildWrapper.Disposer An optional callback to run at the end of the wrapped block.

Nested classes/interfaces inherited from class hudson.tasks.BuildWrapper

BuildWrapper.Environment

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor and Description
SimpleBuildWrapper()

Method Summary

Modifier and Type	Method and Description
SimpleBuildWrapper.Context	createContext() Creates a new SimpleBuildWrapper.Context for use with this wrapper.
ConsoleLogFilter	createLoggerDecorator(Run<?,?> build) Allows this wrapper to decorate log output.
Launcher	decorateLauncher(AbstractBuild build, Launcher launcher, BuildListener listener) May be overridden but this will only take effect when used as a BuildWrapper on an AbstractProject.
OutputStream	decorateLogger(AbstractBuild build, OutputStream logger) Provides an opportunity for a BuildWrapper to decorate the BuildListener logger to be used by the build.
Collection<? extends Action>	getProjectActions(AbstractProject job) Actions to be displayed in the job page.
void	makeBuildVariables(AbstractBuild build, Map<String,String> variables) May be overridden but this will only take effect when used as a BuildWrapper on an AbstractProject.
void	makeSensitiveBuildVariables(AbstractBuild build, Set<String> sensitiveVariables) May be overridden but this will only take effect when used as a BuildWrapper on an AbstractProject.
void	preCheckout(AbstractBuild build, Launcher launcher, BuildListener listener) Provides an opportunity for a BuildWrapper to perform some actions before SCM checkout.
boolean	requiresWorkspace() Determines whether or not this wrapper requires a workspace context (working directory and launcher).
protected boolean	runPreCheckout() By default, when run as part of an AbstractBuild, will run late, in the setUp(AbstractBuild, Launcher, BuildListener) phase.
BuildWrapper.Environment	setUp(AbstractBuild build, Launcher launcher, BuildListener listener) Runs before the Builder runs (but after the checkout has occurred), and performs a set up.
void	setUp(SimpleBuildWrapper.Context context, Run<?,?> build, FilePath workspace, Launcher launcher, TaskListener listener, EnvVars initialEnvironment) Called when a segment of a build is started that is to be enhanced with this wrapper.
void	setUp(SimpleBuildWrapper.Context context, Run<?,?> build, TaskListener listener, EnvVars initialEnvironment) Called when a segment of a build is started that is to be enhanced with this wrapper.

Methods inherited from class hudson.tasks.BuildWrapper

all, getProjectAction, setUp

Methods inherited from class hudson.model.AbstractDescribableImpl

getDescriptor

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleBuildWrapper

public SimpleBuildWrapper()

Method Detail

requiresWorkspace

public boolean requiresWorkspace()

Determines whether or not this wrapper requires a workspace context (working directory and launcher).

When such a context is required (the default), setUp(Context, Run, FilePath, Launcher, TaskListener, EnvVars) applies. Otherwise, setUp(Context, Run, TaskListener, EnvVars) applies.

Returns:

true if this wrapper requires a workspace context; false otherwise.

Since:

TODO

setUp

public void setUp(SimpleBuildWrapper.Context context,
                  Run<?,?> build,
                  FilePath workspace,
                  Launcher launcher,
                  TaskListener listener,
                  EnvVars initialEnvironment)
           throws IOException,
                  InterruptedException

Called when a segment of a build is started that is to be enhanced with this wrapper.

This method must be overridden when this wrapper requires a workspace context. If such a context is not required, it does not need to be overridden; it will then forward to setUp(Context, Run, TaskListener, EnvVars).

Parameters:

context - a way of collecting modifications to the environment for nested steps

build - a build being run

workspace - a workspace of the build

launcher - a way to start commands

listener - a way to report progress

initialEnvironment - the environment variables set at the outset

Throws:

AbstractMethodError - if this wrapper requires a workspace context, and this method is not overridden

IOException - if something fails; AbortException for user errors

InterruptedException - if setup is interrupted

setUp

public void setUp(SimpleBuildWrapper.Context context,
                  Run<?,?> build,
                  TaskListener listener,
                  EnvVars initialEnvironment)
           throws IOException,
                  InterruptedException

Called when a segment of a build is started that is to be enhanced with this wrapper.

This method must be overridden when this wrapper does not require a workspace context, and will not be called when such a context is required.

Parameters:

context - a way of collecting modifications to the environment for nested steps

build - a build being run

listener - a way to report progress

initialEnvironment - the environment variables set at the outset

Throws:

AbstractMethodError - if this method is not overridden

IllegalStateException - if this wrapper requires a workspace context

IOException - if something fails; AbortException for user errors

InterruptedException - if setup is interrupted

Since:

TODO

createContext

@Restricted(value=org.kohsuke.accmod.restrictions.Beta.class)
public SimpleBuildWrapper.Context createContext()

Creates a new SimpleBuildWrapper.Context for use with this wrapper.

Returns:

a new SimpleBuildWrapper.Context instance

runPreCheckout

protected boolean runPreCheckout()

By default, when run as part of an AbstractBuild, will run late, in the setUp(AbstractBuild, Launcher, BuildListener) phase. May be overridden to return true, in which case this will run earlier, in the preCheckout(hudson.model.AbstractBuild, hudson.Launcher, hudson.model.BuildListener) phase. Ignored when not run as part of an AbstractBuild.

setUp

public final BuildWrapper.Environment setUp(AbstractBuild build,
                                            Launcher launcher,
                                            BuildListener listener)
                                     throws IOException,
                                            InterruptedException

Description copied from class: BuildWrapper

Runs before the Builder runs (but after the checkout has occurred), and performs a set up.

Overrides:

setUp in class BuildWrapper

Parameters:

build - The build in progress for which an BuildWrapper.Environment object is created. Never null.

launcher - This launcher can be used to launch processes for this build. If the build runs remotely, launcher will also run a job on that remote machine. Never null.

listener - Can be used to send any message.

Returns:

non-null if the build can continue, null if there was an error and the build needs to be aborted.

Throws:

IOException - terminates the build abnormally. Jenkins will handle the exception and report a nice error message.

InterruptedException

preCheckout

public final void preCheckout(AbstractBuild build,
                              Launcher launcher,
                              BuildListener listener)
                       throws IOException,
                              InterruptedException

Description copied from class: BuildWrapper

Provides an opportunity for a BuildWrapper to perform some actions before SCM checkout.

This hook is called early on in the build (before BuildWrapper.setUp(AbstractBuild, Launcher, BuildListener), but after BuildWrapper.decorateLauncher(AbstractBuild, Launcher, BuildListener) is invoked.) The typical use is delete existing workspace before new build starts etc.

By the time this method is called, the workspace is assigned to the build, which can be obtained via build.getWorkspace().

The default implementation is no-op.

Overrides:

preCheckout in class BuildWrapper

Parameters:

build - The build in progress for which this BuildWrapper is called. Never null.

launcher - The launcher. Never null.

listener - Connected to the build output. Never null. Can be used for error reporting.

Throws:

IOException

InterruptedException

createLoggerDecorator

@CheckForNull
public ConsoleLogFilter createLoggerDecorator(@NonNull
                                                            Run<?,?> build)

Allows this wrapper to decorate log output.

Parameters:

build - as is passed to setUp(Context, Run, FilePath, Launcher, TaskListener, EnvVars)

Returns:

a filter which ignores its build parameter and is Serializable; or null (the default)

Since:

1.608

decorateLogger

public final OutputStream decorateLogger(AbstractBuild build,
                                         OutputStream logger)
                                  throws IOException,
                                         InterruptedException,
                                         Run.RunnerAbortedException

Description copied from class: BuildWrapper

Provides an opportunity for a BuildWrapper to decorate the BuildListener logger to be used by the build.

This hook is called very early on in the build (even before BuildWrapper.setUp(AbstractBuild, Launcher, BuildListener) is invoked.)

The default implementation is no-op, which just returns the logger parameter as-is.

(ArgumentListBuilder.add(String, boolean) is a simpler way to suppress a single password.)

Overrides:

decorateLogger in class BuildWrapper

Parameters:

build - The build in progress for which this BuildWrapper is called. Never null.

logger - The default logger. Never null. This method is expected to wrap this logger. This makes sure that when multiple BuildWrappers attempt to decorate the same logger it will sort of work.

Returns:

Must not be null. If a fatal error happens, throw an exception.

Throws:

Run.RunnerAbortedException - If a fatal error is detected but the implementation handled it gracefully, throw this exception to suppress stack trace.

IOException

InterruptedException

See Also:

ConsoleLogFilter

decorateLauncher

public Launcher decorateLauncher(AbstractBuild build,
                                 Launcher launcher,
                                 BuildListener listener)
                          throws IOException,
                                 InterruptedException,
                                 Run.RunnerAbortedException

May be overridden but this will only take effect when used as a BuildWrapper on an AbstractProject.

Provides an opportunity for a BuildWrapper to decorate a Launcher to be used in the build.

This hook is called very early on in the build (even before BuildWrapper.setUp(AbstractBuild, Launcher, BuildListener) is invoked.) The typical use of Launcher decoration involves in modifying the environment that processes run, such as the use of sudo/pfexec/chroot, or manipulating environment variables.

The default implementation is no-op, which just returns the launcher parameter as-is.

Overrides:

decorateLauncher in class BuildWrapper

Parameters:

build - The build in progress for which this BuildWrapper is called. Never null.

launcher - The default launcher. Never null. This method is expected to wrap this launcher. This makes sure that when multiple BuildWrappers attempt to decorate the same launcher it will sort of work. But if you are developing a plugin where such collision is not a concern, you can also simply discard this Launcher and create an entirely different Launcher and return it, too.

listener - Connected to the build output. Never null. Can be used for error reporting.

Returns:

Must not be null. If a fatal error happens, throw an exception.

Throws:

Run.RunnerAbortedException - If a fatal error is detected but the implementation handled it gracefully, throw this exception to suppress stack trace.

IOException

InterruptedException

Since:

1.608

See Also:

LauncherDecorator

makeBuildVariables

public void makeBuildVariables(AbstractBuild build,
                               Map<String,String> variables)

May be overridden but this will only take effect when used as a BuildWrapper on an AbstractProject.

Called to define AbstractBuild.getBuildVariables(). This provides an opportunity for a BuildWrapper to append any additional build variables defined for the current build.

Overrides:

makeBuildVariables in class BuildWrapper

Parameters:

build - The build in progress for which this BuildWrapper is called. Never null.

variables - Contains existing build variables. Add additional build variables that you contribute to this map.

Since:

1.608

makeSensitiveBuildVariables

public void makeSensitiveBuildVariables(AbstractBuild build,
                                        Set<String> sensitiveVariables)

May be overridden but this will only take effect when used as a BuildWrapper on an AbstractProject.

Called to define sensitive build variables. This provides an opportunity for a BuildWrapper to denote the names of variables that are sensitive in nature and should not be exposed in output.

Overrides:

makeSensitiveBuildVariables in class BuildWrapper

Parameters:

build - The build in progress for which this BuildWrapper is called. Never null.

sensitiveVariables - Contains names of sensitive build variables. Names of sensitive variables that were added with BuildWrapper.makeBuildVariables(hudson.model.AbstractBuild, java.util.Map)

Since:

1.608

getProjectActions

public final Collection<? extends Action> getProjectActions(AbstractProject job)

Description copied from class: BuildWrapper

Actions to be displayed in the job page.

Overrides:

getProjectActions in class BuildWrapper

Parameters:

job - This object owns the BuildWrapper. The returned action will be added to this object.

Returns:

an empty set; this might never be called if the step is not part of the static configuration of a project; instead, add a SimpleBuildStep.LastBuildAction to a build when run