hudson.plugins.git.util

Class BuildChooser

java.lang.Object

hudson.plugins.git.util.BuildChooser

All Implemented Interfaces:

hudson.ExtensionPoint, hudson.model.Describable<BuildChooser>, Serializable

Direct Known Subclasses:

AbstractGitSCMSource.SpecificRevisionBuildChooser, DefaultBuildChooser, InverseBuildChooser

public abstract class BuildChooser
extends Object
implements hudson.ExtensionPoint, hudson.model.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:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

hudson.ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
GitSCM	gitSCM Refers back to the GitSCM that owns this build chooser.

Constructor Summary

Constructors

Constructor and Description
BuildChooser()

Method Summary

Methods

Modifier and Type	Method and Description
static hudson.DescriptorExtensionList<BuildChooser,BuildChooserDescriptor>	all() All the registered build choosers.
static List<BuildChooserDescriptor>	allApplicableTo(hudson.model.Item item) All the registered build choosers that are applicable to the specified item.
Collection<hudson.plugins.git.Revision>	getCandidateRevisions(boolean isPollCall, String singleBranch, org.jenkinsci.plugins.gitclient.GitClient git, hudson.model.TaskListener listener, BuildData buildData, BuildChooserContext context) Get a list of revisions that are candidates to be built.
Collection<hudson.plugins.git.Revision>	getCandidateRevisions(boolean isPollCall, String singleBranch, hudson.plugins.git.IGitAPI git, hudson.model.TaskListener listener, BuildData buildData) Deprecated. as of 1.1.17 Use and override getCandidateRevisions(boolean, String, IGitAPI, TaskListener, BuildData, BuildChooserContext)
Collection<hudson.plugins.git.Revision>	getCandidateRevisions(boolean isPollCall, String singleBranch, hudson.plugins.git.IGitAPI git, hudson.model.TaskListener listener, BuildData buildData, BuildChooserContext context) Deprecated. as of 1.2.0 Use and override getCandidateRevisions(boolean, String, org.jenkinsci.plugins.gitclient.GitClient, hudson.model.TaskListener, BuildData, BuildChooserContext)
BuildChooserDescriptor	getDescriptor()
String	getDisplayName() Short-hand to get to the display name.
void	prepareWorkingTree(org.jenkinsci.plugins.gitclient.GitClient git, hudson.model.TaskListener listener, BuildChooserContext context) 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).
Build	prevBuildForChangelog(String branch, BuildData data, org.jenkinsci.plugins.gitclient.GitClient git, BuildChooserContext context) Determines the baseline to compute the changelog against.
Build	prevBuildForChangelog(String branch, BuildData data, hudson.plugins.git.IGitAPI git) Deprecated. as of 1.1.25 Use and override prevBuildForChangelog(String, BuildData, IGitAPI, BuildChooserContext)
Build	prevBuildForChangelog(String branch, BuildData data, hudson.plugins.git.IGitAPI git, BuildChooserContext context) Deprecated. as of 1.2.0 Use and override prevBuildForChangelog(String, BuildData, org.jenkinsci.plugins.gitclient.GitClient, BuildChooserContext)

Methods inherited from class java.lang.Object

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

Field Detail

gitSCM

public transient GitSCM gitSCM

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

Constructor Detail

BuildChooser

public BuildChooser()

Method Detail

getDisplayName

public final String getDisplayName()

Short-hand to get to the display name.

getCandidateRevisions

public Collection<hudson.plugins.git.Revision> getCandidateRevisions(boolean isPollCall,
                                                            String singleBranch,
                                                            org.jenkinsci.plugins.gitclient.GitClient git,
                                                            hudson.model.TaskListener listener,
                                                            BuildData buildData,
                                                            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 master.

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.

context - Object that provides access back to the model object. This is because the build chooser can be invoked on a slave 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

hudson.plugins.git.GitException

InterruptedException

getCandidateRevisions

public Collection<hudson.plugins.git.Revision> getCandidateRevisions(boolean isPollCall,
                                                            String singleBranch,
                                                            hudson.plugins.git.IGitAPI git,
                                                            hudson.model.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)

Throws:

hudson.plugins.git.GitException

IOException

InterruptedException

getCandidateRevisions

public Collection<hudson.plugins.git.Revision> getCandidateRevisions(boolean isPollCall,
                                                            String singleBranch,
                                                            hudson.plugins.git.IGitAPI git,
                                                            hudson.model.TaskListener listener,
                                                            BuildData buildData)
                                                              throws hudson.plugins.git.GitException,
                                                                     IOException

Deprecated. as of 1.1.17 Use and override getCandidateRevisions(boolean, String, IGitAPI, TaskListener, BuildData, BuildChooserContext)

Throws:

hudson.plugins.git.GitException

IOException

prevBuildForChangelog

public Build prevBuildForChangelog(String branch,
                          @Nullable
                          BuildData data,
                          hudson.plugins.git.IGitAPI git)

Deprecated. as of 1.1.25 Use and override prevBuildForChangelog(String, BuildData, IGitAPI, BuildChooserContext)

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, 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 a slave where there's no direct access to the build/project for which this is invoked.

Throws:

IOException

InterruptedException

prevBuildForChangelog

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)

Throws:

IOException

InterruptedException

getDescriptor

public BuildChooserDescriptor getDescriptor()

Specified by:

getDescriptor in interface hudson.model.Describable<BuildChooser>

all

public static hudson.DescriptorExtensionList<BuildChooser,BuildChooserDescriptor> all()

All the registered build choosers.

allApplicableTo

public static List<BuildChooserDescriptor> allApplicableTo(hudson.model.Item item)

All the registered build choosers that are applicable to the specified item.

Parameters:

item - the item.

prepareWorkingTree

@ParametersAreNonnullByDefault
public void prepareWorkingTree(org.jenkinsci.plugins.gitclient.GitClient git,
                                                    hudson.model.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 master so implementation can interact with Jenkins model

Throws:

IOException

InterruptedException