hudson.model
Class Run<JobT extends Job<JobT,RunT>,RunT extends Run<JobT,RunT>>

java.lang.Object
  hudson.model.AbstractModelObject
      hudson.model.Actionable
          hudson.model.Run<JobT,RunT>

All Implemented Interfaces:

ExtensionPoint, DescriptorByNameOwner, ModelObject, PersistenceRoot, Saveable, SearchableModelObject, SearchItem, AccessControlled, Comparable<RunT>

Direct Known Subclasses:

AbstractBuild, ExternalRun

@ExportedBean
public abstract class Run<JobT extends Job<JobT,RunT>,RunT extends Run<JobT,RunT>>
extends Actionable
implements ExtensionPoint, Comparable<RunT>, AccessControlled, PersistenceRoot, DescriptorByNameOwner

A particular execution of Job.

Custom Run type is always used in conjunction with a custom Job type, so there's no separate registration mechanism for custom Run types.

Author:

Kohsuke Kawaguchi

See Also:

RunListener

Nested Class Summary

class	Run.Artifact A build artifact.
class	Run.ArtifactList
class	Run.KeepLogBuildBadge BuildBadgeAction that shows the logs are being kept.
static class	Run.RedirectUp
static class	Run.RunnerAbortedException Used in Runner#run to indicates that a fatal error in a build is reported to BuildListener and the build should be simply aborted without further recording a stack trace.
static class	Run.Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

static Permission	ARTIFACTS See Functions.isArtifactsPermissionEnabled()
static Permission	DELETE
static FeedAdapter<Run>	FEED_ADAPTER FeedAdapter to produce feed from the summary of this build.
static FeedAdapter<Run>	FEED_ADAPTER_LATEST FeedAdapter to produce feeds to show one build per project.
static int	LIST_CUTOFF Maximum number of artifacts to list before using switching to the tree view.
int	number Build number.
static Comparator<Run>	ORDER_BY_DATE Sort by date.
static PermissionGroup	PERMISSIONS
static int	TREE_CUTOFF Maximum number of artifacts to show in tree view before just showing a link.
static Permission	UPDATE
static com.thoughtworks.xstream.XStream	XSTREAM

Fields inherited from interface hudson.model.Saveable

NOOP

Method Summary

void	addAction(Action a) Adds a new action.
void	checkPermission(Permission p) Convenient short-cut for getACL().checkPermission(permission)
int	compareTo(RunT that) Ordering based on build numbers.
void	delete() Deletes this build and its entire log
void	deleteArtifacts() Deletes this build's artifacts.
DirectoryBrowserSupport	doArtifact() Serves the artifacts.
void	doBuildNumber(org.kohsuke.stapler.StaplerResponse rsp) Returns the build number in the body.
void	doBuildStatus(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
void	doBuildTimestamp(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp, String format) Returns the build time stamp in the body.
org.kohsuke.stapler.HttpResponse	doConfigSubmit(org.kohsuke.stapler.StaplerRequest req)
void	doConsoleText(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Sends out the raw console output.
void	doDoDelete(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Deletes the build when the button is pressed.
void	doProgressiveLog(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Deprecated. as of 1.352 Use getLogText().doProgressiveText(req,rsp)
void	doSubmitDescription(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts the new description.
void	doToggleLogKeep(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
static Run<?,?>	fromExternalizableId(String id)
String	getAbsoluteUrl() Deprecated. This method shall NEVER be used during HTML page rendering, as it won't work with network set up like Apache reverse proxy. This method is only intended for the remote API clients who cannot resolve relative references (even this won't work for the same reason, which should be fixed.)
ACL	getACL() Obtains the ACL associated with this object.
Api	getApi()
List<Run.Artifact>	getArtifacts() Gets the artifacts (relative to getArtifactsDir().
File	getArtifactsDir() Gets the directory where the artifacts are archived.
List<Run.Artifact>	getArtifactsUpTo(int n) Gets the first N artifacts.
List<BuildBadgeAction>	getBadgeActions() Gets the subset of Actionable.getActions() that consists of BuildBadgeActions.
Run.Summary	getBuildStatusSummary() Gets an object that computes the single line summary of this build.
String	getBuildStatusUrl()
<T extends Cause> T	getCause(Class<T> type) Returns a Cause of a particular type.
List<Cause>	getCauses() Returns the Causes that tirggered a build.
EnvVars	getCharacteristicEnvVars() Builds up the environment variable map that's sufficient to identify a process as ours.
Charset	getCharset() Gets the charset in which the log file is written.
String	getDescription()
Descriptor	getDescriptorByName(String className) Exposes all Descriptors by its name to URL.
String	getDisplayName()
long	getDuration() Gets the millisecond it took to build.
String	getDurationString() Gets the string that says how long the build took to run.
Object	getDynamic(String token, org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
EnvVars	getEnvironment() Deprecated. as of 1.305 use getEnvironment(TaskListener)
EnvVars	getEnvironment(TaskListener log) Returns the map that contains environmental variables to be used for launching processes for this build.
Map<String,String>	getEnvVars() Deprecated. as of 1.292 Use getEnvironment() instead.
long	getEstimatedDuration() Returns the estimated duration for this run if it is currently running.
Executor	getExecutor() Gets the Executor building this job, if it's being built.
String	getExternalizableId()
String	getFullDisplayName()
String	getFullName()
boolean	getHasArtifacts() Returns true if this run has any artifacts.
BallColor	getIconColor() Gets the icon color for display.
String	getId() Unique ID of this build.
static DateFormat	getIDFormatter() Get the date formatter used to convert the directory name in to a timestamp This is nasty exposure of private data, but needed all the time the directory containing the build is used as it's timestamp.
String	getLog() Deprecated. since 2007-11-11. Use getLog(int) instead as it avoids loading the whole log into memory unnecessarily.
List<String>	getLog(int maxLines) Gets the log of the build as a list of strings (one per log line).
File	getLogFile() Returns the log file.
InputStream	getLogInputStream() Returns an input stream that reads from the log file.
Reader	getLogReader()
AnnotatedLargeText	getLogText() Used to URL-bind AnnotatedLargeText.
RunT	getNextBuild()
int	getNumber()
JobT	getParent() The project this build is for.
RunT	getPreviousBuild()
RunT	getPreviousBuildInProgress() Obtains the next younger build in progress.
List<RunT>	getPreviousBuildsOverThreshold(int numberOfBuilds, Result threshold) Returns the last 'numberOfBuilds' builds with a build result >= 'threshold'.
RunT	getPreviousBuiltBuild() Returns the last build that was actually built - i.e., skipping any with Result.NOT_BUILT
RunT	getPreviousCompletedBuild() Gets the most recent completed build excluding 'this' Run itself.
RunT	getPreviousFailedBuild() Returns the last failed build before this build.
RunT	getPreviousNotFailedBuild() Returns the last build that didn't fail before this build.
RunT	getPreviousSuccessfulBuild() Returns the last successful build before this build.
Result	getResult() Returns the build result.
File	getRootDir() Root directory of this Run on the master.
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
Date	getTime() Same as getTimestamp() but in a different type.
long	getTimeInMillis() Same as getTimestamp() but in a different type, that is since the time of the epoc.
Calendar	getTimestamp() When the build is scheduled.
String	getTimestampString() Gets the string that says how long since this build has started.
String	getTimestampString2() Returns the timestamp formatted in xs:dateTime.
String	getTruncatedDescription() Returns the length-limited description.
String	getUrl() Returns the URL of this Run, relative to the context root of Hudson.
String	getWhyKeepLog() If isKeepLog() returns true, returns a human readable one-line string that explains why it's being kept.
boolean	hasCustomDisplayName()
boolean	hasntStartedYet() Returns true if the build is still queued and hasn't started yet.
boolean	hasPermission(Permission p) Convenient short-cut for getACL().hasPermission(permission)
boolean	isBuilding() Returns true if the build is not completed yet.
boolean	isKeepLog() Returns true if this log file should be kept and not deleted.
boolean	isLogUpdated() Returns true if the log file is still being updated.
void	keepLog() Marks this build to keep the log.
void	keepLog(boolean newValue)
void	save() Save the settings to a file.
void	setDescription(String description)
void	setDisplayName(String value)
void	setResult(Result r)
String	toString()
void	writeLogTo(long offset, org.apache.commons.jelly.XMLOutput out) Used from console.jelly to write annotated log to the given output.

Methods inherited from class hudson.model.Actionable

getAction, getAction, getActions, getActions

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, getSearchName

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

number

public int number

Build number.

In earlier versions < 1.24, this number is not unique nor continuous, but going forward, it will, and this really replaces the build id.

LIST_CUTOFF

public static final int LIST_CUTOFF

Maximum number of artifacts to list before using switching to the tree view.

TREE_CUTOFF

public static final int TREE_CUTOFF

Maximum number of artifacts to show in tree view before just showing a link.

XSTREAM

public static final com.thoughtworks.xstream.XStream XSTREAM

ORDER_BY_DATE

public static final Comparator<Run> ORDER_BY_DATE

Sort by date. Newer ones first.

FEED_ADAPTER

public static final FeedAdapter<Run> FEED_ADAPTER

FeedAdapter to produce feed from the summary of this build.

FEED_ADAPTER_LATEST

public static final FeedAdapter<Run> FEED_ADAPTER_LATEST

FeedAdapter to produce feeds to show one build per project.

PERMISSIONS

public static final PermissionGroup PERMISSIONS

DELETE

public static final Permission DELETE

UPDATE

public static final Permission UPDATE

ARTIFACTS

public static final Permission ARTIFACTS

See Functions.isArtifactsPermissionEnabled()

Method Detail

addAction

public void addAction(Action a)

Description copied from class: Actionable

Adds a new action. Short for getActions().add(a)

Overrides:

addAction in class Actionable

compareTo

public int compareTo(RunT that)

Ordering based on build numbers.

Specified by:

compareTo in interface Comparable<RunT extends Run<JobT,RunT>>

getResult

@Exported
public Result getResult()

Returns the build result.

When a build is in progress, this method returns an intermediate result.

setResult

public void setResult(Result r)

getBadgeActions

public List<BuildBadgeAction> getBadgeActions()

Gets the subset of Actionable.getActions() that consists of BuildBadgeActions.

isBuilding

@Exported
public boolean isBuilding()

Returns true if the build is not completed yet. This includes "not started yet" state.

isLogUpdated

public boolean isLogUpdated()

Returns true if the log file is still being updated.

getExecutor

public Executor getExecutor()

Gets the Executor building this job, if it's being built. Otherwise null.

getCharset

public final Charset getCharset()

Gets the charset in which the log file is written.

Returns:

never null.

Since:

1.257

getCauses

public List<Cause> getCauses()

Returns the Causes that tirggered a build.

If a build sits in the queue for a long time, multiple build requests made during this period are all rolled up into one build, hence this method may return a list.

Returns:

can be empty but never null. read-only.

Since:

1.321

getCause

public <T extends Cause> T getCause(Class<T> type)

Returns a Cause of a particular type.

Since:

1.362

isKeepLog

@Exported
public final boolean isKeepLog()

Returns true if this log file should be kept and not deleted. This is used as a signal to the LogRotator.

getWhyKeepLog

public String getWhyKeepLog()

If isKeepLog() returns true, returns a human readable one-line string that explains why it's being kept.

getParent

public JobT getParent()

The project this build is for.

getTimestamp

@Exported
public Calendar getTimestamp()

When the build is scheduled.

getTime

public final Date getTime()

Same as getTimestamp() but in a different type.

getTimeInMillis

public final long getTimeInMillis()

Same as getTimestamp() but in a different type, that is since the time of the epoc.

getDescription

@Exported
public String getDescription()

getTruncatedDescription

public String getTruncatedDescription()

Returns the length-limited description.

Returns:

The length-limited description.

getTimestampString

public String getTimestampString()

Gets the string that says how long since this build has started.

Returns:

string like "3 minutes" "1 day" etc.

getTimestampString2

public String getTimestampString2()

Returns the timestamp formatted in xs:dateTime.

getDurationString

public String getDurationString()

Gets the string that says how long the build took to run.

getDuration

@Exported
public long getDuration()

Gets the millisecond it took to build.

getIconColor

public BallColor getIconColor()

Gets the icon color for display.

hasntStartedYet

public boolean hasntStartedYet()

Returns true if the build is still queued and hasn't started yet.

toString

public String toString()

Overrides:

toString in class Object

getFullName

public String getFullName()

getFullDisplayName

@Exported
public String getFullDisplayName()

getDisplayName

public String getDisplayName()

Specified by:

getDisplayName in interface ModelObject

hasCustomDisplayName

public boolean hasCustomDisplayName()

setDisplayName

public void setDisplayName(String value)
                    throws IOException

Parameters:

value - Set to null to revert back to the default "#NNN".

Throws:

IOException

getNumber

@Exported(visibility=2)
public int getNumber()

getPreviousBuild

public RunT getPreviousBuild()

getPreviousCompletedBuild

public final RunT getPreviousCompletedBuild()

Gets the most recent completed build excluding 'this' Run itself.

getPreviousBuildInProgress

public final RunT getPreviousBuildInProgress()

Obtains the next younger build in progress. It uses a skip-pointer so that we can compute this without O(n) computation time. This method also fixes up the skip list as we go, in a way that's concurrency safe.

We basically follow the existing skip list, and wherever we find a non-optimal pointer, we remember them in 'fixUp' and update them later.

getPreviousBuiltBuild

public RunT getPreviousBuiltBuild()

Returns the last build that was actually built - i.e., skipping any with Result.NOT_BUILT

getPreviousNotFailedBuild

public RunT getPreviousNotFailedBuild()

Returns the last build that didn't fail before this build.

getPreviousFailedBuild

public RunT getPreviousFailedBuild()

Returns the last failed build before this build.

getPreviousSuccessfulBuild

public RunT getPreviousSuccessfulBuild()

Returns the last successful build before this build.

Since:

1.383

getPreviousBuildsOverThreshold

public List<RunT> getPreviousBuildsOverThreshold(int numberOfBuilds,
                                                 Result threshold)

Returns the last 'numberOfBuilds' builds with a build result >= 'threshold'.

Parameters:

numberOfBuilds - the desired number of builds

threshold - the build result threshold

Returns:

a list with the builds (youngest build first). May be smaller than 'numberOfBuilds' or even empty if not enough builds satisfying the threshold have been found. Never null.

Since:

1.383

getNextBuild

public RunT getNextBuild()

getUrl

public String getUrl()

Returns the URL of this Run, relative to the context root of Hudson.

Returns:

String like "job/foo/32/" with trailing slash but no leading slash.

getAbsoluteUrl

@Exported(visibility=2,
          name="url")
public final String getAbsoluteUrl()

Deprecated. This method shall NEVER be used during HTML page rendering, as it won't work with network set up like Apache reverse proxy. This method is only intended for the remote API clients who cannot resolve relative references (even this won't work for the same reason, which should be fixed.)

Obtains the absolute URL to this build.

getSearchUrl

public final String getSearchUrl()

Description copied from interface: SearchItem

Returns the URL of this item relative to the parent SearchItem.

Specified by:

getSearchUrl in interface SearchItem

Returns:

URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Hudson.)

getId

@Exported
public String getId()

Unique ID of this build.

getIDFormatter

public static DateFormat getIDFormatter()

Get the date formatter used to convert the directory name in to a timestamp This is nasty exposure of private data, but needed all the time the directory containing the build is used as it's timestamp.

getDescriptorByName

public Descriptor getDescriptorByName(String className)

Description copied from interface: DescriptorByNameOwner

Exposes all Descriptors by its name to URL.

Implementation should always delegate to Hudson.getDescriptorByName(String).

Specified by:

getDescriptorByName in interface DescriptorByNameOwner

Parameters:

className - Either Descriptor.getId() (recommended) or the short name.

getRootDir

public File getRootDir()

Root directory of this Run on the master. Files related to this Run should be stored below this directory.

Specified by:

getRootDir in interface PersistenceRoot

getArtifactsDir

public File getArtifactsDir()

Gets the directory where the artifacts are archived.

getArtifacts

@Exported
public List<Run.Artifact> getArtifacts()

Gets the artifacts (relative to getArtifactsDir().

getArtifactsUpTo

public List<Run.Artifact> getArtifactsUpTo(int n)

Gets the first N artifacts.

getHasArtifacts

public boolean getHasArtifacts()

Returns true if this run has any artifacts.

The strange method name is so that we can access it from EL.

getLogFile

public File getLogFile()

Returns the log file.

getLogInputStream

public InputStream getLogInputStream()
                              throws IOException

Returns an input stream that reads from the log file. It will use a gzip-compressed log file (log.gz) if that exists.

Returns:

an input stream from the log file, or null if none exists

Throws:

IOException

Since:

1.349

getLogReader

public Reader getLogReader()
                    throws IOException

Throws:

IOException

writeLogTo

public void writeLogTo(long offset,
                       org.apache.commons.jelly.XMLOutput out)
                throws IOException

Used from console.jelly to write annotated log to the given output.

Throws:

IOException

Since:

1.349

getLogText

public AnnotatedLargeText getLogText()

Used to URL-bind AnnotatedLargeText.

getApi

public Api getApi()

checkPermission

public void checkPermission(Permission p)

Description copied from interface: AccessControlled

Convenient short-cut for getACL().checkPermission(permission)

Specified by:

checkPermission in interface AccessControlled

hasPermission

public boolean hasPermission(Permission p)

Description copied from interface: AccessControlled

Convenient short-cut for getACL().hasPermission(permission)

Specified by:

hasPermission in interface AccessControlled

getACL

public ACL getACL()

Description copied from interface: AccessControlled

Obtains the ACL associated with this object.

Specified by:

getACL in interface AccessControlled

Returns:

never null.

deleteArtifacts

public void deleteArtifacts()
                     throws IOException

Deletes this build's artifacts.

Throws:

IOException - if we fail to delete.

Since:

1.350

delete

public void delete()
            throws IOException

Deletes this build and its entire log

Throws:

IOException - if we fail to delete.

save

public void save()
          throws IOException

Save the settings to a file.

Specified by:

save in interface Saveable

Throws:

IOException - if the persistence failed.

getLog

@Deprecated
public String getLog()
              throws IOException

Deprecated. since 2007-11-11. Use getLog(int) instead as it avoids loading the whole log into memory unnecessarily.

Gets the log of the build as a string.

Throws:

IOException

getLog

public List<String> getLog(int maxLines)
                    throws IOException

Gets the log of the build as a list of strings (one per log line). The number of lines returned is constrained by the maxLines parameter.

Parameters:

maxLines - The maximum number of log lines to return. If the log is bigger than this, only the most recent lines are returned.

Returns:

A list of log lines. Will have no more than maxLines elements.

Throws:

IOException - If there is a problem reading the log file.

doBuildStatus

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

Throws:

IOException

getBuildStatusUrl

public String getBuildStatusUrl()

getBuildStatusSummary

public Run.Summary getBuildStatusSummary()

Gets an object that computes the single line summary of this build.

doArtifact

public DirectoryBrowserSupport doArtifact()

Serves the artifacts.

doBuildNumber

public void doBuildNumber(org.kohsuke.stapler.StaplerResponse rsp)
                   throws IOException

Returns the build number in the body.

Throws:

IOException

doBuildTimestamp

public void doBuildTimestamp(org.kohsuke.stapler.StaplerRequest req,
                             org.kohsuke.stapler.StaplerResponse rsp,
                             @QueryParameter
                             String format)
                      throws IOException

Returns the build time stamp in the body.

Throws:

IOException

doConsoleText

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

Sends out the raw console output.

Throws:

IOException

doProgressiveLog

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

Deprecated. as of 1.352 Use getLogText().doProgressiveText(req,rsp)

Handles incremental log output.

Throws:

IOException

doToggleLogKeep

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

Throws:

IOException

javax.servlet.ServletException

keepLog

@CLIMethod(name="keep-build")
public final void keepLog()
                   throws IOException

Marks this build to keep the log.

Throws:

IOException

keepLog

public void keepLog(boolean newValue)
             throws IOException

Throws:

IOException

doDoDelete

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

Deletes the build when the button is pressed.

Throws:

IOException

javax.servlet.ServletException

setDescription

public void setDescription(String description)
                    throws IOException

Throws:

IOException

doSubmitDescription

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

Accepts the new description.

Throws:

IOException

javax.servlet.ServletException

getEnvVars

public Map<String,String> getEnvVars()

Deprecated. as of 1.292 Use getEnvironment() instead.

getEnvironment

public EnvVars getEnvironment()
                       throws IOException,
                              InterruptedException

Deprecated. as of 1.305 use getEnvironment(TaskListener)

Throws:

IOException

InterruptedException

getEnvironment

public EnvVars getEnvironment(TaskListener log)
                       throws IOException,
                              InterruptedException

Returns the map that contains environmental variables to be used for launching processes for this build.

BuildSteps that invoke external processes should use this. This allows BuildWrappers and other project configurations (such as JDK selection) to take effect.

Unlike earlier getEnvVars(), this map contains the whole environment, not just the overrides, so one can introspect values to change its behavior.

Throws:

IOException

InterruptedException

Since:

1.305

getCharacteristicEnvVars

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

getExternalizableId

public String getExternalizableId()

fromExternalizableId

public static Run<?,?> fromExternalizableId(String id)

getEstimatedDuration

public long getEstimatedDuration()

Returns the estimated duration for this run if it is currently running. Default to Job.getEstimatedDuration(), may be overridden in subclasses if duration may depend on run specific parameters (like incremental Maven builds).

Returns:

the estimated duration in milliseconds

Since:

1.383

doConfigSubmit

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

Throws:

IOException

javax.servlet.ServletException

Descriptor.FormException

getDynamic

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

Overrides:

getDynamic in class Actionable