hudson.tasks
Class BuildWrapper

java.lang.Object
  extended by hudson.model.AbstractDescribableImpl<BuildWrapper>
      extended by hudson.tasks.BuildWrapper
All Implemented Interfaces:
ExtensionPoint, Describable<BuildWrapper>

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.

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

Author:
Kohsuke Kawaguchi

Nested Class Summary
 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
BuildWrapper()
           
 
Method Summary
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.
 BuildWrapper.Environment setUp(AbstractBuild build, Launcher launcher, BuildListener listener)
          Runs before the Builder runs, and performs a set up.
 BuildWrapper.Environment setUp(Build build, Launcher launcher, BuildListener listener)
          Deprecated. since 2007-10-28. Use setUp(AbstractBuild, Launcher, BuildListener) instead.
 
Methods inherited from class hudson.model.AbstractDescribableImpl
getDescriptor
 
Methods inherited from class java.lang.Object
equals, 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, 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. Hudson will handle the exception and reports a nice error message.
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:
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.

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

getProjectAction

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.



Copyright © 2004-2013 Hudson. All Rights Reserved.