Package hudson.model

Class Job<JobT extends Job<JobT,RunT>,RunT extends Run<JobT,RunT>>

java.lang.Object
hudson.model.AbstractModelObject
hudson.model.Actionable
hudson.model.AbstractItem
hudson.model.Job<JobT,RunT>
All Implemented Interfaces:
ExtensionPoint, DescriptorByNameOwner, Item, ModelObject, PersistenceRoot, Saveable, SearchableModelObject, SearchItem, AccessControlled, FullyNamed, FullyNamedModelObject, Loadable, ModelObjectWithChildren, ModelObjectWithContextMenu, Named, OnMaster, HasWidgets, org.kohsuke.stapler.HttpDeletable, org.kohsuke.stapler.StaplerOverridable, org.kohsuke.stapler.StaplerProxy
Direct Known Subclasses:
AbstractProject, ViewJob
public abstract class Job<JobT extends Job<JobT,RunT>,RunT extends Run<JobT,RunT>> extends AbstractItem implements ExtensionPoint, org.kohsuke.stapler.StaplerOverridable, ModelObjectWithChildren, HasWidgets
A job is an runnable entity under the monitoring of Hudson.

Every time it "runs", it will be recorded as a Run object.

To create a custom job type, extend TopLevelItemDescriptor and put Extension on it.

Author:
Kohsuke Kawaguchi

  • Field Details

    • nextBuildNumber

      protected transient volatile int nextBuildNumber
      Next build number. Kept in a separate file because this is the only information that gets updated often. This allows the rest of the configuration to be in the VCS.

      In 1.28 and earlier, this field was stored in the project configuration file, so even though this is marked as transient, don't move it around.

    • properties

      protected CopyOnWriteList<JobProperty<? super JobT extends Job<JobT,RunT>>> properties
      List of properties configured for this project.

    • HISTORY_ADAPTER

      public static final HistoryWidget.Adapter<HistoricalBuild> HISTORY_ADAPTER

  • Constructor Details

  • Method Details

    • save

      public void save() throws IOException
      Description copied from class: AbstractItem
      Save the settings to a file.
      Specified by:
      save in interface Item
      Specified by:
      save in interface Saveable
      Overrides:
      save in class AbstractItem
      Throws:
      IOException - if the persistence failed.

    • onLoad

      public void onLoad(ItemGroup<? extends Item> parent, String name) throws IOException
      Description copied from class: AbstractItem
      Called right after when a Item is loaded from disk. This is an opportunity to do a post load processing.
      Specified by:
      onLoad in interface Item
      Overrides:
      onLoad in class AbstractItem
      Parameters:
      name - Name of the directory (not a path --- just the name portion) from which the configuration was loaded. This usually becomes the name of this item.
      Throws:
      IOException

    • onCopiedFrom

      public void onCopiedFrom(Item src)
      Description copied from class: AbstractItem
      When a Item is copied from existing one, the files are first copied on the file system, then it will be loaded, then this method will be invoked to perform any implementation-specific work.
      Specified by:
      onCopiedFrom in interface Item
      Overrides:
      onCopiedFrom in class AbstractItem
      Parameters:
      src - Item from which it's copied from. The same type as this. Never null.

    • isHoldOffBuildUntilSave

      public boolean isHoldOffBuildUntilSave()

    • saveNextBuildNumber

      protected void saveNextBuildNumber() throws IOException
      Throws:
      IOException

    • isInQueue

      @Exported public boolean isInQueue()

    • getQueueItem

      @Exported public Queue.Item getQueueItem()
      If this job is in the build queue, return its item.

    • isBuilding

      public boolean isBuilding()
      Returns true if a build of this project is in progress.

    • isLogUpdated

      public boolean isLogUpdated()
      Returns true if the log file is still being updated.

    • getPronoun

      public String getPronoun()
      Description copied from class: AbstractItem
      Get the term used in the UI to represent this kind of Item. Must start with a capital letter.
      Overrides:
      getPronoun in class AbstractItem

    • isNameEditable

      public boolean isNameEditable()
      Returns whether the name of this job can be changed by user.
      Overrides:
      isNameEditable in class AbstractItem
      Returns:
      whether AbstractItem.name can be modified by a user
      See Also:

    • isKeepDependencies

      @Exported public boolean isKeepDependencies()
      If true, it will keep all the build logs of dependency components. (This really only makes sense in AbstractProject but historically it was defined here.)

    • assignBuildNumber

      public int assignBuildNumber() throws IOException
      Allocates a new build number.
      Throws:
      IOException
      See Also:

    • getNextBuildNumber

      @Exported public int getNextBuildNumber()
      Peeks the next build number.

    • getCharacteristicEnvVars

      public EnvVars getCharacteristicEnvVars()
      Builds up the environment variable map that's sufficient to identify a process as ours. This is used to kill run-away processes via ProcessTree.killAll(Map).

    • getEnvironment

      @NonNull public EnvVars getEnvironment(@CheckForNull Node node, @NonNull TaskListener listener) throws IOException, InterruptedException
      Creates an environment variable override for launching processes for this project.

      This is for process launching outside the build execution (such as polling, tagging, deployment, etc.) that happens in a context of a specific job.

      Parameters:
      node - Node to eventually run a process on. The implementation must cope with this parameter being null (in which case none of the node specific properties would be reflected in the resulting override.)
      Throws:
      IOException
      InterruptedException

    • updateNextBuildNumber

      public void updateNextBuildNumber(int next) throws IOException
      Programmatically updates the next build number.

      Much of Hudson assumes that the build number is unique and monotonic, so this method can only accept a new value that's bigger than getLastBuild() returns. Otherwise it'll be no-op.

      Throws:
      IOException
      Since:
      1.199 (before that, this method was package private.)

    • fastUpdateNextBuildNumber

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) public void fastUpdateNextBuildNumber(int nextBuildNumber)
      Unconditionally sets the value of getNextBuildNumber(). Unlike updateNextBuildNumber(int) this does not save the number on disk, and does not check getLastBuild().

    • getBuildDiscarder

      public BuildDiscarder getBuildDiscarder()
      Returns the configured build discarder for this job, via BuildDiscarderProperty, or null if none.

    • setBuildDiscarder

      public void setBuildDiscarder(BuildDiscarder bd) throws IOException
      Throws:
      IOException

    • getLogRotator

      @Deprecated public LogRotator getLogRotator()
      Deprecated.
      as of 1.503 Use getBuildDiscarder().
      Left for backward compatibility. Returns non-null if and only if LogRotator is configured as BuildDiscarder.

    • setLogRotator

      @Deprecated public void setLogRotator(LogRotator logRotator) throws IOException
      Deprecated.
      as of 1.503 Use setBuildDiscarder(BuildDiscarder)
      Throws:
      IOException

    • logRotate

      public void logRotate() throws IOException, InterruptedException
      Perform log rotation.
      Throws:
      IOException
      InterruptedException

    • supportsLogRotator

      public boolean supportsLogRotator()
      True if this instance supports log rotation configuration.

    • getSearchIcon

      public String getSearchIcon()
      Specified by:
      getSearchIcon in interface SearchItem

    • makeSearchIndex

      protected SearchIndexBuilder makeSearchIndex()
      Description copied from class: AbstractModelObject
      Default implementation that returns empty index.
      Overrides:
      makeSearchIndex in class AbstractModelObject

    • getAllJobs

      public Collection<? extends Job> getAllJobs()
      Description copied from class: AbstractItem
      Gets all the jobs that this Item contains as descendants.
      Specified by:
      getAllJobs in interface Item
      Specified by:
      getAllJobs in class AbstractItem

    • addProperty

      public void addProperty(JobProperty<? super JobT> jobProp) throws IOException
      Adds JobProperty.
      Throws:
      IOException
      Since:
      1.188

    • removeProperty

      public void removeProperty(JobProperty<? super JobT> jobProp) throws IOException
      Removes JobProperty
      Throws:
      IOException
      Since:
      1.279

    • removeProperty

      public <T extends JobProperty> T removeProperty(Class<T> clazz) throws IOException
      Removes the property of the given type.
      Returns:
      The property that was just removed.
      Throws:
      IOException
      Since:
      1.279

    • getProperties

      public Map<JobPropertyDescriptor,JobProperty<? super JobT>> getProperties()
      Gets all the job properties configured for this job.

    • getAllProperties

      @Exported(name="property", inline=true) public List<JobProperty<? super JobT>> getAllProperties()
      List of all JobProperty exposed primarily for the remoting API.
      Since:
      1.282

    • getProperty

      public <T extends JobProperty> T getProperty(Class<T> clazz)
      Gets the specific property, or null if the property is not configured for this job.

    • getProperty

      public JobProperty getProperty(String className)
      Bind JobPropertys to URL spaces.
      Since:
      1.403

    • getOverrides

      public Collection<?> getOverrides()
      Overrides from job properties.
      Specified by:
      getOverrides in interface org.kohsuke.stapler.StaplerOverridable
      See Also:

    • createHistoryWidget

      @Deprecated(forRemoval=true, since="2.410") protected HistoryWidget createHistoryWidget()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Remove any override, history widget is now created via WidgetFactory implementation.

    • renameTo

      public void renameTo(String newName) throws IOException
      Renames a job.
      Overrides:
      renameTo in class AbstractItem
      Throws:
      IOException

    • movedTo

      public void movedTo(DirectlyModifiableTopLevelItemGroup destination, AbstractItem newItem, File destDir) throws IOException
      Description copied from class: AbstractItem
      Notify this item it's been moved to another location, replaced by newItem (might be the same object, but not guaranteed). This method is executed after the item root directory has been moved to it's new location.

      Derived classes can override this method to add some specific behavior on move, but have to call parent method so the item is actually setup within it's new parent.

      Overrides:
      movedTo in class AbstractItem
      Throws:
      IOException
      See Also:

    • delete

      public void delete() throws IOException, InterruptedException
      Description copied from class: AbstractItem
      Deletes this item.

      Any exception indicates the deletion has failed, but AbortException would prevent the caller from showing the stack trace.

      Specified by:
      delete in interface Item
      Overrides:
      delete in class AbstractItem
      Throws:
      IOException
      InterruptedException
      See Also:

    • isBuildable

      @Exported public abstract boolean isBuildable()
      Returns true if we should display "build now" icon

    • getBuilds

      @Exported(name="allBuilds", visibility=-2) @WithBridgeMethods(java.util.List.class) public RunList<RunT> getBuilds()
      Gets the read-only view of all the builds.
      Returns:
      never null. The first entry is the latest build.

    • getNewBuilds

      @Exported(name="builds") public RunList<RunT> getNewBuilds()
      Gets the read-only view of the recent builds.
      Since:
      1.485

    • getBuilds

      public List<RunT> getBuilds(Fingerprint.RangeSet rs)
      Obtains all the Runs whose build numbers matches the given Fingerprint.RangeSet.

    • getBuildsAsMap

      public SortedMap<Integer,RunT> getBuildsAsMap()
      Gets all the builds in a map.

    • getBuild

      public RunT getBuild(String id)
      Looks up a build by its ID.
      See Also:

    • getBuildByNumber

      public RunT getBuildByNumber(int n)
      Parameters:
      n - The build number.
      Returns:
      null if no such build exists.
      See Also:

    • getBuildsByTimestamp

      @WithBridgeMethods(java.util.List.class) @Deprecated public RunList<RunT> getBuildsByTimestamp(long start, long end)
      Deprecated.
      as of 1.372. Should just do getBuilds().byTimestamp(s,e) to avoid code bloat in Job.
      Obtains a list of builds, in the descending order, that are within the specified time range [start,end).
      Returns:
      can be empty but never null.

    • getBuildForCLI

      @CLIResolver public RunT getBuildForCLI(String id) throws org.kohsuke.args4j.CmdLineException
      Throws:
      org.kohsuke.args4j.CmdLineException

    • getNearestBuild

      public RunT getNearestBuild(int n)
      Gets the oldest build #m that satisfies m ≥ n. This is useful when you'd like to fetch a build but the exact build might be already gone (deleted, rotated, etc.)
      See Also:

    • getNearestOldBuild

      public RunT getNearestOldBuild(int n)
      Gets the newest build #m that satisfies m ≤ n. This is useful when you'd like to fetch a build but the exact build might be already gone (deleted, rotated, etc.)
      See Also:

    • getDynamic

      public Object getDynamic(String token, org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp)
      Overrides:
      getDynamic in class Actionable
      Since:
      2.475

    • getBuildDir

      public File getBuildDir()
      Directory for storing Run records.

      Some Jobs may not have backing data store for Runs, but those Jobs that use file system for storing data should use this directory for consistency.

      See Also:

    • _getRuns

      protected abstract SortedMap<Integer,? extends RunT> _getRuns()
      Gets all the runs. The resulting map must be treated immutable (by employing copy-on-write semantics.) The map is descending order, with newest builds at the top.
      See Also:

    • removeRun

      protected abstract void removeRun(RunT run)
      Called from Run to remove it from this job. The files are deleted already. So all the callee needs to do is to remove a reference from this Job.
      See Also:

    • getLastBuild

      @Exported public RunT getLastBuild()
      Returns the newest build.
      See Also:

    • getFirstBuild

      @Exported public RunT getFirstBuild()
      Returns the oldest build in the record.
      See Also:

    • getLastSuccessfulBuild

      @Exported public RunT getLastSuccessfulBuild()
      Returns the last successful build, if any. Otherwise null. A successful build would include either Result.SUCCESS or Result.UNSTABLE.
      See Also:

    • getLastUnsuccessfulBuild

      @Exported public RunT getLastUnsuccessfulBuild()
      Returns the last build that was anything but stable, if any. Otherwise null.
      See Also:

    • getLastUnstableBuild

      @Exported public RunT getLastUnstableBuild()
      Returns the last unstable build, if any. Otherwise null.
      See Also:

    • getLastStableBuild

      @Exported public RunT getLastStableBuild()
      Returns the last stable build, if any. Otherwise null.
      See Also:

    • getLastFailedBuild

      @Exported public RunT getLastFailedBuild()
      Returns the last failed build, if any. Otherwise null.

    • getLastCompletedBuild

      @Exported public RunT getLastCompletedBuild()
      Returns the last completed build, if any. Otherwise null.

    • getLastBuildsOverThreshold

      public List<RunT> getLastBuildsOverThreshold(int numberOfBuilds, Result threshold)
      Returns the last numberOfBuilds builds with a build result ≥ threshold
      Returns:
      a list with the builds. May be smaller than 'numberOfBuilds' or even empty if not enough builds satisfying the threshold have been found. Never null.

    • getEstimatedDurationCandidates

      protected List<RunT> getEstimatedDurationCandidates()
      Returns candidate build for calculating the estimated duration of the current run. Returns the 3 last successful (stable or unstable) builds, if there are any. Failing to find 3 of those, it will return up to 3 last unsuccessful builds. In any case it will not go more than 6 builds into the past to avoid costly build loading.
      See Also:

    • getEstimatedDuration

      public long getEstimatedDuration()

    • getPermalinks

      public PermalinkList getPermalinks()
      Gets all the PermalinkProjectAction.Permalinks defined for this job.
      Returns:
      never null

    • doRssChangelog

      public void doRssChangelog(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      RSS feed for changes in this project.
      Throws:
      IOException
      jakarta.servlet.ServletException
      Since:
      2.60

    • doChildrenContextMenu

      public ModelObjectWithContextMenu.ContextMenu doChildrenContextMenu(org.kohsuke.stapler.StaplerRequest2 request, org.kohsuke.stapler.StaplerResponse2 response) throws Exception
      Description copied from interface: ModelObjectWithChildren
      Generates the context menu to list up all the children.
      Specified by:
      doChildrenContextMenu in interface ModelObjectWithChildren
      Throws:
      Exception
      Since:
      2.475

    • doChildrenContextMenu

      @Deprecated @StaplerNotDispatchable public ModelObjectWithContextMenu.ContextMenu doChildrenContextMenu(org.kohsuke.stapler.StaplerRequest request, org.kohsuke.stapler.StaplerResponse response) throws Exception
      Deprecated.
      use doChildrenContextMenu(StaplerRequest2, StaplerResponse2)
      Specified by:
      doChildrenContextMenu in interface ModelObjectWithChildren
      Throws:
      Exception

    • getIconColor

      @Exported(visibility=2, name="color") public BallColor getIconColor()
      Used as the color of the status ball for the project.

    • getBuildHealth

      public HealthReport getBuildHealth()
      Get the current health report for a job.
      Returns:
      the health report. Never returns null

    • getBuildHealthReports

      @Exported(name="healthReport") public List<HealthReport> getBuildHealthReports()

    • doConfigSubmit

      @POST public void doConfigSubmit(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException, Descriptor.FormException
      Accepts submission from the configuration page.
      Throws:
      IOException
      jakarta.servlet.ServletException
      Descriptor.FormException

    • submit

      protected void submit(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException, Descriptor.FormException
      Derived class can override this to perform additional config submission work.
      Throws:
      IOException
      jakarta.servlet.ServletException
      Descriptor.FormException
      Since:
      2.475

    • submit

      @Deprecated protected void submit(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException, Descriptor.FormException
      Deprecated.
      use submit(StaplerRequest2, StaplerResponse2)
      Throws:
      IOException
      javax.servlet.ServletException
      Descriptor.FormException

    • doDescription

      public void doDescription(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException
      Accepts and serves the job description
      Throws:
      IOException

    • doBuildStatus

      public void doBuildStatus(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException
      Returns the image that shows the current buildCommand status.
      Throws:
      IOException

    • getBuildStatusUrl

      public String getBuildStatusUrl()

    • getBuildStatusIconClassName

      public String getBuildStatusIconClassName()

    • getBuildTimeGraph

      public Graph getBuildTimeGraph()

    • doDoRename

      @Deprecated public void doDoRename(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException
      Deprecated.
      Exists for backwards compatibility, use AbstractItem.doConfirmRename(java.lang.String) instead.
      Renames this job.
      Throws:
      IOException
      javax.servlet.ServletException

    • checkRename

      protected void checkRename(String newName) throws Failure
      Description copied from class: AbstractItem
      Allows subclasses to block renames for domain-specific reasons. Generic validation of the new name (e.g., null checking, checking for illegal characters, and checking that the name is not in use) always happens prior to calling this method.
      Overrides:
      checkRename in class AbstractItem
      Parameters:
      newName - the new name for the item
      Throws:
      Failure - if the rename should be blocked
      See Also:

    • doRssAll

      public void doRssAll(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      Throws:
      IOException
      jakarta.servlet.ServletException

    • doRssFailed

      public void doRssFailed(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      Throws:
      IOException
      jakarta.servlet.ServletException

    • getACL

      public ACL getACL()
      Returns the ACL for this object. We need to override the identical method in AbstractItem because we won't call getACL(Job) otherwise (single dispatch)
      Specified by:
      getACL in interface AccessControlled
      Overrides:
      getACL in class AbstractItem
      Returns:
      never null.

    • getTimeline

      @Deprecated @Restricted(org.kohsuke.accmod.restrictions.DoNotUse.class) public BuildTimelineWidget getTimeline()
      Deprecated.