Package jenkins.plugins.git

Class GitSCMTelescope

java.lang.Object

jenkins.scm.api.SCMFileSystem.Builder

jenkins.plugins.git.GitSCMTelescope

All Implemented Interfaces:

ExtensionPoint

public abstract class GitSCMTelescope
extends jenkins.scm.api.SCMFileSystem.Builder

An implementation of this extension point allows AbstractGitSCMSource to examine a repository from a distance without requiring a local checkout.

Since:

3.6.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GitSCMTelescope.ReferenceType	The potential types of reference supported by a GitSCMTelescope.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
GitSCMTelescope()

Method Summary

Modifier and Type	Method	Description
jenkins.scm.api.SCMFileSystem	build(Item owner, SCM scm, jenkins.scm.api.SCMRevision rev)
protected abstract jenkins.scm.api.SCMFileSystem	build(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials, jenkins.scm.api.SCMHead head, jenkins.scm.api.SCMRevision rev)	Given a SCM this should try to build a corresponding SCMFileSystem instance that reflects the content at the specified SCMRevision.
jenkins.scm.api.SCMFileSystem	build(jenkins.scm.api.SCMSource source, jenkins.scm.api.SCMHead head, jenkins.scm.api.SCMRevision rev)
abstract String	getDefaultTarget(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials)	Retrieves the default target of the specified repository.
abstract jenkins.scm.api.SCMRevision	getRevision(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials, String refOrHash)	Retrieves the current revision of the specified reference or object hash.
jenkins.scm.api.SCMRevision	getRevision(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials, jenkins.scm.api.SCMHead head)	Retrieves the current revision of the specified head.
Iterable<jenkins.scm.api.SCMRevision>	getRevisions(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials)	Retrieves the current revisions of the specified repository.
abstract Iterable<jenkins.scm.api.SCMRevision>	getRevisions(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials, Set<GitSCMTelescope.ReferenceType> referenceTypes)	Retrieves the current revisions of the specified repository.
abstract long	getTimestamp(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials, String refOrHash)	Retrieves the timestamp of the specified reference or object hash.
long	getTimestamp(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials, jenkins.scm.api.SCMHead head)	Retrieves the timestamp of the specified reference or object hash.
static GitSCMTelescope	of(GitSCM source)	Returns the GitSCMTelescope to use for the specified GitSCM or null if none match.
static GitSCMTelescope	of(AbstractGitSCMSource source)	Returns the GitSCMTelescope to use for the specified AbstractGitSCMSource or null if none match.
boolean	supports(SCM source)
abstract boolean	supports(String remote)	Checks if this SCMFileSystem.Builder supports the repository at the supplied remote URL.
boolean	supports(jenkins.scm.api.SCMSource source)
abstract void	validate(String remote, com.cloudbees.plugins.credentials.common.StandardCredentials credentials)	Checks if the supplied credentials are valid against the specified repository URL.

Methods inherited from class jenkins.scm.api.SCMFileSystem.Builder

build, supports, supports, supportsDescriptor, supportsDescriptor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GitSCMTelescope

public GitSCMTelescope()

Method Detail

of

@CheckForNull
public static GitSCMTelescope of(@NonNull
                                 GitSCM source)

Returns the GitSCMTelescope to use for the specified GitSCM or null if none match.

Parameters:

source - the GitSCM.

Returns:

the GitSCMTelescope to use for the specified GitSCM or null

of

@CheckForNull
public static GitSCMTelescope of(@NonNull
                                 AbstractGitSCMSource source)

Returns the GitSCMTelescope to use for the specified AbstractGitSCMSource or null if none match.

Parameters:

source - the AbstractGitSCMSource.

Returns:

the GitSCMTelescope to use for the specified AbstractGitSCMSource or null

supports

public abstract boolean supports(@NonNull
                                 String remote)

Checks if this SCMFileSystem.Builder supports the repository at the supplied remote URL. NOTE: returning true mandates that build(Item, SCM, SCMRevision) and build(SCMSource, SCMHead, SCMRevision) must return non-null when they are configured with the corresponding repository URL.

Parameters:

remote - the repository URL.

Returns:

true if and only if the remote URL is supported by this GitSCMTelescope.

validate

public abstract void validate(@NonNull
                              String remote,
                              @CheckForNull
                              com.cloudbees.plugins.credentials.common.StandardCredentials credentials)
                       throws IOException,
                              InterruptedException

Checks if the supplied credentials are valid against the specified repository URL.

Parameters:

remote - the repository URL.

credentials - the credentials or null to validate anonymous connection.

Throws:

IOException - if the operation failed due to an IO error or invalid credentials.

InterruptedException - if the operation was interrupted.

supports

public final boolean supports(@NonNull
                              SCM source)

Specified by:

supports in class jenkins.scm.api.SCMFileSystem.Builder

supports

public final boolean supports(@NonNull
                              jenkins.scm.api.SCMSource source)

Specified by:

supports in class jenkins.scm.api.SCMFileSystem.Builder

build

public final jenkins.scm.api.SCMFileSystem build(@NonNull
                                                 jenkins.scm.api.SCMSource source,
                                                 @NonNull
                                                 jenkins.scm.api.SCMHead head,
                                                 @CheckForNull
                                                 jenkins.scm.api.SCMRevision rev)
                                          throws IOException,
                                                 InterruptedException

Overrides:

build in class jenkins.scm.api.SCMFileSystem.Builder

Throws:

IOException

InterruptedException

build

public final jenkins.scm.api.SCMFileSystem build(@NonNull
                                                 Item owner,
                                                 @NonNull
                                                 SCM scm,
                                                 jenkins.scm.api.SCMRevision rev)
                                          throws IOException,
                                                 InterruptedException

Overrides:

build in class jenkins.scm.api.SCMFileSystem.Builder

Throws:

IOException

InterruptedException

build

@CheckForNull
protected abstract jenkins.scm.api.SCMFileSystem build(@NonNull
                                                       String remote,
                                                       @CheckForNull
                                                       com.cloudbees.plugins.credentials.common.StandardCredentials credentials,
                                                       @NonNull
                                                       jenkins.scm.api.SCMHead head,
                                                       @CheckForNull
                                                       jenkins.scm.api.SCMRevision rev)
                                                throws IOException,
                                                       InterruptedException

Given a SCM this should try to build a corresponding SCMFileSystem instance that reflects the content at the specified SCMRevision. If the SCM is supported but not for a fixed revision, best effort is acceptable as the most capable SCMFileSystem will be returned to the caller.

Parameters:

remote - the repository URL

credentials - the credentials or null for an anonymous connection.

head - the specified SCMHead

rev - the specified SCMRevision.

Returns:

the corresponding SCMFileSystem or null if this builder cannot create a SCMFileSystem for the specified repository URL.

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.

getTimestamp

public abstract long getTimestamp(@NonNull
                                  String remote,
                                  @CheckForNull
                                  com.cloudbees.plugins.credentials.common.StandardCredentials credentials,
                                  @NonNull
                                  String refOrHash)
                           throws IOException,
                                  InterruptedException

Retrieves the timestamp of the specified reference or object hash.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

refOrHash - the reference or hash. If this is a reference then it will start with Constants.R_REFS If this is a hash, it may be a full hash or a short hash.

Returns:

the timestamp.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.

getRevision

@CheckForNull
public abstract jenkins.scm.api.SCMRevision getRevision(@NonNull
                                                        String remote,
                                                        @CheckForNull
                                                        com.cloudbees.plugins.credentials.common.StandardCredentials credentials,
                                                        @NonNull
                                                        String refOrHash)
                                                 throws IOException,
                                                        InterruptedException

Retrieves the current revision of the specified reference or object hash.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

refOrHash - the reference or hash. If this is a reference then it will start with Constants.R_REFS If this is a hash, it may be a full hash or a short hash.

Returns:

the revision or null if the reference or hash does not exist.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.

getTimestamp

public long getTimestamp(@NonNull
                         String remote,
                         @CheckForNull
                         com.cloudbees.plugins.credentials.common.StandardCredentials credentials,
                         @NonNull
                         jenkins.scm.api.SCMHead head)
                  throws IOException,
                         InterruptedException

Retrieves the timestamp of the specified reference or object hash.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

head - the head.

Returns:

the timestamp.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.

getRevision

@CheckForNull
public jenkins.scm.api.SCMRevision getRevision(@NonNull
                                               String remote,
                                               @CheckForNull
                                               com.cloudbees.plugins.credentials.common.StandardCredentials credentials,
                                               @NonNull
                                               jenkins.scm.api.SCMHead head)
                                        throws IOException,
                                               InterruptedException

Retrieves the current revision of the specified head.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

head - the head.

Returns:

the revision or null if the head does not exist.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.

getRevisions

public final Iterable<jenkins.scm.api.SCMRevision> getRevisions(@NonNull
                                                                String remote,
                                                                @CheckForNull
                                                                com.cloudbees.plugins.credentials.common.StandardCredentials credentials)
                                                         throws IOException,
                                                                InterruptedException

Retrieves the current revisions of the specified repository.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

Returns:

the revisions.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.

getRevisions

public abstract Iterable<jenkins.scm.api.SCMRevision> getRevisions(@NonNull
                                                                   String remote,
                                                                   @CheckForNull
                                                                   com.cloudbees.plugins.credentials.common.StandardCredentials credentials,
                                                                   @NonNull
                                                                   Set<GitSCMTelescope.ReferenceType> referenceTypes)
                                                            throws IOException,
                                                                   InterruptedException

Retrieves the current revisions of the specified repository.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

referenceTypes - the types of reference to retrieve revisions of.

Returns:

the revisions.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.

getDefaultTarget

public abstract String getDefaultTarget(@NonNull
                                        String remote,
                                        @CheckForNull
                                        com.cloudbees.plugins.credentials.common.StandardCredentials credentials)
                                 throws IOException,
                                        InterruptedException

Retrieves the default target of the specified repository.

Parameters:

remote - the repository URL.

credentials - the credentials or null for an anonymous connection.

Returns:

the default target of the repository.

Throws:

IOException - if the operation failed due to an IO error.

InterruptedException - if the operation was interrupted.