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, ModelObjectWithContextMenu, OnMaster, org.kohsuke.stapler.HttpDeletable, org.kohsuke.stapler.StaplerOverridable

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, OnMaster

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

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Nested classes/interfaces inherited from interface jenkins.model.ModelObjectWithContextMenu

ModelObjectWithContextMenu.ContextMenu, ModelObjectWithContextMenu.MenuItem

Field Summary

protected static HistoryWidget.Adapter<Run>	HISTORY_ADAPTER
protected int	nextBuildNumber Next build number.
protected CopyOnWriteList<JobProperty<? super JobT>>	properties List of UserPropertys configured for this project.

Fields inherited from class hudson.model.AbstractItem

description, displayName, name, PRONOUN

Fields inherited from interface hudson.model.Item

BUILD, CANCEL, CONFIGURE, CREATE, DELETE, DISCOVER, EXTENDED_READ, PERMISSIONS, READ, WIPEOUT, WORKSPACE

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

protected

Job(ItemGroup parent, String name)

Method Summary

protected abstract SortedMap<Integer,? extends RunT>	_getRuns() Gets all the runs.
void	addProperty(JobProperty<? super JobT> jobProp) Adds JobProperty.
int	assignBuildNumber() Allocates a new buildCommand number.
protected HistoryWidget	createHistoryWidget()
void	delete() Deletes this item.
void	doBuildStatus(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Returns the image that shows the current buildCommand status.
void	doConfigSubmit(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts submission from the configuration page.
void	doDescription(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts and serves the job description
void	doDoRename(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Renames this job.
void	doRssAll(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
void	doRssFailed(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
ACL	getACL() Returns the ACL for this object.
Collection<? extends Job>	getAllJobs() Gets all the jobs that this Item contains as descendants.
List<JobProperty<? super JobT>>	getAllProperties() List of all JobProperty exposed primarily for the remoting API.
RunT	getBuild(String id) Deprecated. since 2008-06-15. This is only used to support backward compatibility with old URLs.
RunT	getBuildByNumber(int n)
File	getBuildDir() Directory for storing Run records.
BuildDiscarder	getBuildDiscarder() Returns the configured build discarder for this job, or null if none.
RunT	getBuildForCLI(String id)
HealthReport	getBuildHealth() Get the current health report for a job.
List<HealthReport>	getBuildHealthReports()
RunList<RunT>	getBuilds() Gets the read-only view of all the builds.
List<RunT>	getBuilds(Fingerprint.RangeSet rs) Obtains all the Runs whose build numbers matches the given Fingerprint.RangeSet.
SortedMap<Integer,RunT>	getBuildsAsMap() Gets all the builds in a map.
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.
String	getBuildStatusUrl()
Graph	getBuildTimeGraph()
EnvVars	getCharacteristicEnvVars() Builds up the environment variable map that's sufficient to identify a process as ours.
Object	getDynamic(String token, org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
EnvVars	getEnvironment(Node node, TaskListener listener) Creates an environment variable override for launching processes for this project.
long	getEstimatedDuration()
RunT	getFirstBuild() Returns the oldest build in the record.
BallColor	getIconColor() Used as the color of the status ball for the project.
RunT	getLastBuild() Returns the last build.
List<RunT>	getLastBuildsOverThreshold(int numberOfBuilds, Result threshold) Returns the last 'numberOfBuilds' builds with a build result >= 'threshold'
RunT	getLastCompletedBuild() Returns the last completed build, if any.
RunT	getLastFailedBuild() Returns the last failed build, if any.
RunT	getLastStableBuild() Returns the last stable build, if any.
RunT	getLastSuccessfulBuild() Returns the last successful build, if any.
RunT	getLastUnstableBuild() Returns the last unstable build, if any.
RunT	getLastUnsuccessfulBuild() Returns the last build that was anything but stable, if any.
LogRotator	getLogRotator() Deprecated. as of 1.503 Use getBuildDiscarder().
RunT	getNearestBuild(int n) Gets the youngest build #m that satisfies n<=m.
RunT	getNearestOldBuild(int n) Gets the latest build #m that satisfies m<=n.
RunList<RunT>	getNewBuilds() Gets the read-only view of the recent builds.
int	getNextBuildNumber() Peeks the next build number.
Collection<?>	getOverrides() Overrides from job properties.
PermalinkList	getPermalinks() Gets all the PermalinkProjectAction.Permalinks defined for this job.
String	getPronoun() Get the term used in the UI to represent this kind of Item.
Map<JobPropertyDescriptor,JobProperty<? super JobT>>	getProperties() Gets all the job properties configured for this job.
<T extends JobProperty> T	getProperty(Class<T> clazz) Gets the specific property, or null if the propert is not configured for this job.
JobProperty	getProperty(String className) Bind JobPropertys to URL spaces.
Queue.Item	getQueueItem() If this job is in the build queue, return its item.
BuildTimelineWidget	getTimeline()
List<Widget>	getWidgets()
abstract boolean	isBuildable() Returns true if we should display "build now" icon
boolean	isBuilding() Returns true if a build of this project is in progress.
protected boolean	isHoldOffBuildUntilSave()
boolean	isInQueue()
boolean	isKeepDependencies() If true, it will keep all the build logs of dependency components.
boolean	isLogUpdated() Returns true if the log file is still being updated.
boolean	isNameEditable() Returns whether the name of this job can be changed by user.
void	logRotate() Perform log rotation.
protected SearchIndexBuilder	makeSearchIndex() Default implementation that returns empty index.
void	onCopiedFrom(Item src) 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.
void	onLoad(ItemGroup<? extends Item> parent, String name) Called right after when a Item is loaded from disk.
protected void	performDelete() Does the real job of deleting the item.
<T extends JobProperty> T	removeProperty(Class<T> clazz) Removes the property of the given type.
void	removeProperty(JobProperty<? super JobT> jobProp) Removes JobProperty
protected abstract void	removeRun(RunT run) Called from Run to remove it from this job.
void	renameTo(String newName) Renames a job.
void	save() Save the settings to a file.
protected void	saveNextBuildNumber()
void	setBuildDiscarder(BuildDiscarder bd)
void	setLogRotator(LogRotator logRotator) Deprecated. as of 1.503 Use setBuildDiscarder(BuildDiscarder)
protected void	submit(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Derived class can override this to perform additional config submission work.
boolean	supportsLogRotator() True if this instance supports log rotation configuration.
void	updateNextBuildNumber(int next) Programatically updates the next build number.

Methods inherited from class hudson.model.AbstractItem

checkPermission, delete, doConfigDotXml, doDoDelete, doSetName, doSubmitDescription, getAbsoluteUrl, getApi, getConfigFile, getDescription, getDescriptorByName, getDisplayName, getDisplayNameOrNull, getFullDisplayName, getFullName, getName, getParent, getRelativeNameFrom, getRelativeNameFrom, getRelativeNameFromGroup, getRootDir, getSearchName, getSearchUrl, getShortUrl, getUrl, hasPermission, onCreatedFromScratch, resolveForCLI, setDescription, setDisplayName, setDisplayNameOrNull, toString, updateByXml, updateByXml

Methods inherited from class hudson.model.Actionable

addAction, doContextMenu, getAction, getAction, getActions, getActions

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface hudson.search.SearchableModelObject

getSearch

Methods inherited from interface hudson.search.SearchItem

getSearchIndex

Field Detail

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 UserPropertys configured for this project.

HISTORY_ADAPTER

protected static final HistoryWidget.Adapter<Run> HISTORY_ADAPTER

Constructor Detail

Job

protected Job(ItemGroup parent,
              String name)

Method Detail

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 opporunity to do a post load processing.

Specified by:

onLoad in interface Item

Overrides:

onLoad in class AbstractItem

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.

performDelete

protected void performDelete()
                      throws IOException,
                             InterruptedException

Description copied from class: AbstractItem

Does the real job of deleting the item.

Overrides:

performDelete in class AbstractItem

Throws:

IOException

InterruptedException

isHoldOffBuildUntilSave

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

isKeepDependencies

@Exported
public boolean isKeepDependencies()

If true, it will keep all the build logs of dependency components.

assignBuildNumber

public int assignBuildNumber()
                      throws IOException

Allocates a new buildCommand number.

Throws:

IOException

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

public EnvVars getEnvironment(Node node,
                              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

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

getBuildDiscarder

public BuildDiscarder getBuildDiscarder()

Returns the configured build discarder for this job, or null if none.

setBuildDiscarder

public void setBuildDiscarder(BuildDiscarder bd)
                       throws IOException

Throws:

IOException

getLogRotator

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

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.

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 propert 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:

JobProperty.getJobOverrides()

getWidgets

public List<Widget> getWidgets()

createHistoryWidget

protected HistoryWidget createHistoryWidget()

renameTo

public void renameTo(String newName)
              throws IOException

Renames a job.

Overrides:

renameTo in class AbstractItem

Throws:

IOException

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

Specified by:

delete in interface Item

Overrides:

delete in class AbstractItem

Throws:

IOException

InterruptedException

isBuildable

@Exported
public abstract boolean isBuildable()

Returns true if we should display "build now" icon

getBuilds

@Exported(name="allBuilds",
          visibility=-2)
@WithBridgeMethods(value=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

@Deprecated
public RunT getBuild(String id)

Deprecated. since 2008-06-15. This is only used to support backward compatibility with old URLs.

getBuildByNumber

public RunT getBuildByNumber(int n)

Parameters:

n - The build number.

Returns:

null if no such build exists.

See Also:

Run.getNumber()

getBuildsByTimestamp

@WithBridgeMethods(value=java.util.List.class)
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 youngest build #m that satisfies n<=m. This is useful when you'd like to fetch a build but the exact build might be already gone (deleted, rotated, etc.)

getNearestOldBuild

public RunT getNearestOldBuild(int n)

Gets the latest 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.)

getDynamic

public Object getDynamic(String token,
                         org.kohsuke.stapler.StaplerRequest req,
                         org.kohsuke.stapler.StaplerResponse rsp)

Overrides:

getDynamic in class Actionable

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:

RunMap

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

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.

getLastBuild

@Exported
public RunT getLastBuild()

Returns the last build.

getFirstBuild

@Exported
public RunT getFirstBuild()

Returns the oldest build in the record.

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:

getLastStableBuild()

getLastUnsuccessfulBuild

@Exported
public RunT getLastUnsuccessfulBuild()

Returns the last build that was anything but stable, if any. Otherwise null.

See Also:

getLastSuccessfulBuild()

getLastUnstableBuild

@Exported
public RunT getLastUnstableBuild()

Returns the last unstable build, if any. Otherwise null.

See Also:

getLastSuccessfulBuild()

getLastStableBuild

@Exported
public RunT getLastStableBuild()

Returns the last stable build, if any. Otherwise null.

See Also:

getLastSuccessfulBuild()

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.

getEstimatedDuration

public long getEstimatedDuration()

getPermalinks

public PermalinkList getPermalinks()

Gets all the PermalinkProjectAction.Permalinks defined for this job.

Returns:

never null

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

public void doConfigSubmit(org.kohsuke.stapler.StaplerRequest req,
                           org.kohsuke.stapler.StaplerResponse rsp)
                    throws IOException,
                           javax.servlet.ServletException,
                           Descriptor.FormException

Accepts submission from the configuration page.

Throws:

IOException

javax.servlet.ServletException

Descriptor.FormException

submit

protected void submit(org.kohsuke.stapler.StaplerRequest req,
                      org.kohsuke.stapler.StaplerResponse rsp)
               throws IOException,
                      javax.servlet.ServletException,
                      Descriptor.FormException

Derived class can override this to perform additional config submission work.

Throws:

IOException

javax.servlet.ServletException

Descriptor.FormException

doDescription

public void doDescription(org.kohsuke.stapler.StaplerRequest req,
                          org.kohsuke.stapler.StaplerResponse rsp)
                   throws IOException

Accepts and serves the job description

Throws:

IOException

doBuildStatus

public void doBuildStatus(org.kohsuke.stapler.StaplerRequest req,
                          org.kohsuke.stapler.StaplerResponse rsp)
                   throws IOException

Returns the image that shows the current buildCommand status.

Throws:

IOException

getBuildStatusUrl

public String getBuildStatusUrl()

getBuildTimeGraph

public Graph getBuildTimeGraph()

doDoRename

public void doDoRename(org.kohsuke.stapler.StaplerRequest req,
                       org.kohsuke.stapler.StaplerResponse rsp)
                throws IOException,
                       javax.servlet.ServletException

Renames this job.

Throws:

IOException

javax.servlet.ServletException

doRssAll

public void doRssAll(org.kohsuke.stapler.StaplerRequest req,
                     org.kohsuke.stapler.StaplerResponse rsp)
              throws IOException,
                     javax.servlet.ServletException

Throws:

IOException

javax.servlet.ServletException

doRssFailed

public void doRssFailed(org.kohsuke.stapler.StaplerRequest req,
                        org.kohsuke.stapler.StaplerResponse rsp)
                 throws IOException,
                        javax.servlet.ServletException

Throws:

IOException

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

public BuildTimelineWidget getTimeline()