hudson.tasks

Interface BuildStep

All Known Subinterfaces:

SimpleBuildStep

All Known Implementing Classes:

ArtifactArchiver, BatchFile, BuildDiscarderProperty, Builder, BuildStepCompatibilityLayer, BuildTrigger, CommandInterpreter, Fingerprinter, JobProperty, Maven, Notifier, OptionalJobProperty, ParametersDefinitionProperty, Publisher, Recorder, Shell

public interface BuildStep

One step of the whole build process.

Persistence

These objects are persisted as a part of Project by XStream. The save operation happens without any notice, and the restore operation happens without calling the constructor, just like Java serialization.

So generally speaking, derived classes should use instance variables only for keeping configuration. You can still store objects you use for processing, like a parser of some sort, but they need to be marked as transient, and the code needs to be aware that they might be null (which is the case when you access the field for the first time the object is restored.)

Lifecycle

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

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	BuildStep.PublisherList List of publisher descriptor.

Field Summary

Fields

Modifier and Type	Field and Description
static List<Descriptor<Builder>>	BUILDERS Deprecated. as of 1.286. Use Builder.all() for read access, and use Extension for registration.
static BuildStep.PublisherList	PUBLISHERS Deprecated. as of 1.286. Use Publisher.all() for read access, and use Extension for registration.

Method Summary

Modifier and Type	Method and Description
Action	getProjectAction(AbstractProject<?,?> project) Deprecated. as of 1.341. Use getProjectActions(AbstractProject) instead.
Collection<? extends Action>	getProjectActions(AbstractProject<?,?> project) Returns action objects if this BuildStep has actions to contribute to a Project.
default BuildStepMonitor	getRequiredMonitorService() Declares the scope of the synchronization monitor this BuildStep expects from outside.
boolean	perform(AbstractBuild<?,?> build, Launcher launcher, BuildListener listener) Runs the step over the given build and reports the progress to the listener.
boolean	prebuild(AbstractBuild<?,?> build, BuildListener listener) Runs before the build begins.

Field Detail

BUILDERS

@Deprecated
static final List<Descriptor<Builder>> BUILDERS

Deprecated. as of 1.286. Use Builder.all() for read access, and use Extension for registration.

List of all installed builders. Builders are invoked to perform the build itself.

PUBLISHERS

@Deprecated
static final BuildStep.PublisherList PUBLISHERS

Deprecated. as of 1.286. Use Publisher.all() for read access, and use Extension for registration.

List of all installed publishers. Publishers are invoked after the build is completed, normally to perform some post-actions on build results, such as sending notifications, collecting results, etc.

See Also:

BuildStep.PublisherList.addNotifier(Descriptor), BuildStep.PublisherList.addRecorder(Descriptor)

Method Detail

prebuild

boolean prebuild(AbstractBuild<?,?> build,
                 BuildListener listener)

Runs before the build begins.

Returns:

true if the build can continue, false if there was an error and the build needs to be aborted.

Using the return value to indicate success/failure should be considered deprecated, and implementations are encouraged to throw AbortException to indicate a failure.

perform

boolean perform(AbstractBuild<?,?> build,
                Launcher launcher,
                BuildListener listener)
         throws InterruptedException,
                IOException

Runs the step over the given build and reports the progress to the listener.

A plugin can contribute the action object to Actionable.getActions() so that a 'report' becomes a part of the persisted data of Build. This is how JUnit plugin attaches the test report to a build page, for example.

When this build step needs to make (direct or indirect) permission checks to ACL (for example, to locate other projects by name, build them, or access their artifacts) then it must be run under a specific Authentication. In such a case, the implementation should check whether Jenkins.getAuthentication() is ACL.SYSTEM, and if so, replace it for the duration of this step with Jenkins.ANONYMOUS. (Either using ACL.impersonate(org.acegisecurity.Authentication), or by making explicit calls to ACL.hasPermission(Authentication, Permission).) This would typically happen when no QueueItemAuthenticator was available, configured, and active.

Returns:

true if the build can continue, false if there was an error and the build needs to be aborted.

Using the return value to indicate success/failure should be considered deprecated, and implementations are encouraged to throw AbortException to indicate a failure.

Throws:

InterruptedException - If the build is interrupted by the user (in an attempt to abort the build.) Normally the BuildStep implementations may simply forward the exception it got from its lower-level functions.

IOException - If the implementation wants to abort the processing when an IOException happens, it can simply propagate the exception to the caller. This will cause the build to fail, with the default error message. Implementations are encouraged to catch IOException on its own to provide a better error message, if it can do so, so that users have better understanding on why it failed.

getProjectAction

@Deprecated
Action getProjectAction(AbstractProject<?,?> project)

Deprecated. as of 1.341. Use getProjectActions(AbstractProject) instead.

getProjectActions

@Nonnull
Collection<? extends Action> getProjectActions(AbstractProject<?,?> project)

Returns action objects if this BuildStep has actions to contribute to a Project.

Project calls this method for every BuildStep that it owns when the rendering is requested.

This action can have optional jobMain.jelly view, which will be aggregated into the main panel of the job top page. The jelly file should have an <h2> tag that shows the section title, followed by some block elements to render the details of the section.

Parameters:

project - Project that owns this build step, since BuildStep object doesn't usually have this "parent" pointer.

Returns:

can be empty but never null.

getRequiredMonitorService

default BuildStepMonitor getRequiredMonitorService()

Declares the scope of the synchronization monitor this BuildStep expects from outside.

This method is introduced for preserving compatibility with plugins written for earlier versions of Hudson, which never run multiple builds of the same job in parallel. Such plugins often assume that the outcome of the previous build is completely available, which is no longer true when we do concurrent builds.

To minimize the necessary code change for such plugins, BuildStep implementations can request Hudson to externally perform synchronization before executing them. This behavior is as follows:

BuildStepMonitor.BUILD

This BuildStep is only executed after the previous build is fully completed (thus fully restoring the earlier semantics of one build at a time.)

BuildStepMonitor.STEP

This BuildStep is only executed after the same step in the previous build is completed. For build steps that use a weaker assumption and only rely on the output from the same build step of the early builds, this improves the concurrency.

BuildStepMonitor.NONE

No external synchronization is performed on this build step. This is the most efficient, and thus the recommended value for newer plugins. Wherever necessary, you can directly use CheckPoints to perform necessary synchronizations.

Migrating Older Implementation

If you are migrating BuildStep implementations written for earlier versions of Hudson, here's what you can do:

• To demand the backward compatible behavior from Jenkins, leave this method unoverridden, and make no other changes to the code. This will prevent users from reaping the benefits of concurrent builds, but at least your plugin will work correctly, and therefore this is a good easy first step.
• If your build step doesn't use anything from a previous build (for example, if you don't even call Run.getPreviousBuild()), then you can return BuildStepMonitor.NONE without making further code changes and you are done with migration.
• If your build step only depends on Actions that you added in the previous build by yourself, then you only need BuildStepMonitor.STEP scope synchronization. Return it from this method ,and you are done with migration without any further code changes.
• If your build step makes more complex assumptions, return BuildStepMonitor.NONE and use CheckPoints directly in your code. The general idea is to call CheckPoint.block() before you try to access the state from the previous build.

Since:

1.319