jenkins.scm.api

Class SCMSource

java.lang.Object

hudson.model.AbstractDescribableImpl<SCMSource>

jenkins.scm.api.SCMSource

All Implemented Interfaces:

ExtensionPoint, Describable<SCMSource>

Direct Known Subclasses:

NullSCMSource, SingleSCMSource

@ExportedBean
public abstract class SCMSource
extends AbstractDescribableImpl<SCMSource>
implements ExtensionPoint

A SCMSource is responsible for fetching SCMHead and corresponding SCMRevision instances from which it can build SCM instances that are configured to check out the specific SCMHead at the specified SCMRevision. Each SCMSource is owned by a SCMSourceOwner, if you need to find all the owners use SCMSourceOwners.all() to iterate through them, e.g. to notify SCMSource instances of push notification from the server they source SCMHeads from. NOTE: This layer does not cache remote calls but can cache intermediary results. For example, with Subversion it is acceptable to cache the last revisions of various directory entries to minimize network round trips, but any of the calls to fetch(TaskListener), fetch(SCMHeadObserver, hudson.model.TaskListener) or fetch(SCMHead, hudson.model.TaskListener) must involve at least one network round trip to validate any cached information.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SCMSource.SourceByItem Means of locating a head given an item.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
static AlternativeUiTextProvider.Message<SCMSource>	PRONOUN Replaceable pronoun of that points to a SCMSource.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SCMSource() Constructor.
protected	SCMSource(String id) Deprecated.

Method Summary

Modifier and Type	Method and Description
void	afterSave() Callback from the SCMSourceOwner after the SCMSourceOwner has been saved.
SCM	build(SCMHead head) Builds a SCM instance for the specified head.
abstract SCM	build(SCMHead head, SCMRevision revision) Builds a SCM instance for the specified head and revision, no validation of the head is performed, a revision for a different head or source will be treated as equivalent to a null revision.
boolean	canProbe() Tests if this SCMSource can instantiate a SCMSourceCriteria.Probe
protected void	checkInterrupt() Checks the Thread.interrupted() and throws an InterruptedException if it was set.
protected SCMProbe	createProbe(SCMHead head, SCMRevision revision) Creates a SCMProbe for the specified SCMHead and SCMRevision.
protected TaskListener	defaultListener(TaskListener listener) Turns a possibly null TaskListener reference into a guaranteed non-null reference.
boolean	equals(Object o)
<O extends SCMHeadObserver> O	fetch(O observer, SCMHeadEvent<?> event, TaskListener listener) Fetches the latest heads and corresponding revisions scoped against a specific event.
<O extends SCMHeadObserver> O	fetch(O observer, TaskListener listener) Fetches the latest heads and corresponding revisions.
SCMRevision	fetch(SCMHead head, TaskListener listener) Gets the current head revision of the specified head.
<O extends SCMHeadObserver> O	fetch(SCMSourceCriteria criteria, O observer, SCMHeadEvent<?> event, TaskListener listener) Fetches the latest heads and corresponding revisions scoped against a specific event.
<O extends SCMHeadObserver> O	fetch(SCMSourceCriteria criteria, O observer, TaskListener listener) Fetches the latest heads and corresponding revisions.
SCMRevision	fetch(String thingName, TaskListener listener) Looks up a specific thingName based on some SCM-specific set of permissible syntaxes.
Set<SCMHead>	fetch(TaskListener listener) Fetches the current list of heads.
List<Action>	fetchActions(SCMHead head, SCMHeadEvent event, TaskListener listener) Fetches any actions that should be persisted for objects related to the specified head.
List<Action>	fetchActions(SCMRevision revision, SCMHeadEvent event, TaskListener listener) Fetches any actions that should be persisted for objects related to the specified revision.
List<Action>	fetchActions(SCMSourceEvent event, TaskListener listener) Fetches any actions that should be persisted for objects related to the specified source.
Set<String>	fetchRevisions(TaskListener listener) Looks up suggested revisions that could be passed to fetch(String, TaskListener).
protected SCMProbe	fromSCMFileSystem(SCMHead head, SCMRevision revision) Helper method for subclasses that have implemented a SCMFileSystem.Builder and want to use a simple non-caching SCMProbe based off of the SCMFileSystem.
Set<? extends SCMHeadCategory>	getCategories() Returns the set of SCMHeadCategory that this SCMSource supports.
protected SCMSourceCriteria	getCriteria() Returns the branch criteria.
SCMSourceDescriptor	getDescriptor()
String	getId() The ID of this source.
SCMSourceOwner	getOwner() Gets the owner.
String	getPronoun() Get the term used in the UI to represent this kind of SCMSource.
List<SCMSourceTrait>	getTraits() Gets the traits for this source.
SCMRevision	getTrustedRevision(SCMRevision revision, TaskListener listener) Enables a source to request that an alternative revision be used to obtain security-sensitive build instructions.
int	hashCode()
boolean	hasId() Returns true if and only if this SCMSource has been assigned an ID.
protected boolean	isCategoryEnabled(SCMHeadCategory category) Sub-classes can override this method to filter the categories that are available from a specific source.
SCMProbe	newProbe(SCMHead head, SCMRevision revision) Creates a SCMProbe for the specified SCMHead and SCMRevision.
Map<SCMHead,SCMRevision>	parentHeads(SCMHead head, TaskListener listener) Looks up the immediate parent heads of the specified head within the specified source.
Set<SCMRevision>	parentRevisions(SCMHead head, SCMRevision revision, TaskListener listener) Looks up the immediate parent revision(s) of the specified revision within the specified head.
protected void	retrieve(SCMHeadObserver observer, TaskListener listener) Deprecated. prefer implementing retrieve(SCMSourceCriteria, SCMHeadObserver, SCMHeadEvent, TaskListener)
protected SCMRevision	retrieve(SCMHead head, TaskListener listener) SPI: Gets the current head revision of the specified head.
protected abstract void	retrieve(SCMSourceCriteria criteria, SCMHeadObserver observer, SCMHeadEvent<?> event, TaskListener listener) SPI: Fetches the latest heads and corresponding revisions that are originating from the supplied event.
protected void	retrieve(SCMSourceCriteria criteria, SCMHeadObserver observer, TaskListener listener) Deprecated. prefer implementing retrieve(SCMSourceCriteria, SCMHeadObserver, SCMHeadEvent, TaskListener)
protected Set<SCMHead>	retrieve(SCMSourceCriteria criteria, TaskListener listener) SPI: Fetches the current list of heads.
protected SCMRevision	retrieve(String thingName, TaskListener listener) SPI: Looks up a specific revision based on some SCM-specific set of permissible syntaxes.
protected Set<SCMHead>	retrieve(TaskListener listener) SPI: Fetches the current list of heads.
protected List<Action>	retrieveActions(SCMHead head, SCMHeadEvent event, TaskListener listener) SPI for fetchActions(SCMHead, SCMHeadEvent, TaskListener).
protected List<Action>	retrieveActions(SCMRevision revision, SCMHeadEvent event, TaskListener listener) SPI for fetchActions(SCMRevision, SCMHeadEvent, TaskListener).
protected List<Action>	retrieveActions(SCMSourceEvent event, TaskListener listener) SPI for fetchActions(SCMSourceEvent,TaskListener).
protected Set<String>	retrieveRevisions(TaskListener listener) SPI: Looks up suggested revisions that could be passed to fetch(String, TaskListener).
void	setId(String id) Sets the ID that is used to ensure this SCMSource can be retrieved from its SCMSourceOwner provided that this SCMSource does not already hasId().
void	setOwner(SCMSourceOwner owner) Sets the owner.
void	setTraits(List<SCMSourceTrait> traits) Sets the traits for this source.
String	toString()
SCMSource	withId(String id) Variant of setId(String) that can be useful for method chaining.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PRONOUN

public static final AlternativeUiTextProvider.Message<SCMSource> PRONOUN

Replaceable pronoun of that points to a SCMSource. Defaults to null depending on the context.

Since:

2.0

Constructor Detail

SCMSource

@Deprecated
protected SCMSource(@CheckForNull
                                String id)

Deprecated.

Constructor.

Parameters:

id - the id or null.

SCMSource

protected SCMSource()

Constructor.

Method Detail

setId

@DataBoundSetter
public final void setId(@CheckForNull
                                         String id)

Sets the ID that is used to ensure this SCMSource can be retrieved from its SCMSourceOwner provided that this SCMSource does not already hasId().

Note this is a one-shot setter. If getId() is called first, then its value will stick, otherwise the first call to setId(String) will stick.

Parameters:

id - the ID, this is an opaque token expected to be unique within any one SCMSourceOwner.

Since:

2.2.0

See Also:

hasId(), getId()

withId

public final SCMSource withId(@CheckForNull
                              String id)

Variant of setId(String) that can be useful for method chaining.

Parameters:

id - the ID

Returns:

this for method chaining

hasId

public final boolean hasId()

Returns true if and only if this SCMSource has been assigned an ID. Once an ID has been assigned it should be preserved.

Returns:

true if and only if this SCMSource has been assigned an ID.

Since:

2.2.0

See Also:

setId(String), getId()

getId

@NonNull
public final String getId()

The ID of this source. The ID is not related to anything at all. If this SCMSource does not have an ID then one will be generated.

Returns:

the ID of this source.

See Also:

setId(String), hasId()

setTraits

public void setTraits(@CheckForNull
                      List<SCMSourceTrait> traits)

Sets the traits for this source. No-op by default.

Parameters:

traits - the list of traits

getTraits

@CheckForNull
public List<SCMSourceTrait> getTraits()

Gets the traits for this source.

Returns:

traits the list of traits, empty by default.

setOwner

public final void setOwner(@CheckForNull
                           SCMSourceOwner owner)

Sets the owner.

Parameters:

owner - the owner.

getOwner

@CheckForNull
public final SCMSourceOwner getOwner()

Gets the owner.

Returns:

the owner.

getCriteria

@CheckForNull
protected final SCMSourceCriteria getCriteria()

Returns the branch criteria.

Returns:

the branch criteria.

fetch

@NonNull
public final <O extends SCMHeadObserver> O fetch(@NonNull
                                                          O observer,
                                                          @CheckForNull
                                                          TaskListener listener)
                                                   throws IOException,
                                                          InterruptedException

Fetches the latest heads and corresponding revisions. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Type Parameters:

O - Observer type.

Parameters:

observer - an optional observer of interim results.

listener - the task listener

Returns:

the provided observer.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

fetch

@NonNull
public final <O extends SCMHeadObserver> O fetch(@CheckForNull
                                                          SCMSourceCriteria criteria,
                                                          @NonNull
                                                          O observer,
                                                          @CheckForNull
                                                          TaskListener listener)
                                                   throws IOException,
                                                          InterruptedException

Fetches the latest heads and corresponding revisions. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Type Parameters:

O - Observer type.

Parameters:

criteria - the criteria to use.

observer - an optional observer of interim results.

listener - the task listener

Returns:

the provided observer.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

fetch

@NonNull
public final <O extends SCMHeadObserver> O fetch(@CheckForNull
                                                          SCMSourceCriteria criteria,
                                                          @NonNull
                                                          O observer,
                                                          @CheckForNull
                                                          SCMHeadEvent<?> event,
                                                          @CheckForNull
                                                          TaskListener listener)
                                                   throws IOException,
                                                          InterruptedException

Fetches the latest heads and corresponding revisions scoped against a specific event. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Type Parameters:

O - Observer type.

Parameters:

criteria - the criteria to use.

observer - an observer of interim results.

event - the (optional) event from which the fetch should be scoped.

listener - the task listener

Returns:

the provided observer.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

fetch

@NonNull
public final <O extends SCMHeadObserver> O fetch(@NonNull
                                                          O observer,
                                                          @CheckForNull
                                                          SCMHeadEvent<?> event,
                                                          @CheckForNull
                                                          TaskListener listener)
                                                   throws IOException,
                                                          InterruptedException

Fetches the latest heads and corresponding revisions scoped against a specific event. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Type Parameters:

O - Observer type.

Parameters:

observer - an observer of interim results.

event - the (optional) event from which the fetch should be scoped.

listener - the task listener

Returns:

the provided observer.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

retrieve

@Deprecated
protected void retrieve(@NonNull
                                    SCMHeadObserver observer,
                                    @NonNull
                                    TaskListener listener)
                             throws IOException,
                                    InterruptedException

Deprecated. prefer implementing retrieve(SCMSourceCriteria, SCMHeadObserver, SCMHeadEvent, TaskListener)

SPI: Fetches the latest heads and corresponding revisions. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Parameters:

observer - an optional observer of interim results.

listener - the task listener.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

retrieve

@Deprecated
protected void retrieve(@CheckForNull
                                    SCMSourceCriteria criteria,
                                    @NonNull
                                    SCMHeadObserver observer,
                                    @NonNull
                                    TaskListener listener)
                             throws IOException,
                                    InterruptedException

Deprecated. prefer implementing retrieve(SCMSourceCriteria, SCMHeadObserver, SCMHeadEvent, TaskListener)

SPI: Fetches the latest heads and corresponding revisions. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches. It is vitally important that implementations must periodically call checkInterrupt() otherwise it will be impossible for users to interrupt the operation.

Parameters:

criteria - the criteria to use, if non-null them implementations mustfilter all SCMHead instances against the SCMSourceCriteria.isHead(SCMSourceCriteria.Probe, TaskListener) before passing through to the SCMHeadObserver.

observer - an optional observer of interim results.

listener - the task listener.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

retrieve

protected abstract void retrieve(@CheckForNull
                                 SCMSourceCriteria criteria,
                                 @NonNull
                                 SCMHeadObserver observer,
                                 @CheckForNull
                                 SCMHeadEvent<?> event,
                                 @NonNull
                                 TaskListener listener)
                          throws IOException,
                                 InterruptedException

SPI: Fetches the latest heads and corresponding revisions that are originating from the supplied event. If the supplied event is one that the implementer trusts, then the implementer may be able to optimize retrieval to minimize round trips. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

It is vitally important that implementations must periodically call checkInterrupt() otherwise it will be impossible for users to interrupt the operation.

The default implementation wraps the SCMHeadObserver using SCMHeadEvent.filter(SCMSource, SCMHeadObserver) and delegates to retrieve(SCMSourceCriteria, SCMHeadObserver, TaskListener)

Parameters:

criteria - the criteria to use, if non-null them implementations mustfilter all SCMHead instances against the SCMSourceCriteria.isHead(SCMSourceCriteria.Probe, TaskListener) before passing through to the SCMHeadObserver.

observer - an observer of interim results, if the event is non-null then the observer will already have been filtered with SCMHeadEvent.filter(SCMSource, SCMHeadObserver).

event - the (optional) event from which the operation should be scoped.

listener - the task listener.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

fetch

@NonNull
public final Set<SCMHead> fetch(@CheckForNull
                                         TaskListener listener)
                                  throws IOException,
                                         InterruptedException

Fetches the current list of heads. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Parameters:

listener - the task listener

Returns:

the current list of heads.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

parentRevisions

@NonNull
public Set<SCMRevision> parentRevisions(@NonNull
                                                 SCMHead head,
                                                 @NonNull
                                                 SCMRevision revision,
                                                 @CheckForNull
                                                 TaskListener listener)
                                          throws IOException,
                                                 InterruptedException

Looks up the immediate parent revision(s) of the specified revision within the specified head.

Parameters:

head - the head to look up the parent revision(s) within.

revision - the revision to lookup the immediate parent(s) of.

listener - the task listener.

Returns:

a set of immediate parent revisions of the specified revision. An empty set indicates either that the parents are unknown or that the revision is a root revision. Where the backing SCM supports merge tracking there is the potential for multiple parent revisions reflecting that the specified revision was a merge of more than one revision and thus has more than one parent.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

0.3

parentHeads

@NonNull
public Map<SCMHead,SCMRevision> parentHeads(@NonNull
                                                     SCMHead head,
                                                     @CheckForNull
                                                     TaskListener listener)
                                              throws IOException,
                                                     InterruptedException

Looks up the immediate parent heads of the specified head within the specified source.

Parameters:

head - the head to look up the parent head(s) within.

listener - the task listener.

Returns:

a map of immediate parent heads of the specified head where the heads are the keys and the revisions at which the parent relationship was established are the values. An empty map indicates either that the parents are unknown or that the head is a root head. Where the backing SCM supports merge tracking there is the potential for multiple parent heads reflecting that the specified head was a merge of more than one head and thus has more than one parent.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

0.3

retrieve

@NonNull
protected Set<SCMHead> retrieve(@NonNull
                                         TaskListener listener)
                                  throws IOException,
                                         InterruptedException

SPI: Fetches the current list of heads. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Parameters:

listener - the task listener

Returns:

the current list of heads.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

retrieve

@NonNull
protected Set<SCMHead> retrieve(@CheckForNull
                                         SCMSourceCriteria criteria,
                                         @NonNull
                                         TaskListener listener)
                                  throws IOException,
                                         InterruptedException

SPI: Fetches the current list of heads. Implementers are free to cache intermediary results but the call must always check the validity of any intermediary caches.

Parameters:

criteria - the criteria to use for identifying heads.

listener - the task listener

Returns:

the current list of heads.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

fetch

@CheckForNull
public final SCMRevision fetch(@NonNull
                                             SCMHead head,
                                             @CheckForNull
                                             TaskListener listener)
                                      throws IOException,
                                             InterruptedException

Gets the current head revision of the specified head. Does not check this against any SCMSourceCriteria.

Parameters:

head - the head.

listener - the task listener

Returns:

the revision hash (may be non-deterministic) or null if the head no longer exists.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

retrieve

@CheckForNull
protected SCMRevision retrieve(@NonNull
                                             SCMHead head,
                                             @NonNull
                                             TaskListener listener)
                                      throws IOException,
                                             InterruptedException

SPI: Gets the current head revision of the specified head. Does not check this against any SCMSourceCriteria.

Parameters:

head - the head.

listener - the task listener

Returns:

the revision hash (may be non-deterministic) or null if the head no longer exists.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

fetch

@CheckForNull
public final SCMRevision fetch(@NonNull
                                             String thingName,
                                             @CheckForNull
                                             TaskListener listener)
                                      throws IOException,
                                             InterruptedException

Looks up a specific thingName based on some SCM-specific set of permissible syntaxes. Delegates to retrieve(String, TaskListener).

Parameters:

thingName - might be a branch name, a tag name, a cryptographic hash, a change request number, etc.

listener - the task listener (optional)

Returns:

a valid SCMRevision corresponding to the argument, with a usable corresponding head, or null if malformed or not found

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

1.3

retrieve

@CheckForNull
protected SCMRevision retrieve(@NonNull
                                             String thingName,
                                             @NonNull
                                             TaskListener listener)
                                      throws IOException,
                                             InterruptedException

SPI: Looks up a specific revision based on some SCM-specific set of permissible syntaxes. The default implementation uses retrieve(SCMSourceCriteria, SCMHeadObserver, TaskListener) and looks for SCMHead.getName() matching the argument (so typically only supporting branch names).

Parameters:

thingName - might be a branch name, a tag name, a cryptographic hash, a revision number, etc.

listener - the task listener

Returns:

a valid revision object corresponding to the argument, with a usable corresponding head, or null if malformed or not found

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

1.3

fetchRevisions

@NonNull
public final Set<String> fetchRevisions(@CheckForNull
                                                 TaskListener listener)
                                          throws IOException,
                                                 InterruptedException

Looks up suggested revisions that could be passed to fetch(String, TaskListener). There is no guarantee that all returned revisions are in fact valid, nor that all valid revisions are returned. Delegates to retrieveRevisions(hudson.model.TaskListener).

Parameters:

listener - the task listener

Returns:

a possibly empty set of revision names suggested by the implementation

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

1.3

retrieveRevisions

@NonNull
protected Set<String> retrieveRevisions(@NonNull
                                                 TaskListener listener)
                                          throws IOException,
                                                 InterruptedException

SPI: Looks up suggested revisions that could be passed to fetch(String, TaskListener). There is no guarantee that all returned revisions are in fact valid, nor that all valid revisions are returned. By default, calls retrieve(TaskListener), thus typically returning only branch names.

Parameters:

listener - the task listener

Returns:

a possibly empty set of revision names suggested by the implementation

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

1.3

fetchActions

@NonNull
public final List<Action> fetchActions(@NonNull
                                                SCMRevision revision,
                                                @CheckForNull
                                                SCMHeadEvent event,
                                                @CheckForNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

Fetches any actions that should be persisted for objects related to the specified revision. For example, if a Run is building a specific SCMRevision, then this method would be called to populate any Action instances for that Run. NOTE: unlike fetchActions(SCMHead, SCMHeadEvent, TaskListener), fetchActions(SCMSourceEvent, TaskListener) or SCMNavigator.fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener) there is no guarantee that this method will ever be called more than once for any Run. fetchActions(SCMHead, SCMHeadEvent, TaskListener) must have been called at least once before calling this method.

Parameters:

revision - the SCMRevision

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

fetchActions

@NonNull
public final List<Action> fetchActions(@NonNull
                                                SCMHead head,
                                                @CheckForNull
                                                SCMHeadEvent event,
                                                @CheckForNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

Fetches any actions that should be persisted for objects related to the specified head. For example, if a Job is associated with a specific SCMHead, then this method would be called to refresh any Action instances of that Job. fetchActions(SCMSourceEvent,TaskListener) must have been called at least once before calling this method.

Where a SCMHead is associated with a Item or Job, it is the responsibility of the caller to ensure that these Action instances are exposed on the Item / Job for example by providing a TransientActionFactory implementation that reports these persisted actions separately (for example AbstractProject.getActions() returns an immutable list, so there is no way to persist the actions from this method against those sub-classes, instead the actions need to be persisted by some side mechanism and then injected into the Actionable.getAllActions() through a TransientActionFactory ignoring the cognitive dissonance triggered by adding non-transient actions through a transient action factory... think of it instead as a TemporalActionFactory that adds actions that can change over time)

Parameters:

head - the SCMHead

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

fetchActions

@NonNull
public final List<Action> fetchActions(@CheckForNull
                                                SCMSourceEvent event,
                                                @CheckForNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

Fetches any actions that should be persisted for objects related to the specified source. For example, if a Item is associated with a specific SCMSource, then this method would be called to refresh any Action instances of that Item. If this SCMSource belongs to a SCMNavigator then SCMNavigator.fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener) must have been called at least once before calling this method.

Where a SCMSource is associated with a specific Item, it is the responsibility of the caller to ensure that these Action instances are exposed on the Item for example by providing a TransientActionFactory implementation that reports these persisted actions separately (for example AbstractProject.getActions() returns an immutable list, so there is no way to persist the actions from this method against those sub-classes, instead the actions need to be persisted by some side mechanism and then injected into the Actionable.getAllActions() through a TransientActionFactory ignoring the cognitive dissonance triggered by adding non-transient actions through a transient action factory... think of it instead as a TemporalActionFactory that adds actions that can change over time)

Parameters:

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

retrieveActions

@NonNull
protected List<Action> retrieveActions(@NonNull
                                                SCMRevision revision,
                                                @CheckForNull
                                                SCMHeadEvent event,
                                                @NonNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

SPI for fetchActions(SCMRevision, SCMHeadEvent, TaskListener). Fetches any actions that should be persisted for objects related to the specified revision.

Parameters:

revision - the SCMRevision

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

retrieveActions

@NonNull
protected List<Action> retrieveActions(@NonNull
                                                SCMHead head,
                                                @CheckForNull
                                                SCMHeadEvent event,
                                                @NonNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

SPI for fetchActions(SCMHead, SCMHeadEvent, TaskListener). Fetches any actions that should be persisted for objects related to the specified head.

Parameters:

head - the SCMHead

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

retrieveActions

@NonNull
protected List<Action> retrieveActions(@CheckForNull
                                                SCMSourceEvent event,
                                                @NonNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

SPI for fetchActions(SCMSourceEvent,TaskListener). Fetches any actions that should be persisted for objects related to the specified source.

Parameters:

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

build

@NonNull
public abstract SCM build(@NonNull
                                   SCMHead head,
                                   @CheckForNull
                                   SCMRevision revision)

Builds a SCM instance for the specified head and revision, no validation of the head is performed, a revision for a different head or source will be treated as equivalent to a null revision.

Parameters:

head - the head.

revision - the revision or null.

Returns:

the SCM instance.

build

@NonNull
public final SCM build(@NonNull
                                SCMHead head)

Builds a SCM instance for the specified head.

Parameters:

head - the head.

Returns:

the SCM instance

getTrustedRevision

@NonNull
public SCMRevision getTrustedRevision(@NonNull
                                               SCMRevision revision,
                                               @NonNull
                                               TaskListener listener)
                                        throws IOException,
                                               InterruptedException

Enables a source to request that an alternative revision be used to obtain security-sensitive build instructions.

Normally it is assumed that revisions in the SCM represented by this source come from principals operating with the same authorization as the principal creating the job, or at least with authorization to create a similar job.

A source may however collect revisions from untrusted third parties and submit them for builds. If the project type performing the build loads instructions from the same revision, this might allow the job to be subverted to perform unauthorized build steps or steal credentials.

By replacing the supplied revision with a trusted variant, a source can defend against such attacks. It is up to the project type to determine which files should come from a trusted replacement. Regular project sources should come from the original; Jenkins-specific scripting commands or configuration should come from the replacement, unless easily sandboxed; scripts for external build tools should come from the original if possible.

Parameters:

revision - a revision (produced by one of the retrieve overloads) which may or may not come from a trustworthy source

listener - a way to explain possible substitutions

Returns:

by default, revision; may be overridden to provide an alternate revision from the same or a different head

Throws:

IOException - in case the implementation must call fetch(SCMHead, TaskListener) or similar

InterruptedException - in case the implementation must call fetch(SCMHead, TaskListener) or similar

Since:

1.1

defaultListener

@NonNull
protected final TaskListener defaultListener(@CheckForNull
                                                      TaskListener listener)

Turns a possibly null TaskListener reference into a guaranteed non-null reference.

Parameters:

listener - a possibly null TaskListener reference.

Returns:

guaranteed non-null TaskListener.

canProbe

public boolean canProbe()

Tests if this SCMSource can instantiate a SCMSourceCriteria.Probe

Returns:

true if and only if createProbe(SCMHead, SCMRevision) has been implemented.

Since:

2.0

newProbe

@NonNull
public final SCMProbe newProbe(@NonNull
                                        SCMHead head,
                                        @CheckForNull
                                        SCMRevision revision)
                                 throws IOException

Creates a SCMProbe for the specified SCMHead and SCMRevision. Public exposed API for createProbe(SCMHead, SCMRevision).

Parameters:

head - the SCMHead.

revision - the SCMRevision.

Returns:

the SCMSourceCriteria.Probe.

Throws:

IllegalArgumentException - if the SCMRevision.getHead() is not equal to the supplied SCMHead

IOException - if the probe creation failed due to an IO exception.

Since:

2.0

See Also:

canProbe()

createProbe

@NonNull
protected SCMProbe createProbe(@NonNull
                                        SCMHead head,
                                        @CheckForNull
                                        SCMRevision revision)
                                 throws IOException

Creates a SCMProbe for the specified SCMHead and SCMRevision.

Parameters:

head - the SCMHead.

revision - the SCMRevision.

Returns:

the SCMSourceCriteria.Probe.

Throws:

IOException - if the probe creation failed due to an IO exception.

Since:

2.0

See Also:

canProbe(), newProbe(SCMHead, SCMRevision), fromSCMFileSystem(SCMHead, SCMRevision)

fromSCMFileSystem

@CheckForNull
protected final SCMProbe fromSCMFileSystem(@NonNull
                                                         SCMHead head,
                                                         @CheckForNull
                                                         SCMRevision revision)
                                                  throws IOException,
                                                         InterruptedException

Helper method for subclasses that have implemented a SCMFileSystem.Builder and want to use a simple non-caching SCMProbe based off of the SCMFileSystem.

Parameters:

head - the SCMHead.

revision - the SCMRevision.

Returns:

the SCMSourceCriteria.Probe or null if this source cannot be probed.

Throws:

IOException - if the attempt to create a SCMFileSystem failed due to an IO error (such as the remote system being unavailable)

InterruptedException - if the attempt to create a SCMFileSystem was interrupted.

Since:

2.0

equals

public final boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

getDescriptor

public SCMSourceDescriptor getDescriptor()

Specified by:

getDescriptor in interface Describable<SCMSource>

Overrides:

getDescriptor in class AbstractDescribableImpl<SCMSource>

getPronoun

@CheckForNull
public String getPronoun()

Get the term used in the UI to represent this kind of SCMSource. Must start with a capital letter.

Returns:

the term or null to fall back to the calling context's default.

Since:

2.0

getCategories

@NonNull
public final Set<? extends SCMHeadCategory> getCategories()

Returns the set of SCMHeadCategory that this SCMSource supports. There will always be exactly one SCMCategory.isUncategorized() instance in the returned set.

Returns:

the set of SCMHeadCategory that this SCMSource supports.

Since:

2.0

isCategoryEnabled

protected boolean isCategoryEnabled(@NonNull
                                    SCMHeadCategory category)

Sub-classes can override this method to filter the categories that are available from a specific source. For example a source type might be capable of having mainline branches, user branches, merge requests and release tags while a specific instance of the source may be configured to only have mainline branches and release tags.

Parameters:

category - the category.

Returns:

true if the supplied category is enabled for this SCMSource instance.

Since:

2.0

checkInterrupt

protected final void checkInterrupt()
                             throws InterruptedException

Checks the Thread.interrupted() and throws an InterruptedException if it was set.

Throws:

InterruptedException - if interrupted.

Since:

2.0

afterSave

public void afterSave()

Callback from the SCMSourceOwner after the SCMSourceOwner has been saved. Can be used to register the SCMSourceOwner for a call-back hook from the backing SCM that this source is for. Implementations are responsible for ensuring that they do not create duplicate registrations and that orphaned registrations are removed eventually.

Since:

2.0