J
- When you restrict your job property to be only applicable to a certain
subtype of Job
, you can use this type parameter to improve
the type signature of this class. See JobPropertyDescriptor.isApplicable(Class)
.@ExportedBean public abstract class JobProperty<J extends Job<?,?>> extends Object implements ReconfigurableDescribable<JobProperty<?>>, BuildStep, ExtensionPoint
Job
.
Plugins can extend this to define custom properties
for Job
s. JobProperty
s show up in the user
configuration screen, and they are persisted with the job object.
Configuration screen should be defined in config.jelly
.
Within this page, the JobProperty
instance is available
as instance
variable (while it
refers to Job
.
Starting 1.150, JobProperty
implements BuildStep
,
meaning it gets the same hook as Publisher
and Builder
.
The primary intention of this mechanism is so that JobProperty
s
can add actions to the new build. The perform(AbstractBuild, Launcher, BuildListener)
and prebuild(AbstractBuild, BuildListener)
are invoked after those
of Publisher
s.
Consider extending OptionalJobProperty
instead.
JobPropertyDescriptor
BuildStep.PublisherList
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
protected J |
owner
The
Job object that owns this property. |
BUILDERS, PUBLISHERS
Constructor and Description |
---|
JobProperty() |
Modifier and Type | Method and Description |
---|---|
JobPropertyDescriptor |
getDescriptor()
Gets the descriptor for this instance.
|
Action |
getJobAction(J job)
Deprecated.
as of 1.341. Override
getJobActions(Job) instead. |
Collection<? extends Action> |
getJobActions(J job)
Action s to be displayed in the job page. |
Collection<?> |
getJobOverrides() |
Action |
getProjectAction(AbstractProject<?,?> project) |
Collection<? extends Action> |
getProjectActions(AbstractProject<?,?> project)
|
BuildStepMonitor |
getRequiredMonitorService()
Returns
BuildStepMonitor.NONE by default, as JobProperty s normally don't depend
on its previous result. |
Collection<? extends SubTask> |
getSubTasks()
Contributes
SubTask s to AbstractProject.getSubTasks() |
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.
|
JobProperty<?> |
reconfigure(org.kohsuke.stapler.StaplerRequest req,
net.sf.json.JSONObject form)
When a parent/owner object of a Describable gets a config form submission and instances are
recreated, this method is invoked on the existing instance (meaning the 'this' reference
points to the existing instance) to create a new instance to be added to the parent/owner object.
|
protected void |
setOwner(J owner)
Hook for performing post-initialization action.
|
protected void setOwner(J owner)
This method is invoked in two cases. One is when the Job
that owns
this property is loaded from disk, and the other is when a job is re-configured
and all the JobProperty
instances got re-created.
public JobPropertyDescriptor getDescriptor()
Describable
Descriptor
is a singleton for every concrete Describable
implementation, so if a.getClass() == b.getClass()
then by default
a.getDescriptor() == b.getDescriptor()
as well.
(In rare cases a single implementation class may be used for instances with distinct descriptors.)
getDescriptor
in interface Describable<JobProperty<?>>
@Deprecated public Action getJobAction(J job)
getJobActions(Job)
instead.@NonNull public Collection<? extends Action> getJobActions(J job)
Action
s to be displayed in the job page.
Returning actions from this method allows a job property to add them to the left navigation bar in the job page.
Action
can implement additional marker interface to integrate
with the UI in different ways.
job
- Always the same as owner
but passed in anyway for backward compatibility (I guess.)
You really need not use this value at all.ProminentProjectAction
,
PermalinkProjectAction
public boolean prebuild(AbstractBuild<?,?> build, BuildListener listener)
BuildStep
prebuild
in interface BuildStep
Using the return value to indicate success/failure should
be considered deprecated, and implementations are encouraged
to throw AbortException
to indicate a failure.
public 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.
Invoked after Publisher
s have run.
perform
in interface BuildStep
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.public BuildStepMonitor getRequiredMonitorService()
BuildStepMonitor.NONE
by default, as JobProperty
s normally don't depend
on its previous result.getRequiredMonitorService
in interface BuildStep
public final Action getProjectAction(AbstractProject<?,?> project)
getProjectAction
in interface BuildStep
@NonNull public final Collection<? extends Action> getProjectActions(AbstractProject<?,?> project)
BuildStep
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.
getProjectActions
in interface BuildStep
project
- Project
that owns this build step,
since BuildStep
object doesn't usually have this "parent" pointer.public Collection<?> getJobOverrides()
Job.getOverrides()
public JobProperty<?> reconfigure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject form) throws Descriptor.FormException
ReconfigurableDescribable
The default implementation of this should be the following:
return form==null ? null : getDescriptor().newInstance(req, form);
reconfigure
in interface ReconfigurableDescribable<JobProperty<?>>
req
- The current HTTP request being processed.form
- JSON fragment that corresponds to this describable object.
If the newly submitted form doesn't include a fragment for this describable
(meaning the user has de-selected your descriptor), then this argument is null.Descriptor.FormException
public Collection<? extends SubTask> getSubTasks()
SubTask
s to AbstractProject.getSubTasks()
Copyright © 2004–2022. All rights reserved.