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()
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

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