hudson.tasks
Interface BuildStep

All Known Implementing Classes:
AggregatedTestResultPublisher, Ant, ArtifactArchiver, AuthorizationMatrixProperty, BatchFile, Builder, BuildStepCompatibilityLayer, BuildTrigger, CommandInterpreter, Fingerprinter, JavadocArchiver, JobProperty, JUnitResultArchiver, Mailer, Maven, Notifier, 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.)

Author:
Kohsuke Kawaguchi

Nested Class Summary
static class BuildStep.PublisherList
          List of publisher descriptor.
 
Field Summary
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
 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.
 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

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

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.

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

Returns:
true if the build can continue, false if there was an error and the build needs to be aborted.
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

Action getProjectAction(AbstractProject<?,?> project)
Deprecated. as of 1.341. Use getProjectActions(AbstractProject) instead.


getProjectActions

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

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:

Note to caller

For plugins written against earlier versions of Hudson, calling this method results in AbstractMethodError.

Since:
1.319


Copyright © 2004-2013 Hudson. All Rights Reserved.