Package 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

  • Field Details

  • Method Details

    • 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.getAuthentication2() is ACL.SYSTEM2, and if so, replace it for the duration of this step with Jenkins.ANONYMOUS. (Either using ACL.impersonate2(org.springframework.security.core.Authentication), or by making explicit calls to ACL.hasPermission2(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 Implementations: 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