public interface BuildStep
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.)
Build steps are instantiated when the user saves the job configuration, and sticks around in memory until the job configuration is overwritten.
Modifier and Type | Interface and Description |
---|---|
static class |
BuildStep.PublisherList
List of publisher descriptor.
|
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. |
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)
|
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.
|
@Deprecated static final List<Descriptor<Builder>> BUILDERS
Builder.all()
for read access, and use
Extension
for registration.@Deprecated static final BuildStep.PublisherList PUBLISHERS
Publisher.all()
for read access, and use
Extension
for registration.boolean prebuild(AbstractBuild<?,?> build, BuildListener listener)
Using the return value to indicate success/failure should
be considered deprecated, and implementations are encouraged
to throw AbortException
to indicate a failure.
boolean perform(AbstractBuild<?,?> build, Launcher launcher, BuildListener listener) throws InterruptedException, IOException
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.
Using the return value to indicate success/failure should
be considered deprecated, and implementations are encouraged
to throw AbortException
to indicate a failure.
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.@Deprecated Action getProjectAction(AbstractProject<?,?> project)
getProjectActions(AbstractProject)
instead.@NonNull Collection<? extends Action> getProjectActions(AbstractProject<?,?> project)
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.
default BuildStepMonitor getRequiredMonitorService()
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
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
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
CheckPoint
s
to perform necessary synchronizations.
If you are migrating BuildStep
implementations written for earlier versions of Hudson,
here's what you can do:
Run.getPreviousBuild()
), then you can return BuildStepMonitor.NONE
without making further
code changes and you are done with migration.
Action
s 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.
BuildStepMonitor.NONE
and use
CheckPoint
s directly in your code. The general idea is to call CheckPoint.block()
before
you try to access the state from the previous build.
Copyright © 2004–2021. All rights reserved.