Package io.jenkins.plugins.forensics.reference

Class SimpleReferenceRecorder

java.lang.Object
hudson.tasks.BuildStepCompatibilityLayer
hudson.tasks.Publisher
hudson.tasks.Recorder
io.jenkins.plugins.forensics.reference.SimpleReferenceRecorder
All Implemented Interfaces:
ExtensionPoint, Describable<Publisher>, BuildStep, SimpleBuildStep
Direct Known Subclasses:
ReferenceRecorder
public class SimpleReferenceRecorder extends Recorder implements SimpleBuildStep
A simple recorder that discovers a reference build from another given reference job.

Several plugins that report build statistics (test results, code coverage, metrics, static analysis warnings) typically show their reports in two different ways: either as absolute report (e.g., total number of tests or warnings, overall code coverage) or as relative delta report (e.g., additional tests, increased or decreased coverage, new or fixed warnings). To compute a relative delta report, a plugin needs to carefully select the other build to compare the current results to (a so-called reference build). For simple Jenkins jobs that build the main branch of an SCM, the reference build will be selected from one of the previous builds of the same job. For more complex branch source projects (i.e., projects that build several branches and pull requests in a connected job hierarchy) it makes more sense to select a reference build from a job that builds the actual target branch (i.e., the branch the current changes will be merged into). Here one typically is interested what changed in a branch or pull request with respect to the main branch (or any other target branch): e.g., how will the code coverage change if the team merges the changes. Selecting the correct reference build is not that easy, since the main branch of a project will evolve more frequently than a specific feature or bugfix branch.

This recorder unifies the computation of the reference build so consuming plugins can simply use the resulting ReferenceBuild in order to get a reference for their delta reports.

Author:
Arne Schöntag, Ullrich Hafner

  • Constructor Details

    • SimpleReferenceRecorder

      @DataBoundConstructor public SimpleReferenceRecorder()
      Creates a new instance of SimpleReferenceRecorder.

    • SimpleReferenceRecorder

      protected SimpleReferenceRecorder(io.jenkins.plugins.util.JenkinsFacade jenkins)
      Creates a new instance of ReferenceRecorder.
      Parameters:
      jenkins - facade to Jenkins

  • Method Details

    • readResolve

      protected Object readResolve()
      Called after deserialization to retain backward compatibility.
      Returns:
      this

    • setReferenceJob

      @DataBoundSetter public void setReferenceJob(String referenceJob)
      Sets the reference job: this job will be used as a baseline to search for the best matching reference build. If the reference job should be computed automatically (supported by multi-branch projects only), then let this field empty. If the reference job is not defined and cannot be computed automatically, then the current job will be used.
      Parameters:
      referenceJob - the name of reference job

    • getReferenceJob

      public String getReferenceJob()
      Returns the name of the reference job.
      Returns:
      the name of reference job

    • setRequiredResult

      @DataBoundSetter public void setRequiredResult(Result requiredResult)
      Sets that required build result of the reference build. If the reference build has a worse status, then the selected reference build will not be used.
      Parameters:
      requiredResult - the minimum required build result

    • getRequiredResult

      public Result getRequiredResult()

    • hasRequiredResult

      protected boolean hasRequiredResult(Run<?,?> referenceBuild)
      Returns whether the specified build has a result that is better or equal than the required result.
      Parameters:
      referenceBuild - the reference build to check
      Returns:
      true if the build has a result that is better or equal than the required result, false otherwise

    • getRequiredMonitorService

      public BuildStepMonitor getRequiredMonitorService()
      Specified by:
      getRequiredMonitorService in interface BuildStep

    • getDescriptor

      public SimpleReferenceRecorder.SimpleReferenceRecorderDescriptor getDescriptor()
      Specified by:
      getDescriptor in interface Describable<Publisher>
      Overrides:
      getDescriptor in class Recorder

    • perform

      public void perform(@NonNull Run<?,?> run, @NonNull FilePath workspace, @NonNull EnvVars env, @NonNull Launcher launcher, @NonNull TaskListener listener)
      Specified by:
      perform in interface SimpleBuildStep

    • setConsiderRunningBuild

      @DataBoundSetter public void setConsiderRunningBuild(boolean considerRunningBuild)
      If enabled, then running builds will be considered as reference build as well. Otherwise, only completed builds are considered. Enabling this option might cause problems if the reference build has not yet all the required results available.
      Parameters:
      considerRunningBuild - if true then running builds will be considered as reference build as well

    • isConsiderRunningBuild

      public boolean isConsiderRunningBuild()

    • findReferenceBuild

      protected ReferenceBuild findReferenceBuild(Run<?,?> run, edu.hm.hafner.util.FilteredLog log)

    • logNoBuildFound

      protected void logNoBuildFound(Job<?,?> reference, edu.hm.hafner.util.FilteredLog log)

    • getReferenceBuildWithRequiredStatus

      protected Optional<ReferenceBuild> getReferenceBuildWithRequiredStatus(Run<?,?> run, Run<?,?> start, edu.hm.hafner.util.FilteredLog log)
      Returns a reference build that satisfied the required status. Starting with the specified start build, the history of builds is searched for a build that satisfies the required status. If no such build is found, then a null object is returned.
      Parameters:
      run - the run that is currently built
      start - the first build to start the search
      log - the logger
      Returns:
      the reference build that satisfies the required status (or empty if no such build is found)

    • createEmptyReferenceBuild

      protected ReferenceBuild createEmptyReferenceBuild(Run<?,?> run, edu.hm.hafner.util.FilteredLog messages)

    • resolveReferenceJob

      protected Optional<Job<?,?>> resolveReferenceJob(edu.hm.hafner.util.FilteredLog log)
      Finds a reference job that should be used as a starting point to find the reference build.
      Parameters:
      log - the logger
      Returns:
      the reference job (if available)

    • findJob

      protected Optional<Job<?,?>> findJob(String jobName, edu.hm.hafner.util.FilteredLog log)
      Finds a job with the given name.
      Parameters:
      jobName - the name of the job
      log - the logger
      Returns:
      the job with the given name (if existing)

    • getLastBuild

      protected Optional<Run<?,?>> getLastBuild(Job<?,?> reference)
      Returns the last build of the specified reference job. If the reference build is not completed and the option considerRunningBuild is set, then the last running build is returned. Otherwise, the last completed build is returned.
      Parameters:
      reference - the reference job
      Returns:
      the last build of the reference job