jenkins.scm.api

Class SCMFileSystem

java.lang.Object

jenkins.scm.api.SCMFileSystem

All Implemented Interfaces:

Closeable, AutoCloseable

public abstract class SCMFileSystem
extends Object
implements Closeable

A virtual file system for a specific SCM potentially pinned to a specific SCMRevision. In contrast to SCMProbe, implementations should not cache results between SCMFileSystem instantiations.

While some DVCS implementations may need to perform a local checkout in order to be able to implement this API it should be noted that in such cases the local checkout is not a cache but rather a copy of the immutable revisions - this may look and sound like a cache but it isn't as the revision itself is immutable. When a new SCMFileSystem if being instantiated against a null SCMRevision the DVCS system can re-use the previous local checkout after reconfirming that the current revision for the head matches that of the local checkout.

Where the getRevision() is null or SCMRevision.isDeterministic() a SCMFileSystem can choose to keep the results locally (up to close()) or re-query against the remote.

Author:

Stephen Connolly

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SCMFileSystem.Builder Extension point that allows different plugins to implement SCMFileSystem classes for the same SCM or SCMSource and let Jenkins pick the most capable for any specific SCM implementation.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SCMFileSystem(SCMRevision rev) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	changesSince(SCMRevision revision, OutputStream changeLogStream) Writes the changes between the specified revision and getRevision() in the format compatible with the SCM from this of(Item, SCM) to the supplied OutputStream.
SCMFile	child(String path) Short for getRoot().child(path).
void	close()
SCMRevision	getRevision() If this inspector is looking at the specific commit, returns that revision.
abstract SCMFile	getRoot() Returns the SCMFile object that represents the root directory of the repository.
boolean	isFixedRevision() Whether this inspector is looking at the specific commit.
abstract long	lastModified() Returns the time that the SCMFileSystem was last modified.
static SCMFileSystem	of(Item owner, SCM scm) Given a SCM this method will try to retrieve a corresponding SCMFileSystem instance.
static SCMFileSystem	of(Item owner, SCM scm, SCMRevision rev) Given a SCM this method will try to retrieve a corresponding SCMFileSystem instance that reflects the content at the specified SCMRevision.
static SCMFileSystem	of(SCMSource source, SCMHead head) Given a SCMSource and a SCMHead this method will try to retrieve a corresponding SCMFileSystem instance that reflects the content of the specified SCMHead.
static SCMFileSystem	of(SCMSource source, SCMHead head, SCMRevision rev) Given a SCMSource, a SCMHead and a SCMRevision this method will try to retrieve a corresponding SCMFileSystem instance that reflects the content of the specified SCMHead at the specified SCMRevision.
static boolean	supports(SCM scm) Given a SCM this method will check if there is at least one SCMFileSystem provider capable of being instantiated.
static boolean	supports(SCMDescriptor descriptor) Given a SCMDescriptor this method will check if there is at least one SCMFileSystem provider capable of being instantiated from the descriptor's SCMSource.
static boolean	supports(SCMSource source) Given a SCMSource this method will check if there is at least one SCMFileSystem provider capable of being instantiated.
static boolean	supports(SCMSourceDescriptor descriptor) Given a SCMSourceDescriptor this method will check if there is at least one SCMFileSystem provider capable of being instantiated from the descriptor's SCMSource.

Methods inherited from class java.lang.Object

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

Constructor Detail

SCMFileSystem

protected SCMFileSystem(@CheckForNull
                        SCMRevision rev)

Constructor.

Parameters:

rev - the revision.

Method Detail

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

lastModified

public abstract long lastModified()
                           throws IOException,
                                  InterruptedException

Returns the time that the SCMFileSystem was last modified. This should logically be equivalent to the maximum SCMFile.lastModified() that you would find if you were to do the horribly inefficient traversal of all the SCMFile instances from getRoot(). Where implementers do not have an easy and quick way to get this information (such as by looking at the commit time of the getRevision() HINT HINT) then just return 0L.

Returns:

A long value representing the time the SCMFileSystem was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970) or 0L if the operation is unsupported.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

getRevision

@CheckForNull
public SCMRevision getRevision()

If this inspector is looking at the specific commit, returns that revision. Otherwise null, indicating that the inspector is looking at just the latest state of the repository.

Returns:

the revision of the commit the inspector is looking at, or null if none.

isFixedRevision

public final boolean isFixedRevision()

Whether this inspector is looking at the specific commit.

Short for getRevision()!=null.

.

Returns:

true if this inspector is looking at the specific commit.

child

@NonNull
public final SCMFile child(@NonNull
                                    String path)

Short for getRoot().child(path).

Parameters:

path - Path of the SCMFile to obtain from the root of the repository.

Returns:

null if there's no file/directory at the requested path.

getRoot

@NonNull
public abstract SCMFile getRoot()

Returns the SCMFile object that represents the root directory of the repository.

Returns:

the root directory of the repository.

changesSince

public boolean changesSince(@CheckForNull
                            SCMRevision revision,
                            @NonNull
                            OutputStream changeLogStream)
                     throws UnsupportedOperationException,
                            IOException,
                            InterruptedException

Writes the changes between the specified revision and getRevision() in the format compatible with the SCM from this of(Item, SCM) to the supplied OutputStream. This method allows for consumers or the SCM API to replicate the SCM.checkout(Run, Launcher, FilePath, TaskListener, File, SCMRevisionState) functionality that captures the changelog without requiring a full checkout.

Parameters:

revision - the starting revision or null to capture the initial change set.

changeLogStream - the destination to stream the changes to.

Returns:

true if there are changes, false if there were no changes.

Throws:

UnsupportedOperationException - if this SCMFileSystem does not support changelog querying.

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

Since:

2.0

of

@CheckForNull
public static SCMFileSystem of(@NonNull
                                             Item owner,
                                             @NonNull
                                             SCM scm)
                                      throws IOException,
                                             InterruptedException

Given a SCM this method will try to retrieve a corresponding SCMFileSystem instance.

Parameters:

owner - the owner of the SCM

scm - the SCM.

Returns:

the corresponding SCMFileSystem or null if there is none.

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.

of

@CheckForNull
public static SCMFileSystem of(@NonNull
                                             Item owner,
                                             @NonNull
                                             SCM scm,
                                             @CheckForNull
                                             SCMRevision rev)
                                      throws IOException,
                                             InterruptedException

Given a SCM this method will try to retrieve a corresponding SCMFileSystem instance that reflects the content at the specified SCMRevision.

Parameters:

owner - the owner of the SCM

scm - the SCM.

rev - the specified SCMRevision.

Returns:

the corresponding SCMFileSystem or null if there is none.

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.

supports

public static boolean supports(@NonNull
                               SCM scm)

Given a SCM this method will check if there is at least one SCMFileSystem provider capable of being instantiated. Returning true does not mean that of(Item, SCM, SCMRevision) will be able to instantiate a SCMFileSystem for any specific SCMRevision, rather returning false indicates that there is absolutely no point in calling of(Item, SCM, SCMRevision) as it will always return null.

Parameters:

scm - the SCMSource.

Returns:

true if of(Item, SCM) / of(Item, SCM, SCMRevision) could return a SCMFileSystem implementation, false if of(Item, SCM) / of(Item, SCM, SCMRevision) will always return null for the supplied SCM.

Since:

2.0

of

@CheckForNull
public static SCMFileSystem of(@NonNull
                                             SCMSource source,
                                             @NonNull
                                             SCMHead head)
                                      throws IOException,
                                             InterruptedException

Given a SCMSource and a SCMHead this method will try to retrieve a corresponding SCMFileSystem instance that reflects the content of the specified SCMHead.

Parameters:

source - the SCMSource.

head - the specified SCMHead.

Returns:

the corresponding SCMFileSystem or null if there is none.

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.

of

@CheckForNull
public static SCMFileSystem of(@NonNull
                                             SCMSource source,
                                             @NonNull
                                             SCMHead head,
                                             @CheckForNull
                                             SCMRevision rev)
                                      throws IOException,
                                             InterruptedException

Given a SCMSource, a SCMHead and a SCMRevision this method will try to retrieve a corresponding SCMFileSystem instance that reflects the content of the specified SCMHead at the specified SCMRevision.

Parameters:

source - the SCMSource.

head - the specified SCMHead.

rev - the specified SCMRevision.

Returns:

the corresponding SCMFileSystem or null if there is none.

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.

supports

public static boolean supports(@NonNull
                               SCMSource source)

Given a SCMSource this method will check if there is at least one SCMFileSystem provider capable of being instantiated. Returning true does not mean that of(SCMSource, SCMHead, SCMRevision) will be able to instantiate a SCMFileSystem for any specific SCMHead or SCMRevision, rather returning false indicates that there is absolutely no point in calling of(SCMSource, SCMHead, SCMRevision) as it will always return null.

Parameters:

source - the SCMSource.

Returns:

true if of(SCMSource, SCMHead) / of(SCMSource, SCMHead, SCMRevision) could return a SCMFileSystem implementation, false if of(SCMSource, SCMHead) / of(SCMSource, SCMHead, SCMRevision) will always return null for the supplied SCMSource.

Since:

2.0

supports

public static boolean supports(@NonNull
                               SCMDescriptor descriptor)

Given a SCMDescriptor this method will check if there is at least one SCMFileSystem provider capable of being instantiated from the descriptor's SCMSource. Returning true does not mean that of(Item, SCM, SCMRevision) will be able to instantiate a SCMFileSystem for any specific Item or SCMRevision, rather returning false indicates that there is absolutely no point in calling of(Item, SCM, SCMRevision) as it will always return null.

Parameters:

descriptor - the SCMDescriptor.

Returns:

true if of(Item, SCM, SCMRevision) could return a SCMFileSystem implementation, false if of(Item, SCM, SCMRevision) will always return null for the supplied SCM.

Since:

2.3.0

supports

public static boolean supports(@NonNull
                               SCMSourceDescriptor descriptor)

Given a SCMSourceDescriptor this method will check if there is at least one SCMFileSystem provider capable of being instantiated from the descriptor's SCMSource. Returning true does not mean that of(SCMSource, SCMHead, SCMRevision) will be able to instantiate a SCMFileSystem for any specific SCMHead or SCMRevision, rather returning false indicates that there is absolutely no point in calling of(SCMSource, SCMHead, SCMRevision) as it will always return null.

Parameters:

descriptor - the SCMSourceDescriptor.

Returns:

true if of(SCMSource, SCMHead) / of(SCMSource, SCMHead, SCMRevision) could return a SCMFileSystem implementation, false if of(SCMSource, SCMHead) / of(SCMSource, SCMHead, SCMRevision) will always return null for the supplied SCMSource.

Since:

2.3.0