jenkins.scm.api

Class SCMSource

java.lang.Object

hudson.model.AbstractDescribableImpl<SCMSource>

jenkins.scm.api.SCMSource

All Implemented Interfaces:

hudson.ExtensionPoint, hudson.model.Describable<SCMSource>

Direct Known Subclasses:

NullSCMSource, SingleSCMSource

public abstract class SCMSource
extends hudson.model.AbstractDescribableImpl<SCMSource>
implements hudson.ExtensionPoint

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

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

hudson.ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
hudson.scm.SCM	build(SCMHead head) Builds a SCM instance for the specified head.
abstract hudson.scm.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.
protected hudson.model.TaskListener	defaultListener(hudson.model.TaskListener listener) Turns a possibly null TaskListener reference into a guaranteed non-null reference.
boolean	equals(Object o)
<O extends SCMHeadObserver> O	fetch(O observer, hudson.model.TaskListener listener) Fetches the latest heads and corresponding revisions.
SCMRevision	fetch(SCMHead head, hudson.model.TaskListener listener) Gets the current head revision of the specified head.
Set<SCMHead>	fetch(hudson.model.TaskListener listener) Fetches the current list of heads.
protected SCMSourceCriteria	getCriteria() Returns the branch criteria.
String	getId() The ID of this source.
SCMSourceOwner	getOwner() Gets the owner.
int	hashCode()
Map<SCMHead,SCMRevision>	parentHeads(SCMHead head, hudson.model.TaskListener listener) Looks up the immediate parent heads of the specified head within the specified source.
Set<SCMRevision>	parentRevisions(SCMHead head, SCMRevision revision, hudson.model.TaskListener listener) Looks up the immediate parent revision(s) of the specified revision within the specified head.
protected abstract void	retrieve(SCMHeadObserver observer, hudson.model.TaskListener listener) Fetches the latest heads and corresponding revisions.
protected SCMRevision	retrieve(SCMHead head, hudson.model.TaskListener listener) Gets the current head revision of the specified head.
protected Set<SCMHead>	retrieve(hudson.model.TaskListener listener) Fetches the current list of heads.
void	setOwner(SCMSourceOwner owner) Sets the owner.
String	toString()

Methods inherited from class hudson.model.AbstractDescribableImpl

getDescriptor

Methods inherited from class java.lang.Object

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

Constructor Detail

SCMSource

protected SCMSource(@CheckForNull
         String id)

Constructor.

Parameters:

id - the id or null.

Method Detail

getId

@NonNull
public final String getId()

The ID of this source. The ID is not related to anything at all.

Returns:

the ID of this source.

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
                                          hudson.model.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.

Parameters:

observer - an optional observer of interim results.

listener - the task listener

Returns:

the provided observer.

Throws:

IOException

InterruptedException

retrieve

@NonNull
protected abstract void retrieve(@NonNull
                    SCMHeadObserver observer,
                    @NonNull
                    hudson.model.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.

Parameters:

observer - an optional observer of interim results.

listener - the task listener.

Throws:

IOException

InterruptedException

fetch

@NonNull
public final Set<SCMHead> fetch(@CheckForNull
                         hudson.model.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

InterruptedException

parentRevisions

@NonNull
public Set<SCMRevision> parentRevisions(@NonNull
                                       SCMHead head,
                                       @NonNull
                                       SCMRevision revision,
                                       @CheckForNull
                                       hudson.model.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

InterruptedException

Since:

0.3

parentHeads

@NonNull
public Map<SCMHead,SCMRevision> parentHeads(@NonNull
                                           SCMHead head,
                                           @CheckForNull
                                           hudson.model.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

InterruptedException

Since:

0.3

retrieve

@NonNull
protected Set<SCMHead> retrieve(@NonNull
                            hudson.model.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

InterruptedException

fetch

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

Gets the current head revision of the specified head.

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

InterruptedException

retrieve

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

Gets the current head revision of the specified head.

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

InterruptedException

build

@NonNull
public abstract hudson.scm.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 hudson.scm.SCM build(@NonNull
                           SCMHead head)

Builds a SCM instance for the specified head.

Parameters:

head - the head.

Returns:

the SCM instance

defaultListener

@NonNull
protected final hudson.model.TaskListener defaultListener(@CheckForNull
                                                hudson.model.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.

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