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 Jobs. JobPropertys 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 JobPropertys
can add actions to the new build. The perform(AbstractBuild, Launcher, BuildListener)
and prebuild(AbstractBuild, BuildListener) are invoked after those
of Publishers.
Consider extending OptionalJobProperty instead.
JobPropertyDescriptorBuildStep.PublisherListExtensionPoint.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)
Actions 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 JobPropertys normally don't depend
on its previous result. |
Collection<? extends SubTask> |
getSubTasks()
Contributes
SubTasks 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)
Actions 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,
PermalinkProjectActionpublic boolean prebuild(AbstractBuild<?,?> build, BuildListener listener)
BuildStepprebuild 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 Publishers 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 JobPropertys normally don't depend
on its previous result.getRequiredMonitorService in interface BuildSteppublic final Action getProjectAction(AbstractProject<?,?> project)
getProjectAction in interface BuildStep@NonNull public final Collection<? extends Action> getProjectActions(AbstractProject<?,?> project)
BuildStepBuildStep 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 BuildStepproject - 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
ReconfigurableDescribableThe 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.FormExceptionpublic Collection<? extends SubTask> getSubTasks()
SubTasks to AbstractProject.getSubTasks()Copyright © 2004–2022. All rights reserved.