Package 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.

  • Field Details

  • Constructor Details

    • SCMSource

      @Deprecated protected SCMSource(@CheckForNull String id)
      Deprecated.
      Constructor.
      Parameters:
      id - the id or null.

    • SCMSource

      protected SCMSource()
      Constructor.

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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

      @Deprecated @CheckForNull public final SCMRevision fetch(@NonNull String thingName, @CheckForNull TaskListener listener) throws IOException, InterruptedException
      Deprecated.
      rather call fetch(String, TaskListener, Item)
      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

    • fetch

      @CheckForNull public final SCMRevision fetch(@NonNull String thingName, @CheckForNull TaskListener listener, @CheckForNull Item context) 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)
      context - an associated context to supersede getOwner(), such as a job in which this is running
      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:
      2.6.0

    • retrieve

      @Deprecated @CheckForNull protected SCMRevision retrieve(@NonNull String thingName, @NonNull TaskListener listener) throws IOException, InterruptedException
      Deprecated.
      rather override retrieve(String, TaskListener, Item)
      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

    • retrieve

      @CheckForNull protected SCMRevision retrieve(@NonNull String thingName, @NonNull TaskListener listener, @CheckForNull Item context) 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
      context - an associated context to supersede getOwner(), such as a job in which this is running
      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:
      2.6.0

    • fetchRevisions

      @Deprecated @NonNull public final Set<String> fetchRevisions(@CheckForNull TaskListener listener) throws IOException, InterruptedException
      Deprecated.
      rather call fetchRevisions(TaskListener, Item)
      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

    • fetchRevisions

      @NonNull public final Set<String> fetchRevisions(@CheckForNull TaskListener listener, @CheckForNull Item context) 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
      context - an associated context to supersede getOwner(), such as a job in which this is running
      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:
      2.6.0

    • retrieveRevisions

      @Deprecated @NonNull protected Set<String> retrieveRevisions(@NonNull TaskListener listener) throws IOException, InterruptedException
      Deprecated.
      rather override retrieveRevisions(TaskListener, Item)
      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

    • retrieveRevisions

      @NonNull protected Set<String> retrieveRevisions(@NonNull TaskListener listener, @CheckForNull Item context) 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
      context - an associated context to supersede getOwner(), such as a job in which this is running
      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:
      2.6.0

    • 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:

    • 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:

    • 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