Package hudson.tasks

Class BuildWrapper

java.lang.Object

hudson.model.AbstractDescribableImpl<BuildWrapper>

hudson.tasks.BuildWrapper

All Implemented Interfaces:

ExtensionPoint, Describable<BuildWrapper>

Direct Known Subclasses:

SimpleBuildWrapper

public abstract class BuildWrapper
extends AbstractDescribableImpl<BuildWrapper>
implements ExtensionPoint

Pluggability point for performing pre/post actions for the build process.

This extension point enables a plugin to set up / tear down additional services needed to perform a build, such as setting up local X display, or launching and stopping application servers for testing.

An instance of BuildWrapper is associated with a Project with configuration information as its state. An instance is persisted along with Project.

BuildWrappers are instantiated when the user saves the job configuration, and sticks around in memory until the job configuration is overwritten.

The setUp(Build,Launcher,BuildListener) method is invoked for each build.

BuildWrapper requires an user consent (in terms of a checkbox) to work. If this is not desirable, see Environment for other ways to inject Environments to builds.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	BuildWrapper.Environment	Represents the environment set up by setUp(Build,Launcher,BuildListener).

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
BuildWrapper()

Method Summary

Modifier and Type	Method	Description
static DescriptorExtensionList<BuildWrapper,Descriptor<BuildWrapper>>	all()	Returns all the registered BuildWrapper descriptors.
Launcher	decorateLauncher(AbstractBuild build, Launcher launcher, BuildListener listener)	Provides an opportunity for a BuildWrapper to decorate a Launcher to be used in the build.
OutputStream	decorateLogger(AbstractBuild build, OutputStream logger)	Provides an opportunity for a BuildWrapper to decorate the BuildListener logger to be used by the build.
Action	getProjectAction(AbstractProject job)	Deprecated. Use getProjectActions(AbstractProject) instead.
Collection<? extends Action>	getProjectActions(AbstractProject job)	Actions to be displayed in the job page.
void	makeBuildVariables(AbstractBuild build, Map<String,String> variables)	Called to define AbstractBuild.getBuildVariables().
void	makeSensitiveBuildVariables(AbstractBuild build, Set<String> sensitiveVariables)	Called to define sensitive build variables.
void	preCheckout(AbstractBuild build, Launcher launcher, BuildListener listener)	Provides an opportunity for a BuildWrapper to perform some actions before SCM checkout.
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.
BuildWrapper.Environment	setUp(Build build, Launcher launcher, BuildListener listener)	Deprecated. since 2007-10-28.

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

BuildWrapper

public BuildWrapper()

Method Detail

setUp

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

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

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.

UnsupportedOperationException - when a plugin does not support this type of build.

InterruptedException

Since:

1.150

setUp

@Deprecated
public BuildWrapper.Environment setUp(Build build,
                                      Launcher launcher,
                                      BuildListener listener)
                               throws IOException,
                                      InterruptedException

Deprecated.

since 2007-10-28. Use setUp(AbstractBuild, Launcher, BuildListener) instead.

Throws:

AbstractMethodError - when a plugin overrides neither this method nor setUp(AbstractBuild, Launcher, BuildListener).

IOException

InterruptedException

decorateLauncher

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

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 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.

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.280

See Also:

LauncherDecorator

decorateLogger

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

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 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.)

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

Since:

1.374

See Also:

ConsoleLogFilter

preCheckout

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

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

This hook is called early on in the build (before setUp(AbstractBuild, Launcher, BuildListener), but after 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.

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

Since:

1.399

getProjectAction

@Deprecated
public Action getProjectAction(AbstractProject job)

Deprecated.

Use getProjectActions(AbstractProject) instead.

Action to be displayed in the job page.

Parameters:

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

Returns:

null if there's no such action.

Since:

1.226

getProjectActions

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

Actions to be displayed in the job page.

Parameters:

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

Returns:

can be empty but never null

Since:

1.341

makeBuildVariables

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

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

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.

makeSensitiveBuildVariables

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

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.

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 makeBuildVariables(hudson.model.AbstractBuild, java.util.Map)

Since:

1.378

all

public static DescriptorExtensionList<BuildWrapper,Descriptor<BuildWrapper>> all()

Returns all the registered BuildWrapper descriptors.