@ExportedBean public abstract class SCMSource extends AbstractDescribableImpl<SCMSource> implements ExtensionPoint
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 SCMHead
s 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.Modifier and Type | Class and Description |
---|---|
static class |
SCMSource.SourceByItem
Means of locating a head given an item.
|
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
static AlternativeUiTextProvider.Message<SCMSource> |
PRONOUN
Replaceable pronoun of that points to a
SCMSource . |
Modifier | Constructor and Description |
---|---|
protected |
SCMSource()
Constructor.
|
protected |
SCMSource(String id)
Deprecated.
|
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)
|
protected TaskListener |
defaultListener(TaskListener listener)
Turns a possibly
null TaskListener reference into a guaranteed non-null reference. |
boolean |
equals(Object o) |
<O extends SCMHeadObserver> |
fetch(O observer,
SCMHeadEvent<?> event,
TaskListener listener)
Fetches the latest heads and corresponding revisions scoped against a specific event.
|
<O extends SCMHeadObserver> |
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> |
fetch(SCMSourceCriteria criteria,
O observer,
SCMHeadEvent<?> event,
TaskListener listener)
Fetches the latest heads and corresponding revisions scoped against a specific event.
|
<O extends SCMHeadObserver> |
fetch(SCMSourceCriteria criteria,
O observer,
TaskListener listener)
Fetches the latest heads and corresponding revisions.
|
SCMRevision |
fetch(String thingName,
TaskListener listener)
Deprecated.
rather call
fetch(String, TaskListener, Item) |
SCMRevision |
fetch(String thingName,
TaskListener listener,
Item context)
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)
Deprecated.
rather call
fetchRevisions(TaskListener, Item) |
Set<String> |
fetchRevisions(TaskListener listener,
Item context)
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)
|
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)
Deprecated.
rather override
retrieve(String, TaskListener, Item) |
protected SCMRevision |
retrieve(String thingName,
TaskListener listener,
Item context)
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)
|
protected List<Action> |
retrieveActions(SCMRevision revision,
SCMHeadEvent event,
TaskListener listener)
|
protected List<Action> |
retrieveActions(SCMSourceEvent event,
TaskListener listener)
|
protected Set<String> |
retrieveRevisions(TaskListener listener)
Deprecated.
rather override
retrieveRevisions(TaskListener, Item) |
protected Set<String> |
retrieveRevisions(TaskListener listener,
Item context)
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. |
public static final AlternativeUiTextProvider.Message<SCMSource> PRONOUN
SCMSource
. Defaults to null
depending on the context.@Deprecated protected SCMSource(@CheckForNull String id)
id
- the id or null
.protected SCMSource()
@DataBoundSetter public final void setId(@CheckForNull String id)
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.
id
- the ID, this is an opaque token expected to be unique within any one SCMSourceOwner
.hasId()
,
getId()
public final SCMSource withId(@CheckForNull String id)
setId(String)
that can be useful for method chaining.id
- the IDthis
for method chainingpublic final boolean hasId()
true
if and only if this SCMSource
has been assigned an ID. Once an ID has been assigned
it should be preserved.true
if and only if this SCMSource
has been assigned an ID.setId(String)
,
getId()
@NonNull public final String getId()
SCMSource
does not have an ID
then one will be generated.setId(String)
,
hasId()
public void setTraits(@CheckForNull List<SCMSourceTrait> traits)
traits
- the list of traits@CheckForNull public List<SCMSourceTrait> getTraits()
public final void setOwner(@CheckForNull SCMSourceOwner owner)
owner
- the owner.@CheckForNull public final SCMSourceOwner getOwner()
@CheckForNull protected final SCMSourceCriteria getCriteria()
@NonNull public final <O extends SCMHeadObserver> O fetch(@NonNull O observer, @CheckForNull TaskListener listener) throws IOException, InterruptedException
O
- Observer type.observer
- an optional observer of interim results.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final <O extends SCMHeadObserver> O fetch(@CheckForNull SCMSourceCriteria criteria, @NonNull O observer, @CheckForNull TaskListener listener) throws IOException, InterruptedException
O
- Observer type.criteria
- the criteria to use.observer
- an optional observer of interim results.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final <O extends SCMHeadObserver> O fetch(@CheckForNull SCMSourceCriteria criteria, @NonNull O observer, @CheckForNull SCMHeadEvent<?> event, @CheckForNull TaskListener listener) throws IOException, InterruptedException
O
- Observer type.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 listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final <O extends SCMHeadObserver> O fetch(@NonNull O observer, @CheckForNull SCMHeadEvent<?> event, @CheckForNull TaskListener listener) throws IOException, InterruptedException
O
- Observer type.observer
- an observer of interim results.event
- the (optional) event from which the fetch should be scoped.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@Deprecated protected void retrieve(@NonNull SCMHeadObserver observer, @NonNull TaskListener listener) throws IOException, InterruptedException
retrieve(SCMSourceCriteria, SCMHeadObserver, SCMHeadEvent, TaskListener)
observer
- an optional observer of interim results.listener
- the task listener.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@Deprecated protected void retrieve(@CheckForNull SCMSourceCriteria criteria, @NonNull SCMHeadObserver observer, @NonNull TaskListener listener) throws IOException, InterruptedException
retrieve(SCMSourceCriteria, SCMHeadObserver, SCMHeadEvent, TaskListener)
checkInterrupt()
otherwise it will be impossible for users to interrupt the operation.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.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.protected abstract void retrieve(@CheckForNull SCMSourceCriteria criteria, @NonNull SCMHeadObserver observer, @CheckForNull SCMHeadEvent<?> event, @NonNull TaskListener listener) throws IOException, InterruptedException
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)
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.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final Set<SCMHead> fetch(@CheckForNull TaskListener listener) throws IOException, InterruptedException
listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public Set<SCMRevision> parentRevisions(@NonNull SCMHead head, @NonNull SCMRevision revision, @CheckForNull TaskListener listener) throws IOException, InterruptedException
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.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public Map<SCMHead,SCMRevision> parentHeads(@NonNull SCMHead head, @CheckForNull TaskListener listener) throws IOException, InterruptedException
head
- the head to look up the parent head(s) within.listener
- the task listener.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected Set<SCMHead> retrieve(@NonNull TaskListener listener) throws IOException, InterruptedException
listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected Set<SCMHead> retrieve(@CheckForNull SCMSourceCriteria criteria, @NonNull TaskListener listener) throws IOException, InterruptedException
criteria
- the criteria to use for identifying heads.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@CheckForNull public final SCMRevision fetch(@NonNull SCMHead head, @CheckForNull TaskListener listener) throws IOException, InterruptedException
SCMSourceCriteria
.head
- the head.listener
- the task listenernull
if the head no longer exists.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@CheckForNull protected SCMRevision retrieve(@NonNull SCMHead head, @NonNull TaskListener listener) throws IOException, InterruptedException
SCMSourceCriteria
.head
- the head.listener
- the task listenernull
if the head no longer exists.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@Deprecated @CheckForNull public final SCMRevision fetch(@NonNull String thingName, @CheckForNull TaskListener listener) throws IOException, InterruptedException
fetch(String, TaskListener, Item)
retrieve(String, TaskListener)
.thingName
- might be a branch name, a tag name, a cryptographic hash, a change request number, etc.listener
- the task listener (optional)SCMRevision
corresponding to the argument, with a usable corresponding head, or
null
if malformed or not foundIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@CheckForNull public final SCMRevision fetch(@NonNull String thingName, @CheckForNull TaskListener listener, @CheckForNull Item context) throws IOException, InterruptedException
retrieve(String, TaskListener)
.thingName
- might be a branch name, a tag name, a cryptographic hash, a change request number, etc.listener
- the task listener (optional)context
- an associated context to supersede getOwner()
, such as a job in which this is runningSCMRevision
corresponding to the argument, with a usable corresponding head, or
null
if malformed or not foundIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@Deprecated @CheckForNull protected SCMRevision retrieve(@NonNull String thingName, @NonNull TaskListener listener) throws IOException, InterruptedException
retrieve(String, TaskListener, Item)
retrieve(SCMSourceCriteria, SCMHeadObserver, TaskListener)
and looks for SCMHead.getName()
matching the argument (so typically only supporting branch names).thingName
- might be a branch name, a tag name, a cryptographic hash, a revision number, etc.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@CheckForNull protected SCMRevision retrieve(@NonNull String thingName, @NonNull TaskListener listener, @CheckForNull Item context) throws IOException, InterruptedException
retrieve(SCMSourceCriteria, SCMHeadObserver, TaskListener)
and looks for SCMHead.getName()
matching the argument (so typically only supporting branch names).thingName
- might be a branch name, a tag name, a cryptographic hash, a revision number, etc.listener
- the task listenercontext
- an associated context to supersede getOwner()
, such as a job in which this is runningIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@Deprecated @NonNull public final Set<String> fetchRevisions(@CheckForNull TaskListener listener) throws IOException, InterruptedException
fetchRevisions(TaskListener, Item)
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)
.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final Set<String> fetchRevisions(@CheckForNull TaskListener listener, @CheckForNull Item context) throws IOException, InterruptedException
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)
.listener
- the task listenercontext
- an associated context to supersede getOwner()
, such as a job in which this is runningIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@Deprecated @NonNull protected Set<String> retrieveRevisions(@NonNull TaskListener listener) throws IOException, InterruptedException
retrieveRevisions(TaskListener, Item)
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.listener
- the task listenerIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected Set<String> retrieveRevisions(@NonNull TaskListener listener, @CheckForNull Item context) throws IOException, InterruptedException
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.listener
- the task listenercontext
- an associated context to supersede getOwner()
, such as a job in which this is runningIOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final List<Action> fetchActions(@NonNull SCMRevision revision, @CheckForNull SCMHeadEvent event, @CheckForNull TaskListener listener) throws IOException, InterruptedException
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. 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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final List<Action> fetchActions(@NonNull SCMHead head, @CheckForNull SCMHeadEvent event, @CheckForNull TaskListener listener) throws IOException, InterruptedException
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)
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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public final List<Action> fetchActions(@CheckForNull SCMSourceEvent event, @CheckForNull TaskListener listener) throws IOException, InterruptedException
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)
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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected List<Action> retrieveActions(@NonNull SCMRevision revision, @CheckForNull SCMHeadEvent event, @NonNull TaskListener listener) throws IOException, InterruptedException
fetchActions(SCMRevision, SCMHeadEvent, TaskListener)
. Fetches any actions that should be persisted for
objects related to the specified revision.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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected List<Action> retrieveActions(@NonNull SCMHead head, @CheckForNull SCMHeadEvent event, @NonNull TaskListener listener) throws IOException, InterruptedException
fetchActions(SCMHead, SCMHeadEvent, TaskListener)
. Fetches any actions that should be persisted for objects
related to the specified head.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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected List<Action> retrieveActions(@CheckForNull SCMSourceEvent event, @NonNull TaskListener listener) throws IOException, InterruptedException
fetchActions(SCMSourceEvent,TaskListener)
. Fetches any actions that should be persisted for
objects related to the specified source.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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull public abstract SCM build(@NonNull SCMHead head, @CheckForNull SCMRevision revision)
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.head
- the head.revision
- the revision or null
.SCM
instance.@NonNull public final SCM build(@NonNull SCMHead head)
SCM
instance for the specified head.head
- the head.SCM
instance@NonNull public SCMRevision getTrustedRevision(@NonNull SCMRevision revision, @NonNull TaskListener listener) throws IOException, InterruptedException
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.
revision
- a revision (produced by one of the retrieve
overloads)
which may or may not come from a trustworthy sourcelistener
- a way to explain possible substitutionsrevision
;
may be overridden to provide an alternate revision from the same or a different headIOException
- in case the implementation must call fetch(SCMHead, TaskListener)
or similarInterruptedException
- in case the implementation must call fetch(SCMHead, TaskListener)
or similar@NonNull protected final TaskListener defaultListener(@CheckForNull TaskListener listener)
null
TaskListener
reference into a guaranteed non-null reference.listener
- a possibly null
TaskListener
reference.TaskListener
.public boolean canProbe()
SCMSource
can instantiate a SCMSourceCriteria.Probe
true
if and only if createProbe(SCMHead, SCMRevision)
has been implemented.@NonNull public final SCMProbe newProbe(@NonNull SCMHead head, @CheckForNull SCMRevision revision) throws IOException
SCMProbe
for the specified SCMHead
and SCMRevision
.
Public exposed API for createProbe(SCMHead, SCMRevision)
.head
- the SCMHead
.revision
- the SCMRevision
.SCMSourceCriteria.Probe
.IllegalArgumentException
- if the SCMRevision.getHead()
is not equal to the supplied SCMHead
IOException
- if the probe creation failed due to an IO exception.canProbe()
@NonNull protected SCMProbe createProbe(@NonNull SCMHead head, @CheckForNull SCMRevision revision) throws IOException
head
- the SCMHead
.revision
- the SCMRevision
.SCMSourceCriteria.Probe
.IOException
- if the probe creation failed due to an IO exception.canProbe()
,
newProbe(SCMHead, SCMRevision)
,
fromSCMFileSystem(SCMHead, SCMRevision)
@CheckForNull protected final SCMProbe fromSCMFileSystem(@NonNull SCMHead head, @CheckForNull SCMRevision revision) throws IOException, InterruptedException
SCMFileSystem.Builder
and want to use a simple
non-caching SCMProbe
based off of the SCMFileSystem
.head
- the SCMHead
.revision
- the SCMRevision
.SCMSourceCriteria.Probe
or null
if this source cannot be probed.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.public SCMSourceDescriptor getDescriptor()
getDescriptor
in interface Describable<SCMSource>
getDescriptor
in class AbstractDescribableImpl<SCMSource>
@CheckForNull public String getPronoun()
SCMSource
. Must start with a capital letter.null
to fall back to the calling context's default.@NonNull public final Set<? extends SCMHeadCategory> getCategories()
SCMHeadCategory
that this SCMSource
supports. There will always be
exactly one SCMCategory.isUncategorized()
instance in the returned set.SCMHeadCategory
that this SCMSource
supports.protected boolean isCategoryEnabled(@NonNull SCMHeadCategory category)
category
- the category.true
if the supplied category is enabled for this SCMSource
instance.protected final void checkInterrupt() throws InterruptedException
Thread.interrupted()
and throws an InterruptedException
if it was set.InterruptedException
- if interrupted.public void afterSave()
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.Copyright © 2016–2022. All rights reserved.