Package hudson.plugins.git.util

Class BuildChooser

java.lang.Object
hudson.plugins.git.util.BuildChooser
All Implemented Interfaces:
ExtensionPoint, Describable<BuildChooser>, Serializable
Direct Known Subclasses:
AbstractGitSCMSource.SpecificRevisionBuildChooser, DefaultBuildChooser, InverseBuildChooser
public abstract class BuildChooser extends Object implements ExtensionPoint, Describable<BuildChooser>, Serializable
Interface defining an API to choose which revisions ought to be considered for building.

This object is persisted as a part of the project configuration.

Author:
magnayn, Kohsuke Kawaguchi
See Also:

  • Field Details

    • gitSCM

      public transient GitSCM gitSCM
      Refers back to the GitSCM that owns this build chooser. Do not modify from outside GitSCM.

  • Constructor Details

    • BuildChooser

      public BuildChooser()

  • Method Details

    • getDisplayName

      public final String getDisplayName()
      Short-hand to get to the display name.
      Returns:
      display name of this build chooser

    • getCandidateRevisions

      public Collection<hudson.plugins.git.Revision> getCandidateRevisions(boolean isPollCall, @CheckForNull String singleBranch, @NonNull org.jenkinsci.plugins.gitclient.GitClient git, @NonNull TaskListener listener, @NonNull BuildData buildData, @NonNull BuildChooserContext context) throws hudson.plugins.git.GitException, IOException, InterruptedException
      Get a list of revisions that are candidates to be built.

      This method is invoked on the node where the workspace exists, which may not be the controller.

      Parameters:
      isPollCall - true if this method is called from pollChanges.
      singleBranch - contains the name of a single branch to be built this will be non-null only in the simple case, in advanced cases with multiple repositories and/or branches specified then this value will be null.
      git - Used for invoking Git
      listener - build log
      buildData - build data to be used Information that captures what we did during the last build.
      context - Object that provides access back to the model object. This is because the build chooser can be invoked on an agent where there's no direct access to the build/project for which this is invoked. If isPollCall is false, then call back to both project and build are available. If isPollCall is true, then only the callback to the project is available as there's no contextual build object.
      Returns:
      the candidate revision. Can be an empty set to indicate that there's nothing to build.
      Throws:
      IOException - on input or output error
      hudson.plugins.git.GitException - on git error
      InterruptedException - when interrupted

    • getCandidateRevisions

      @Deprecated public Collection<hudson.plugins.git.Revision> getCandidateRevisions(boolean isPollCall, String singleBranch, hudson.plugins.git.IGitAPI git, TaskListener listener, BuildData buildData, BuildChooserContext context) throws hudson.plugins.git.GitException, IOException, InterruptedException
      Deprecated.
      as of 1.2.0 Use and override getCandidateRevisions(boolean, String, org.jenkinsci.plugins.gitclient.GitClient, hudson.model.TaskListener, BuildData, BuildChooserContext)
      Parameters:
      isPollCall - true if this method is called from pollChanges.
      singleBranch - contains the name of a single branch to be built this will be non-null only in the simple case, in advanced cases with multiple repositories and/or branches specified then this value will be null.
      git - Used for invoking Git
      listener - build log
      buildData - Information that captures what we did during the last build.
      context - Object that provides access back to the model object. This is because the build chooser can be invoked on an agent where there's no direct access to the build/project for which this is invoked. If isPollCall is false, then call back to both project and build are available. If isPollCall is true, then only the callback to the project is available as there's no contextual build object.
      Returns:
      the candidate revision. Can be an empty set to indicate that there's nothing to build.
      Throws:
      IOException - on input or output error
      hudson.plugins.git.GitException - on git error
      InterruptedException - when interrupted

    • getCandidateRevisions

      @Deprecated public Collection<hudson.plugins.git.Revision> getCandidateRevisions(boolean isPollCall, String singleBranch, hudson.plugins.git.IGitAPI git, TaskListener listener, BuildData buildData) throws hudson.plugins.git.GitException, IOException
      Deprecated.
      as of 1.1.17 Use and override getCandidateRevisions(boolean, String, hudson.plugins.git.IGitAPI, TaskListener, BuildData, BuildChooserContext)
      Parameters:
      isPollCall - true if this method is called from pollChanges.
      singleBranch - contains the name of a single branch to be built this will be non-null only in the simple case, in advanced cases with multiple repositories and/or branches specified then this value will be null.
      git - GitClient used to access repository
      listener - build log
      buildData - build data to be used Information that captures what we did during the last build.
      Returns:
      the candidate revision. Can be an empty set to indicate that there's nothing to build.
      Throws:
      IOException - on input or output error
      hudson.plugins.git.GitException - on git error

    • prevBuildForChangelog

      @Deprecated public Build prevBuildForChangelog(String branch, @Nullable BuildData buildData, hudson.plugins.git.IGitAPI git)
      Deprecated.
      as of 1.1.25 Use and override prevBuildForChangelog(String, BuildData, hudson.plugins.git.IGitAPI, BuildChooserContext)
      Parameters:
      branch - contains the name of branch to be built this will be non-null only in the simple case, in advanced cases with multiple repositories and/or branches specified then this value will be null.
      buildData - build data to be used Information that captures what we did during the last build.
      git - Used for invoking Git
      Returns:
      the candidate revision. Can be an empty set to indicate that there's nothi

    • prevBuildForChangelog

      public Build prevBuildForChangelog(String branch, @Nullable BuildData data, org.jenkinsci.plugins.gitclient.GitClient git, BuildChooserContext context) throws IOException, InterruptedException
      Determines the baseline to compute the changelog against.

      getCandidateRevisions(boolean, String, hudson.plugins.git.IGitAPI, TaskListener, BuildData, BuildChooserContext) determine what commits can be subject for a build, and for each commit it determines the branches that contribute to them.

      Once GitSCM picks up a specific Revision to build, for each branch, in that revision, this method is called to compute the changelog.

      Parameters:
      branch - The branch name.
      data - Information that captures what we did during the last build.
      git - Used for invoking Git
      context - Object that provides access back to the model object. This is because the build chooser can be invoked on an agent where there's no direct access to the build/project for which this is invoked.
      Returns:
      candidate revision. Can be an empty set to indicate that there's nothing to build.
      Throws:
      IOException - on input or output error
      InterruptedException - when interrupted

    • prevBuildForChangelog

      @Deprecated public Build prevBuildForChangelog(String branch, @Nullable BuildData data, hudson.plugins.git.IGitAPI git, BuildChooserContext context) throws IOException, InterruptedException
      Deprecated.
      as of 1.2.0 Use and override prevBuildForChangelog(String, BuildData, org.jenkinsci.plugins.gitclient.GitClient, BuildChooserContext)
      Parameters:
      branch - contains the name of a branch to be built this will be non-null only in the simple case, in advanced cases with multiple repositories and/or branches specified then this value will be null.
      data - Information that captures what we did during the last build.
      git - Used for invoking Git
      context - Object that provides access back to the model object. This is because the build chooser can be invoked on an agent where there's no direct access to the build/project for which this is invoked. If isPollCall is false, then call back to both project and build are available. If isPollCall is true, then only the callback to the project is available as there's no contextual build object.
      Returns:
      the candidate revision. Can be an empty set to indicate that there's nothing to build.
      Throws:
      IOException - on I/O error
      hudson.plugins.git.GitException - on git error
      InterruptedException - if interrupted

    • getDescriptor

      public BuildChooserDescriptor getDescriptor()
      Returns build chooser descriptor.
      Specified by:
      getDescriptor in interface Describable<BuildChooser>
      Returns:
      build chooser descriptor

    • all

      public static DescriptorExtensionList<BuildChooser,BuildChooserDescriptor> all()
      All the registered build choosers.
      Returns:
      all registered build choosers

    • allApplicableTo

      public static List<BuildChooserDescriptor> allApplicableTo(Item item)
      All the registered build choosers that are applicable to the specified item.
      Parameters:
      item - the item.
      Returns:
      All build choosers applicable to item

    • prepareWorkingTree

      public void prepareWorkingTree(org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, BuildChooserContext context) throws IOException, InterruptedException
      In a general case, a working tree is a left-over from the previous build, so it can be quite messed up (such as HEAD pointing to a random branch). This method is responsible to bring the working copy to a predictable clean state where candidate revisions can be evaluated.

      Typical use-case is a BuildChooser which do handle pull-request merge for validation. Such a BuildChooser will run the merge on working copy, and expose the merge commit as getCandidateRevisions(boolean, String, org.jenkinsci.plugins.gitclient.GitClient, hudson.model.TaskListener, BuildData, BuildChooserContext)

      Parameters:
      git - client to execute git commands on working tree
      listener - build log
      context - back-channel to controller so implementation can interact with Jenkins model
      Throws:
      IOException - on input or output error
      InterruptedException - when interrupted