Package hudson.model

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

    • Field Detail

      • project

        @NonNull
protected final transient JobT extends Job<JobT,​RunT> project

      • number

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

      • previousBuild

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
protected transient volatile RunT extends Run<JobT,​RunT> previousBuild
        Previous build. Can be null. TODO JENKINS-22052 this is not actually implemented any more External code should use getPreviousBuild()

      • nextBuild

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
protected transient volatile RunT extends Run<JobT,​RunT> nextBuild
        Next build. Can be null. External code should use getNextBuild()

      • timestamp

        protected long timestamp
        When the build is scheduled.

      • result

        protected volatile Result result
        The build result. This value may change while the state is in Run.State.BUILDING.

      • description

        @CheckForNull
protected volatile String description
        Human-readable description which is used on the main build page. It can also be quite long, and it may use markup in a format defined by a MarkupFormatter. getTruncatedDescription() may be used to retrieve a size-limited description, but it implies some limitations.

      • duration

        protected long duration
        Number of milli-seconds it took to run this build.

      • charset

        protected String charset
        Charset in which the log file is written. For compatibility reason, this field may be null. For persistence, this field is string and not Charset.
        Since:
        1.257
        See Also:
        getCharset()

      • LIST_CUTOFF

        public static final int LIST_CUTOFF
        Maximum number of artifacts to list before using switching to the tree view.

      • XSTREAM

        public static final com.thoughtworks.xstream.XStream XSTREAM

      • XSTREAM2

        public static final XStream2 XSTREAM2
        Alias to XSTREAM so that one can access additional methods on XStream2 more easily.

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

      • SKIP_PERMISSION_CHECK

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean SKIP_PERMISSION_CHECK
        Escape hatch for StaplerProxy-based access control

    • Method Detail

      • reload

        public void reload()
            throws IOException
        Reloads the build record from disk.
        Throws:
        IOException
        Since:
        1.410

      • onLoad

        protected void onLoad()
        Called after the build is loaded and the object is added to the build list.

      • getTransientActions

        @Deprecated
public List<Action> getTransientActions()
        Deprecated.
        Use Actionable.getAllActions() instead.
        Return all transient actions associated with this build.
        Returns:
        the list can be empty but never null. read only.

      • addAction

        public void addAction​(@NonNull
                      Action a)
        Adds a new action. Note: calls to Actionable.getAllActions() that happen before calls to this method may not see the update. Note: this method will always modify the actions A RunAction2 is handled specially.
        Overrides:
        addAction in class Actionable

      • _this

        @NonNull
protected RunT _this()
        Obtains 'this' in a more type safe signature.

      • compareTo

        public int compareTo​(@NonNull
                     RunT that)
        Ordering based on build numbers. If numbers are equal order based on names of parent projects.
        Specified by:
        compareTo in interface Comparable<JobT extends Job<JobT,​RunT>>

      • getQueueId

        @Exported
public long getQueueId()
        Get the Queue.Item.getId() of the original queue item from where this Run instance originated.
        Returns:
        The queue item ID.
        Since:
        1.601

      • setQueueId

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public void setQueueId​(long queueId)
        Set the queue item ID.

        Mapped from the Queue.Item.getId().

        Parameters:
        queueId - The queue item ID.

      • getResult

        @Exported
@CheckForNull
public Result getResult()
        Returns the build result.

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

        Returns:
        The status of the build, if it has completed or some build step has set a status; may be null if the build is ongoing.

      • setResult

        public void setResult​(@NonNull
                      Result r)
        Sets the getResult() of this build. Has no effect when the result is already set and worse than the proposed result. May only be called after the build has started and before it has moved into post-production (normally meaning both isInProgress() and isBuilding() are true).
        Parameters:
        r - the proposed new result
        Throws:
        IllegalStateException - if the build has not yet started, is in post-production, or is complete

      • isBuilding

        @Exported
public boolean isBuilding()
        Returns true if the build is not completed yet. This includes "not started yet" state.

      • isInProgress

        @Exported
public boolean isInProgress()
        Determine whether the run is being build right now.
        Returns:
        true if after started and before completed.
        Since:
        1.538

      • isLogUpdated

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

      • getOneOffExecutor

        @CheckForNull
public Executor getOneOffExecutor()
        Gets the one off Executor building this job, if it's being built. Otherwise null.
        Since:
        1.433

      • getCharset

        @NonNull
public final Charset getCharset()
        Gets the charset in which the log file is written.
        Returns:
        never null.
        Since:
        1.257

      • getCauses

        @NonNull
public List<Cause> getCauses()
        Returns the Causes that triggered 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

        @CheckForNull
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 build should be kept and not deleted. (Despite the name, this refers to the entire build, not merely the log file.) This is used as a signal to the BuildDiscarder.

      • getWhyKeepLog

        @CheckForNull
public String getWhyKeepLog()
        If isKeepLog() returns true, returns a short, human-readable sentence that explains why it's being kept.

      • getParent

        @NonNull
public JobT getParent()
        The project this build is for.

      • getTime

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

      • getStartTimeInMillis

        public final long getStartTimeInMillis()
        When the build has started running in an executor. For example, if a build is scheduled 1pm, and stayed in the queue for 1 hour (say, no idle agents), then this method returns 2pm, which is the time the job moved from the queue to the building state.
        See Also:
        getTimestamp()

      • getDescription

        @Exported
@CheckForNull
public String getDescription()

      • getTruncatedDescription

        @Deprecated
@CheckForNull
public String getTruncatedDescription()
        Deprecated.
        truncated description based on the TRUNCATED_DESCRIPTION_LIMIT setting.
        Returns the length-limited description. The method tries to take HTML tags within the description into account, but it is a best-effort attempt. Also, the method will likely not work properly if a non-HTML MarkupFormatter is used.
        Returns:
        The length-limited description.

      • getTimestampString

        @NonNull
public String getTimestampString()
        Gets the string that says how long since this build has started.
        Returns:
        string like "3 minutes" "1 day" etc.

      • getTimestampString2

        @NonNull
public String getTimestampString2()
        Returns the timestamp formatted in xs:dateTime.

      • getDurationString

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

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

      • getFullDisplayName

        @Exported
public String getFullDisplayName()

      • 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()

      • getPreviousCompletedBuild

        @CheckForNull
public final RunT getPreviousCompletedBuild()
        Gets the most recent completed build excluding 'this' Run itself.

      • getPreviousBuildInProgress

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

        @CheckForNull
public RunT getPreviousBuiltBuild()
        Returns the last build that was actually built - i.e., skipping any with Result.NOT_BUILT

      • getPreviousNotFailedBuild

        @CheckForNull
public RunT getPreviousNotFailedBuild()
        Returns the last build that didn't fail before this build.

      • getPreviousFailedBuild

        @CheckForNull
public RunT getPreviousFailedBuild()
        Returns the last failed build before this build.

      • getPreviousSuccessfulBuild

        @CheckForNull
public RunT getPreviousSuccessfulBuild()
        Returns the last successful build before this build.
        Since:
        1.383

      • getPreviousBuildsOverThreshold

        @NonNull
public List<RunT> getPreviousBuildsOverThreshold​(int numberOfBuilds,
                                                 @NonNull
                                                 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

      • getBuildsOverThreshold

        @NonNull
protected List<RunT> getBuildsOverThreshold​(int numberOfBuilds,
                                            @NonNull
                                            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:
        2.202

      • getUrl

        @NonNull
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")
@Deprecated
@NonNull
public final String getAbsoluteUrl()
        Deprecated.
        This method shall NEVER be used during HTML page rendering, as it's too easy for misconfiguration to break this value, with network set up like Apache reverse proxy. This method is only intended for the remote API clients who cannot resolve relative references.
        Obtains the absolute URL to this build.

      • getSearchUrl

        @NonNull
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 Jenkins.)

      • getId

        @Exported
@NonNull
public String getId()
        Unique ID of this build. Usually the decimal form of number, but may be a formatted timestamp for historical builds.

      • getRootDir

        @NonNull
public File getRootDir()
        Get the root directory of this Run on the controller. Files related to this Run should be stored below this directory.
        Specified by:
        getRootDir in interface PersistenceRoot
        Returns:
        Root directory of this Run on the controller. Never null

      • getArtifactManager

        @NonNull
public final ArtifactManager getArtifactManager()
        Gets an object responsible for storing and retrieving build artifacts. If pickArtifactManager() has previously been called on this build, and a nondefault manager selected, that will be returned. Otherwise (including if we are loading a historical build created prior to this feature) StandardArtifactManager is used.

        This method should be used when existing artifacts are to be loaded, displayed, or removed. If adding artifacts, use pickArtifactManager() instead.

        Returns:
        an appropriate artifact manager
        Since:
        1.532

      • pickArtifactManager

        @NonNull
public final ArtifactManager pickArtifactManager()
                                          throws IOException
        Selects an object responsible for storing and retrieving build artifacts. The first time this is called on a running build, ArtifactManagerConfiguration is checked to see if one will handle this build. If so, that manager is saved in the build and it will be used henceforth. If no manager claimed the build, StandardArtifactManager is used.

        This method should be used when a build step expects to archive some artifacts. If only displaying existing artifacts, use getArtifactManager() instead.

        Returns:
        an appropriate artifact manager
        Throws:
        IOException - if a custom manager was selected but the selection could not be saved
        Since:
        1.532

      • getArtifactsDir

        @Deprecated
public File getArtifactsDir()
        Deprecated.
        Should only be used from StandardArtifactManager or subclasses.
        Gets the directory where the artifacts are archived.

      • getArtifacts

        @Exported
@NonNull
public List<Run.Artifact> getArtifacts()
        Gets the artifacts (relative to getArtifactsDir().
        Returns:
        The list can be empty but never null

      • getArtifactsUpTo

        @NonNull
public List<Run.Artifact> getArtifactsUpTo​(int artifactsNumber)
        Gets the first N artifacts.
        Returns:
        The list can be empty but never null

      • getHasArtifacts

        public boolean getHasArtifacts()
        Check if the Run contains artifacts. The strange method name is so that we can access it from EL.
        Returns:
        true if this run has any artifacts

      • getBuildFingerprints

        @NonNull
@Exported(name="fingerprint",
          inline=true,
          visibility=-1)
public Collection<Fingerprint> getBuildFingerprints()
        get the fingerprints associated with this build
        Returns:
        The fingerprints

      • getLogFile

        @Deprecated
@NonNull
public File getLogFile()
        Deprecated.
        Assumes file-based storage of the log, which is not necessarily the case for Pipelines after JEP-210. Use other methods giving various kinds of streams such as getLogReader(), getLogInputStream(), or getLogText().
        Returns the log file.
        Returns:
        The file may reference both uncompressed or compressed logs

      • getLogInputStream

        @NonNull
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. If the log file does not exist, the error message will be returned to the output.
        Throws:
        IOException
        Since:
        1.349

      • writeLogTo

        public void writeLogTo​(long offset,
                       @NonNull
                       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

      • getApi

        @NonNull
public Api getApi()

      • getACL

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

      • onStartBuilding

        protected void onStartBuilding()
        Called when a job started building.

      • onEndBuilding

        protected void onEndBuilding()
        Called when a job finished building normally or abnormally.

      • writeReplace

        protected Object writeReplace()

      • getLog

        @Deprecated
@NonNull
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.
        Returns:
        Returns the log or an empty string if it has not been found
        Throws:
        IOException

      • getLog

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

        @NonNull
public String getBuildStatusUrl()

      • getBuildStatusIconClassName

        public String getBuildStatusIconClassName()

      • getBuildStatusSummary

        @NonNull
public Run.Summary getBuildStatusSummary()
        Gets an object which represents the single line summary of the status of this build (especially in comparison with the previous build.)
        See Also:
        Run.StatusSummarizer

      • doArtifact

        @NonNull
public DirectoryBrowserSupport doArtifact()
        Serves the artifacts.
        Throws:
        org.springframework.security.access.AccessDeniedException - Access denied

      • 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

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

      • 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

      • 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

      • getEnvironment

        @NonNull
public EnvVars getEnvironment​(@NonNull
                              TaskListener listener)
                       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.

        Returns:
        the map with the environmental variables.
        Throws:
        IOException
        InterruptedException
        Since:
        1.305

      • getCharacteristicEnvVars

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

      • getEstimatedDuration

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

      • getDynamic

        public Object getDynamic​(String token,
                         org.kohsuke.stapler.StaplerRequest req,
                         org.kohsuke.stapler.StaplerResponse rsp)
        Overrides:
        getDynamic in class Actionable

      • getTarget

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Object getTarget()
        Specified by:
        getTarget in interface org.kohsuke.stapler.StaplerProxy