Package 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 specificSCM
potentially pinned to a specificSCMRevision
. In contrast toSCMProbe
, implementations should not cache results betweenSCMFileSystem
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 anull
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()
isnull
orSCMRevision.isDeterministic()
aSCMFileSystem
can choose to keep the results locally (up toclose()
) or re-query against the remote.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SCMFileSystem.Builder
Extension point that allows different plugins to implementSCMFileSystem
classes for the sameSCM
orSCMSource
and let Jenkins pick the most capable for any specificSCM
implementation.
-
Constructor Summary
Constructors Modifier Constructor Description protected
SCMFileSystem(SCMRevision rev)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description boolean
changesSince(SCMRevision revision, OutputStream changeLogStream)
Writes the changes between the specified revision andgetRevision()
in the format compatible with theSCM
from thisof(Item, SCM)
to the suppliedOutputStream
.SCMFile
child(String path)
Short forgetRoot().child(path)
.void
close()
SCMRevision
getRevision()
If this inspector is looking at the specific commit, returns that revision.abstract SCMFile
getRoot()
Returns theSCMFile
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 theSCMFileSystem
was last modified.static SCMFileSystem
of(Item owner, SCM scm)
Given aSCM
this method will try to retrieve a correspondingSCMFileSystem
instance.static SCMFileSystem
of(Item owner, SCM scm, SCMRevision rev)
Given aSCM
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content at the specifiedSCMRevision
.static SCMFileSystem
of(Item owner, SCM scm, SCMRevision rev, Run<?,?> build)
Given aSCM
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content at the specifiedSCMRevision
.static SCMFileSystem
of(SCMSource source, SCMHead head)
Given aSCMSource
and aSCMHead
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content of the specifiedSCMHead
.static SCMFileSystem
of(SCMSource source, SCMHead head, SCMRevision rev)
Given aSCMSource
, aSCMHead
and aSCMRevision
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content of the specifiedSCMHead
at the specifiedSCMRevision
.static boolean
supports(SCM scm)
Given aSCM
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated.static boolean
supports(SCMDescriptor descriptor)
Given aSCMDescriptor
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated from the descriptor'sSCMSource
.static boolean
supports(SCMSource source)
Given aSCMSource
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated.static boolean
supports(SCMSourceDescriptor descriptor)
Given aSCMSourceDescriptor
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated from the descriptor'sSCMSource
.
-
-
-
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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
-
lastModified
public abstract long lastModified() throws IOException, InterruptedException
Returns the time that theSCMFileSystem
was last modified. This should logically be equivalent to the maximumSCMFile.lastModified()
that you would find if you were to do the horribly inefficient traversal of all theSCMFile
instances fromgetRoot()
. Where implementers do not have an easy and quick way to get this information (such as by looking at the commit time of thegetRevision()
HINT HINT) then just return0L
.- Returns:
- A
long
value representing the time theSCMFileSystem
was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970) or0L
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 forgetRoot().child(path)
.- Parameters:
path
- Path of the SCMFile to obtain from the root of the repository.- Returns:
- Child path
-
getRoot
@NonNull public abstract SCMFile getRoot()
Returns theSCMFile
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 andgetRevision()
in the format compatible with theSCM
from thisof(Item, SCM)
to the suppliedOutputStream
. This method allows for consumers or the SCM API to replicate theSCM.checkout(Run, Launcher, FilePath, TaskListener, File, SCMRevisionState)
functionality that captures the changelog without requiring a full checkout.- Parameters:
revision
- the starting revision ornull
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 thisSCMFileSystem
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 aSCM
this method will try to retrieve a correspondingSCMFileSystem
instance.- Parameters:
owner
- the owner of theSCM
scm
- theSCM
.- Returns:
- the corresponding
SCMFileSystem
ornull
if there is none. - Throws:
IOException
- if the attempt to create aSCMFileSystem
failed due to an IO error (such as the remote system being unavailable)InterruptedException
- if the attempt to create aSCMFileSystem
was interrupted.
-
of
@CheckForNull public static SCMFileSystem of(@NonNull Item owner, @NonNull SCM scm, @CheckForNull SCMRevision rev) throws IOException, InterruptedException
Given aSCM
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content at the specifiedSCMRevision
.- Parameters:
owner
- the owner of theSCM
scm
- theSCM
.rev
- the specifiedSCMRevision
.- Returns:
- the corresponding
SCMFileSystem
ornull
if there is none. - Throws:
IOException
- if the attempt to create aSCMFileSystem
failed due to an IO error (such as the remote system being unavailable)InterruptedException
- if the attempt to create aSCMFileSystem
was interrupted.
-
of
@CheckForNull public static SCMFileSystem of(@NonNull Item owner, @NonNull SCM scm, @CheckForNull SCMRevision rev, @CheckForNull Run<?,?> build) throws IOException, InterruptedException
Given aSCM
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content at the specifiedSCMRevision
.- Parameters:
owner
- the owner of theSCM
scm
- theSCM
.rev
- the specifiedSCMRevision
.build
- an associated build context, if any, that could be used for example to look up parameters- Returns:
- the corresponding
SCMFileSystem
ornull
if there is none. - Throws:
IOException
- if the attempt to create aSCMFileSystem
failed due to an IO error (such as the remote system being unavailable)InterruptedException
- if the attempt to create aSCMFileSystem
was interrupted.
-
supports
public static boolean supports(@NonNull SCM scm)
Given aSCM
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated. Returningtrue
does not mean thatof(Item, SCM, SCMRevision, Run)
will be able to instantiate aSCMFileSystem
for any specificSCMRevision
, rather returningfalse
indicates that there is absolutely no point in callingof(Item, SCM, SCMRevision, Run)
as it will always returnnull
.- Parameters:
scm
- theSCMSource
.- Returns:
true
ifof(Item, SCM)
/of(Item, SCM, SCMRevision, Run)
could return aSCMFileSystem
implementation,false
ifof(Item, SCM)
/of(Item, SCM, SCMRevision, Run)
will always returnnull
for the suppliedSCM
.- Since:
- 2.0
-
of
@CheckForNull public static SCMFileSystem of(@NonNull SCMSource source, @NonNull SCMHead head) throws IOException, InterruptedException
Given aSCMSource
and aSCMHead
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content of the specifiedSCMHead
.- Parameters:
source
- theSCMSource
.head
- the specifiedSCMHead
.- Returns:
- the corresponding
SCMFileSystem
ornull
if there is none. - Throws:
IOException
- if the attempt to create aSCMFileSystem
failed due to an IO error (such as the remote system being unavailable)InterruptedException
- if the attempt to create aSCMFileSystem
was interrupted.
-
of
@CheckForNull public static SCMFileSystem of(@NonNull SCMSource source, @NonNull SCMHead head, @CheckForNull SCMRevision rev) throws IOException, InterruptedException
Given aSCMSource
, aSCMHead
and aSCMRevision
this method will try to retrieve a correspondingSCMFileSystem
instance that reflects the content of the specifiedSCMHead
at the specifiedSCMRevision
.- Parameters:
source
- theSCMSource
.head
- the specifiedSCMHead
.rev
- the specifiedSCMRevision
.- Returns:
- the corresponding
SCMFileSystem
ornull
if there is none. - Throws:
IOException
- if the attempt to create aSCMFileSystem
failed due to an IO error (such as the remote system being unavailable)InterruptedException
- if the attempt to create aSCMFileSystem
was interrupted.
-
supports
public static boolean supports(@NonNull SCMSource source)
Given aSCMSource
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated. Returningtrue
does not mean thatof(SCMSource, SCMHead, SCMRevision)
will be able to instantiate aSCMFileSystem
for any specificSCMHead
orSCMRevision
, rather returningfalse
indicates that there is absolutely no point in callingof(SCMSource, SCMHead, SCMRevision)
as it will always returnnull
.- Parameters:
source
- theSCMSource
.- Returns:
true
ifof(SCMSource, SCMHead)
/of(SCMSource, SCMHead, SCMRevision)
could return aSCMFileSystem
implementation,false
ifof(SCMSource, SCMHead)
/of(SCMSource, SCMHead, SCMRevision)
will always returnnull
for the suppliedSCMSource
.- Since:
- 2.0
-
supports
public static boolean supports(@NonNull SCMDescriptor descriptor)
Given aSCMDescriptor
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated from the descriptor'sSCMSource
. Returningtrue
does not mean thatof(Item, SCM, SCMRevision, Run)
will be able to instantiate aSCMFileSystem
for any specificItem
orSCMRevision
, rather returningfalse
indicates that there is absolutely no point in callingof(Item, SCM, SCMRevision, Run)
as it will always returnnull
.- Parameters:
descriptor
- theSCMDescriptor
.- Returns:
true
ifof(Item, SCM, SCMRevision, Run)
could return aSCMFileSystem
implementation,false
ifof(Item, SCM, SCMRevision, Run)
will always returnnull
for the suppliedSCM
.- Since:
- 2.3.0
-
supports
public static boolean supports(@NonNull SCMSourceDescriptor descriptor)
Given aSCMSourceDescriptor
this method will check if there is at least oneSCMFileSystem
provider capable of being instantiated from the descriptor'sSCMSource
. Returningtrue
does not mean thatof(SCMSource, SCMHead, SCMRevision)
will be able to instantiate aSCMFileSystem
for any specificSCMHead
orSCMRevision
, rather returningfalse
indicates that there is absolutely no point in callingof(SCMSource, SCMHead, SCMRevision)
as it will always returnnull
.- Parameters:
descriptor
- theSCMSourceDescriptor
.- Returns:
true
ifof(SCMSource, SCMHead)
/of(SCMSource, SCMHead, SCMRevision)
could return aSCMFileSystem
implementation,false
ifof(SCMSource, SCMHead)
/of(SCMSource, SCMHead, SCMRevision)
will always returnnull
for the suppliedSCMSource
.- Since:
- 2.3.0
-
-