Package hudson.model

Class JobProperty<J extends Job<?,?>>

java.lang.Object
hudson.model.JobProperty<J>
Type Parameters:
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).
All Implemented Interfaces:
ExtensionPoint, Describable<JobProperty<?>>, ReconfigurableDescribable<JobProperty<?>>, BuildStep
Direct Known Subclasses:
OptionalJobProperty
@ExportedBean public abstract class JobProperty<J extends Job<?,?>> extends Object implements ReconfigurableDescribable<JobProperty<?>>, BuildStep, ExtensionPoint
Extensible property of 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.

Since:
1.72
Author:
Kohsuke Kawaguchi
See Also:

  • Field Details

    • owner

      protected transient J extends Job<?,?> owner
      The Job object that owns this property. This value will be set by the Hudson code. Derived classes can expect this value to be always set.

  • Constructor Details

    • JobProperty

      public JobProperty()

  • Method Details

    • setOwner

      protected void setOwner(J owner)
      Hook for performing post-initialization action.

      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.

    • getDescriptor

      public JobPropertyDescriptor getDescriptor()
      Description copied from interface: Describable
      Gets the descriptor for this instance.

      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.)

      Specified by:
      getDescriptor in interface Describable<J extends Job<?,?>>

    • getJobAction

      @Deprecated public Action getJobAction(J job)
      Deprecated.
      as of 1.341. Override getJobActions(Job) instead.

    • getJobActions

      @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.

      Parameters:
      job - Always the same as owner but passed in anyway for backward compatibility (I guess.) You really need not use this value at all.
      Returns:
      can be empty but never null.
      Since:
      1.341
      See Also:

    • prebuild

      public boolean prebuild(AbstractBuild<?,?> build, BuildListener listener)
      Description copied from interface: BuildStep
      Runs before the build begins.
      Specified by:
      prebuild in interface BuildStep
      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

      public 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.

      Invoked after Publishers have run.

      Specified by:
      perform in interface BuildStep
      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.

    • getRequiredMonitorService

      public BuildStepMonitor getRequiredMonitorService()
      Returns BuildStepMonitor.NONE by default, as JobPropertys normally don't depend on its previous result.
      Specified by:
      getRequiredMonitorService in interface BuildStep

    • getProjectAction

      public final Action getProjectAction(AbstractProject<?,?> project)
      Specified by:
      getProjectAction in interface BuildStep

    • getProjectActions

      @NonNull public final Collection<? extends Action> getProjectActions(AbstractProject<?,?> project)
      Description copied from interface: BuildStep
      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.

      Specified by:
      getProjectActions in interface BuildStep
      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.

    • getJobOverrides

      public Collection<?> getJobOverrides()
      See Also:

    • reconfigure

      public JobProperty<?> reconfigure(org.kohsuke.stapler.StaplerRequest2 req, net.sf.json.JSONObject form) throws Descriptor.FormException
      Description copied from interface: ReconfigurableDescribable
      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.

      The default implementation of this should be the following: 

       return form==null ? null : getDescriptor().newInstance(req, form);
      Specified by:
      reconfigure in interface ReconfigurableDescribable<J extends Job<?,?>>
      Parameters:
      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.
      Returns:
      The new instance. To not to create an instance of a describable, return null.
      Throws:
      Descriptor.FormException
      Since:
      2.475

    • reconfigure

      @Deprecated public JobProperty<?> reconfigure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject form) throws Descriptor.FormException
      Deprecated.
      use reconfigure(StaplerRequest2, JSONObject)
      Specified by:
      reconfigure in interface ReconfigurableDescribable<J extends Job<?,?>>
      Throws:
      Descriptor.FormException

    • getSubTasks

      public Collection<? extends SubTask> getSubTasks()
      Contributes SubTasks to AbstractProject.getSubTasks()
      Since:
      1.377