Package jenkins.scm.api

Class SCMSource

    • 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

      • 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,
                               @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

        @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

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

      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class Object

      • 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

      • 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

      • 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