public interface PluginCommandFactory
ScmCommandFactory.
This interface is intended to be implemented by plugin developers. Functionality provided by this interface
is intended to be consumed using the ScmCommandFactory exposed by the ScmService. Only the system
should ever deal with this interface directly.
All command types on this interface are required to have a working implementation, as this factory describes the basic SCM commands used by the system to provide day-to-day functionality.
cross-repository support is optional. Where factory methods accept secondary
repositories SCMs which do not support cross-repository operations should fail fast,
throwing an UnsupportedOperationException rather than returning a Command;
they should not return a command which throws that exception.
SCM implementations may also provide additional functionality to allow the system to offer enhanced
features, such as pull requests. Such functionality is exposed by other interfaces:
PluginBulkContentCommandFactoryPluginCommandBuilderFactoryPluginCompareCommandFactoryPluginMirrorCommandFactoryPluginExtendedCommandFactoryPluginPullRequestCommandFactoryPluginRefCommandFactory
SCMs which support additional functionality, or have custom Command types, are encouraged to provide a
sub-interface extending from this one exposing that functionality. For example:
//Extends Command to allow canceling it after it has been called and checking whether it's been canceled.
public interface CancelableCommand<T> extends Command<T> {
void cancel();
boolean isCanceled();
}
//Overrides methods on the PluginCommandFactory interface using covariant return types to return the
//enhanced CancelableCommand instead of simple Command
public interface MyScmCommandFactory extends PluginCommandFactory {
@Nonnull
@Override
CancelableCommand<List<Blame>> blame(@Nonnull Repository repository,
@Nonnull BlameCommandParameters parameters,
@Nonnull PageRequest pageRequest);
//Overrides for other methods as appropriate
}
MyScmCommandFactory using a
component directive:
<!-- Note: This should be in the SCM provider's atlassian-plugin.xml -->
<component key="myScmCommandFactory"
class="com.example.DefaultMyScmCommandFactory"
public="true">
<interface>com.example.MyScmCommandFactory</interface>
</component>
public="true" allows other plugins to import the component. This approach allows other plugin developers
to import the SCM plugin's command factory and leverage its enhanced functionality with a component-import
directive:
<!-- Note: This should be in the SCM consumer's atlassian-plugin.xml -->
<component-import key="myScmCommandFactory"
interface="com.example.MyScmCommandFactory"/>
| Modifier and Type | Method and Description |
|---|---|
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.content.Blame>> |
blame(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.BlameCommandParameters parameters,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Retrieves a page of
Blame, providing attribution for each line in the specified file, calculated
from the specified starting commit. |
com.atlassian.bitbucket.scm.Command<Void> |
branches(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.BranchesCommandParameters parameters,
com.atlassian.bitbucket.repository.BranchCallback callback)
Streams
branches in the specified repository to the provided callback. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.repository.Branch>> |
branches(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.BranchesCommandParameters parameters,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Retrieves a page of
branches. |
com.atlassian.bitbucket.scm.Command<Void> |
changes(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.ChangesCommandParameters parameters,
com.atlassian.bitbucket.content.ChangeCallback callback)
Streams
changes between two commits to the provided callback. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.content.Change>> |
changes(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.ChangesCommandParameters parameters,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Retrieves a page of
changes between two commits. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.commit.Changeset>> |
changesets(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.ChangesetsCommandParameters parameters,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Retrieves a page of
changesets given a set of commit IDs, where each changeset includes the first page of changes between a requested commit
and its first parent. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.commit.Commit> |
commit(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.CommitCommandParameters parameters)
Retrieves the requested commit or, if a path was also supplied, retrieves the first commit to modify
that path prior to the requested commit.
|
com.atlassian.bitbucket.scm.Command<Void> |
commits(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.CommitsCommandParameters parameters,
com.atlassian.bitbucket.commit.CommitCallback callback)
Streams commits which match the provided
paramters to the provided callback. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.commit.Commit>> |
commits(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.CommitsCommandParameters parameters,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Retrieves a page of commits which match the provided
paramters. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.commit.MinimalCommit> |
commonAncestor(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.CommonAncestorCommandParameters parameters)
Retrieves the common ancestor for the provided commits
|
com.atlassian.bitbucket.scm.Command<Void> |
create(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.CreateCommandParameters parameters)
Creates and initializes the repository on disk, performing any SCM-specific configuration that is appropriate
for new repositories.
|
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Branch> |
defaultBranch(com.atlassian.bitbucket.repository.Repository repository)
Retrieves the default
Branch for the specified repository. |
com.atlassian.bitbucket.scm.AsyncCommand<Void> |
delete(com.atlassian.bitbucket.repository.Repository repository,
DeleteCommandParameters parameters)
Deletes the repository, allowing the underlying SCM to carry out any special processing necessary to clean up
repository storage.
|
com.atlassian.bitbucket.scm.Command<Void> |
diff(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.DiffCommandParameters parameters,
com.atlassian.bitbucket.content.DiffContentCallback callback)
Streams the diff between two commits to the provided
callback. |
com.atlassian.bitbucket.scm.Command<Void> |
diff(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.DiffCommandParameters parameters,
com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier)
Streams the raw diff between two commits.
|
com.atlassian.bitbucket.scm.Command<Void> |
directory(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.DirectoryCommandParameters parameters,
com.atlassian.bitbucket.content.ContentTreeCallback callback,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Streams a directory listing for the requested path at the specified commit.
|
com.atlassian.bitbucket.scm.Command<Void> |
file(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.FileCommandParameters parameters,
com.atlassian.bitbucket.content.FileContentCallback callback,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Streams lines from the requested path at the specified commit, for non-binary files.
|
com.atlassian.bitbucket.scm.Command<Void> |
rawFile(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.RawFileCommandParameters parameters,
com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier)
Streams the raw bytes for the requested file at the specified commit to
OutputStream returned by the
provided supplier. |
com.atlassian.bitbucket.scm.Command<Void> |
refs(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.RefsCommandParameters parameters,
com.atlassian.bitbucket.repository.RefCallback callback)
Streams all of the refs in the specified repository.
|
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.scm.RepositorySize> |
repositorySize(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.RepositorySizeCommandParameters parameters)
Calculates the
size for the specified repository. |
default com.atlassian.bitbucket.scm.Command<Map<String,String>> |
resolveCommits(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.ResolveCommitsCommandParameters parameters)
Resolves revisions provided on
parameters to the referenced commit ID. |
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Ref> |
resolveRef(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.ResolveRefCommandParameters parameters)
Resolves the specified
refId, which may be a:
branch name
tag name
commit hash
If a name is provided, it must be considered as either an ID or a display ID. |
com.atlassian.bitbucket.scm.Command<Map<String,com.atlassian.bitbucket.repository.Ref>> |
resolveRefs(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.ResolveRefsCommandParameters parameters)
Resolves one or more branches, tags and/or refs.
|
default com.atlassian.bitbucket.scm.Command<Long> |
size(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.SizeCommandParameters parameters)
Retrieves the size of the file at the requested path at the specified commit.
|
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.repository.Tag>> |
tags(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.TagsCommandParameters parameters,
com.atlassian.bitbucket.util.PageRequest pageRequest)
Retrieves a page of
tags. |
com.atlassian.bitbucket.scm.Command<Void> |
tags(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.TagsCommandParameters parameters,
com.atlassian.bitbucket.repository.TagCallback callback)
Streams
tags in the specified repository to the provided callback. |
com.atlassian.bitbucket.scm.Command<Void> |
traverseCommits(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.commit.graph.TraversalCallback callback)
Streams all of the commits in the repository reachable from any branch or tag in topological order.
|
com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.content.ContentTreeNode.Type> |
type(com.atlassian.bitbucket.repository.Repository repository,
com.atlassian.bitbucket.scm.TypeCommandParameters parameters)
Retrieves the
type for the requested path at the specified commit. |
@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.content.Blame>> blame(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.BlameCommandParameters parameters, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
Blame, providing attribution for each line in the specified file, calculated
from the specified starting commit.repository - the repository to calculate blame inparameters - parameters describing the file and starting commit to usepageRequest - describes the page of blame to retrieve@Nonnull com.atlassian.bitbucket.scm.Command<Void> branches(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.BranchesCommandParameters parameters, @Nonnull com.atlassian.bitbucket.repository.BranchCallback callback)
branches in the specified repository to the provided callback.repository - the repository to stream branches fromparameters - parameters describing any filter to apply, and the order to stream branches incallback - a callback to receive the streamed branches@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.repository.Branch>> branches(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.BranchesCommandParameters parameters, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
branches.repository - the repository to retrieve branches fromparameters - parameters describing any filter to apply, and the order to retrieve branches inpageRequest - describes the page of branches to retrieve@Nonnull com.atlassian.bitbucket.scm.Command<Void> changes(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.ChangesCommandParameters parameters, @Nonnull com.atlassian.bitbucket.content.ChangeCallback callback)
changes between two commits to the provided callback.
If the sinceId is not specified, the first ancestor of
the untilId must be used automatically. If the until
commit is the first commit in the repository, and has no ancestors, each file included in that commit should
be streamed as newly added.
repository - the repository to stream changes fromparameters - parameters describing the two commits to compute changes for, as well as limits to applycallback - a callback to receive the streamed changes@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.content.Change>> changes(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.ChangesCommandParameters parameters, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
changes between two commits.
If the sinceId is not specified, the first ancestor of
the untilId must be used automatically. If the until
commit is the first commit in the repository, and has no ancestors, each file included in that commit should
be returned as newly added.
repository - the repository to retrieve changes fromparameters - parameters describing the two commits to compute changes for, as well as limits to applypageRequest - describes the page of changes to retrieve@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.commit.Changeset>> changesets(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.ChangesetsCommandParameters parameters, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
changesets given a set of commit IDs, where each changeset includes the first page of changes between a requested commit
and its first parent.repository - the repository to retrieve changesets fromparameters - parameters describing the changesets to retrievepageRequest - describes the page of changesets to retrieve@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.commit.MinimalCommit> commonAncestor(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.CommonAncestorCommandParameters parameters)
repository - the repository to retrieve the common ancestor fromparameters - common ancestor parametersnull.@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.commit.Commit> commit(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.CommitCommandParameters parameters)
repository - the repository to retrieve the commit fromparameters - parameters describing the commit to retrieve@Nonnull com.atlassian.bitbucket.scm.Command<Void> commits(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.CommitsCommandParameters parameters, @Nonnull com.atlassian.bitbucket.commit.CommitCallback callback)
paramters to the provided callback.
Implementors: SCMs are required to support this operation. However, they are not required
to support secondary repositories unless they offer
cross-repository support. If a secondary repository is provided and cross-
repository operations are not supported, implementations should throw an UnsupportedOperationException.
repository - the repository to retrieve commits fromparameters - parameters describing the commits to retrievecallback - a callback to receive the streamed commitsUnsupportedOperationException - if a secondary
repository is provided an cross-
repository operations are not supportedScmFeature.CROSS_REPOSITORY@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.commit.Commit>> commits(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.CommitsCommandParameters parameters, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
paramters.
Implementors: SCMs are required to support this operation. However, they are not required
to support secondary repositories unless they offer
cross-repository support. If a secondary repository is provided and cross-
repository operations are not supported, implementations should throw an UnsupportedOperationException.
repository - the repository to retrieve commits fromparameters - parameters describing the commits to retrievepageRequest - describes the page of commits to retrieveUnsupportedOperationException - if a secondary
repository is provided an cross-
repository operations are not supportedScmFeature.CROSS_REPOSITORY@Nonnull com.atlassian.bitbucket.scm.Command<Void> create(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.CreateCommandParameters parameters)
repository does not exist on disk when this method is called. The SCM is
expected to create it with contents that are appropriate for an empty, new repository.
Implementors: The default implementation of this method has been removed in 8.0. SCMs are required to implement this command for themselves; they cannot rely on the default.
repository - the repository to createparameters - parameters describing how the repository should be created@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Branch> defaultBranch(@Nonnull com.atlassian.bitbucket.repository.Repository repository)
Branch for the specified repository.
Each repository in an SCM is required to have a default branch. However, that branch is not actually
required to exist within the repository. If the default branch does not exist, the returned command
must throw NoDefaultBranchException; it may not return null.
repository - the repository to retrieve the default branch forNoDefaultBranchException if the default branch does not existScm.getDefaultBranch(Repository)@Nonnull com.atlassian.bitbucket.scm.AsyncCommand<Void> delete(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull DeleteCommandParameters parameters)
Note: By the time this method is called, the repository has already been deleted from the database, and the associated database transaction has been committed.
Warning: This method is irreversible. It should never be called by a plugin. It is intended solely for use by the system.
repository - the repository to deleteparameters - additional parameters, such as IDs for forks of the deleted repository@Nonnull com.atlassian.bitbucket.scm.Command<Void> diff(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.DiffCommandParameters parameters, @Nonnull com.atlassian.bitbucket.content.DiffContentCallback callback)
callback.
If the sinceId is not specified, the diff must be calculated to
the first ancestor of the untilId. If the until
commit is the first commit in the repository, and has no ancestors, content for each file included in that
commit should be streamed as newly added.
Diff implementations are required to honor the following settings:
context line countline lengthline countwhitespace modes they do not natively support.repository - the repository to stream the diff fromparameters - parameters describing the two commits to diff, and additional settings for controlling
the shape and content of the streamed diffcallback - a callback to receive the streamed diff@Nonnull com.atlassian.bitbucket.scm.Command<Void> diff(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.DiffCommandParameters parameters, @Nonnull com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier)
If the sinceId is not specified, the diff must be calculated to
the first ancestor of the untilId. If the until
commit is the first commit in the repository, and has no ancestors, content for each file included in that
commit should be streamed as newly added.
Diff implementations are required to honor the following settings:
context line countwhitespace modes they do not natively support.repository - the repository to stream the diff fromparameters - parameters describing the two commits to diff, and additional settings for controlling
the shape and content of the streamed diffoutputSupplier - a supplier which will provide an output stream@Nonnull com.atlassian.bitbucket.scm.Command<Void> directory(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.DirectoryCommandParameters parameters, @Nonnull com.atlassian.bitbucket.content.ContentTreeCallback callback, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
When a recursive listing is requested, implementations
must only stream non-directory entries. If the SCM tracks
empty directories, they must be omitted.
For non-recursive listings, implementations are encouraged to collapse subdirectories which only have a single entry. For example, consider the following directory structure:
src/
main/
java/
com/
example/
MyClass.java
resources/
pom.xml
new SimplePath("pom.xml), may stream either
of the following values:
new SimplePath("src"), ornew SimplePath("src/main"
A listing at "src/main", in addition to streaming new SimplePath("resources") may stream either
of the following values:
new SimplePath("java"), ornew SimplePath("java/com/example/MyClass.java")
If file sizes are requested, SCMs which can efficiently
include them should do so. If the SCM's internal representation for directory data makes file sizes expensive
to retrieve (such as requiring the entire file to be streamed and its bytes counted, in the worst case), the
SCM should omit size data even if it is requested.
repository - the repository to stream the directory listing fromparameters - parameters describing the directory to list and the commit to list them atcallback - a callback to receive the streamed list of files, subdirectories and submodulespageRequest - describes the page of the directory listing to stream@Nonnull com.atlassian.bitbucket.scm.Command<Void> file(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.FileCommandParameters parameters, @Nonnull com.atlassian.bitbucket.content.FileContentCallback callback, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
When the command is executed, if the requested path identifies a binary file, such as an image or PDF, the
SCM should call FileContentCallback.onBinary().
For SCMs which support multiple file encodings:
ContentDetectionUtils offers static methods for performing binary and encoding detection. It may be
accessed from the following Maven dependency:
<dependency>
<groupId>com.atlassian.bitbucket.server</groupId>
<artifactId>bitbucket-scm-common</artifactId>
<scope>provided</scope>
</dependency>
Implementations are required to honor max line lengths.
If any line in a file exceeds that length, it must be truncated to constrain memory usage.
If annotations are requested, the implementation must
compute the blame(com.atlassian.bitbucket.repository.Repository, com.atlassian.bitbucket.scm.BlameCommandParameters, com.atlassian.bitbucket.util.PageRequest) for each line on the requested page and, after streaming those lines,
offer the blame to the callback.
repository - the repository to stream the file fromparameters - parameters describing the file to stream and the commit to stream it atcallback - a callback to receive the parsed and limited file contentpageRequest - describes the page of the file to streamrawFile(Repository, RawFileCommandParameters, TypeAwareOutputSupplier)@Nonnull com.atlassian.bitbucket.scm.Command<Void> rawFile(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.RawFileCommandParameters parameters, @Nonnull com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier)
OutputStream returned by the
provided supplier.
Prior to streaming bytes, SCM implementations are required to perform best-effort MIME type detection on the
file, and to pass the detected type to the supplier. The Java
URLConnection class offers some static methods to facilitate such detection.
ContentDetectionUtils.detectContentType(BufferedInputStream, String) may also be useful. It may be
accessed from the following Maven dependency:
<dependency>
<groupId>com.atlassian.bitbucket.server</groupId>
<artifactId>bitbucket-scm-common</artifactId>
<scope>provided</scope>
</dependency>
repository - the repository to stream the file fromparameters - parameters describing the file to stream, and the commit to stream it atoutputSupplier - provides an OutputStream to stream the file to, after its MIME type is supplied@Nonnull com.atlassian.bitbucket.scm.Command<Void> refs(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.RefsCommandParameters parameters, @Nonnull com.atlassian.bitbucket.repository.RefCallback callback)
Implementors: A "ref" in this context is any type of ref that would normally be retrieved by the SCM. At a minimum, this should be every branch and every tag in the repository. If the SCM has additional standard refs, they should be included. If the SCM supports optional or nonstandard ref namespaces, any refs stored there should not be included.
Implementors: The default implementation of this method has been removed in 8.0. SCMs are required to implement this command for themselves; they cannot rely on the default.
repository - the repository to stream refs forparameters - parameters to allow evolving the SPI over timecallback - a callback to receive the streamed refs@Nonnull default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.scm.RepositorySize> repositorySize(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.RepositorySizeCommandParameters parameters)
size for the specified repository.
Note: Calculating the size can be an expensive operation. The returned value may be a best effort estimation of the repository size. Implementors: The default implementation of this method will be removed in 9.0. SCMs are required to implement this command for themselves; they cannot rely on the default.
repository - the repository for which size needs to be calculated.parameters - the additional parameters (if any) for the size calculation.size of the given repository.RepositorySize@Nonnull default com.atlassian.bitbucket.scm.Command<Map<String,String>> resolveCommits(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.ResolveCommitsCommandParameters parameters)
parameters to the referenced commit ID. Revisions specified on
parameters can be anything that the SCM can resolve to commit IDs, including branch and tag names.
The command returns a map from the provided revision to the resolved commit ID. If a revision could
not be resolved, no value is returned in the map.
Implementors: The default implementation of this method will be removed in 9.0. SCMs are required to implement this command for themselves; they cannot rely on the default.
repository - the repository to resolve the revisions inparameters - parameters describing the revisions to resolve@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Ref> resolveRef(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.ResolveRefCommandParameters parameters)
refId, which may be a:
branch nametag namecommit hash
If a hash is provided, it may only be resolved to a branch or tag if it identifies the tip commit. If the
hash identifies a commit that is not the tip of a branch or tag, the returned command must return
null.
When a hash or name is provided and resolves to multiple branches, tags or a combination of both, SCM implementors are encouraged to choose a tag over a branch, and to return the "first" branch or tag alphabetically. However, this is not enforced and is not considered part of the contract.
If the parameters specify a ref type, the provided ID must
only be resolved against refs of that type. If a ref of a different type matches, it may not
be returned. Implementations are encouraged to optimize their lookups when a type is provided.
repository - the repository to resolve the ref inparameters - parameters describing the ref to resolve, optionally including a type hintBranch or
Tag@Nonnull com.atlassian.bitbucket.scm.Command<Map<String,com.atlassian.bitbucket.repository.Ref>> resolveRefs(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.ResolveRefsCommandParameters parameters)
Implementations may only resolve branch IDs and
tag IDs against branches and
tags, respectively. If a ref a different type matches, it may not be returned.
Ref IDs may be resolved against refs of any type. When
an ID resolves to multiple branches, tags or a combination of both, SCM implementors are encouraged
to choose a tag over a branch, and to return the "first" branch or tag alphabetically. However, this is
not enforced, and is not considered part of the contract.
repository - the repository to resolve the refs inparameters - parameters describing the branches, tags and refs to resolveref it resolved to@Nonnull default com.atlassian.bitbucket.scm.Command<Long> size(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.SizeCommandParameters parameters)
The returned command must:
null if the path identifies a directory or submodule (or other non-file type)NoSuchCommitException if the specified commit does not existNoSuchPathException if the specified path does not exist in the commitImplementors: The default implementation of this method will be removed in 9.0. SCMs are required to implement this command for themselves; they cannot rely on the default.
repository - the repository to retrieve the file size fromparameters - parameters describing the commit and path to retrieve the size for@Nonnull com.atlassian.bitbucket.scm.Command<Void> tags(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.TagsCommandParameters parameters, @Nonnull com.atlassian.bitbucket.repository.TagCallback callback)
tags in the specified repository to the provided callback.repository - the repository to stream tags fromparameters - parameters describing any filter to apply, and the order to stream tags incallback - a callback to receive the streamed tags@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.util.Page<com.atlassian.bitbucket.repository.Tag>> tags(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.TagsCommandParameters parameters, @Nonnull com.atlassian.bitbucket.util.PageRequest pageRequest)
tags.repository - the repository to retrieve tags fromparameters - parameters describing any filter to apply, and the order to retrieve tags inpageRequest - describes the page of tags to retrieve@Nonnull com.atlassian.bitbucket.scm.Command<Void> traverseCommits(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.commit.graph.TraversalCallback callback)
repository - the repository to traverse commits forcallback - the callback to receive the streamed commits@Nonnull com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.content.ContentTreeNode.Type> type(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull com.atlassian.bitbucket.scm.TypeCommandParameters parameters)
type for the requested path at the specified commit. The same
path may have different types at different commits as the repository's contents change.
The command may not return null for any reason. If the specified commit does not exist in the
repository, the returned command must throw NoSuchCommitException. If the requested path
does not exist in the specified commit, the returned command must throw NoSuchPathException.
repository - the repository to retrieve the type fromparameters - parameters describing the commit and path to retrieve the type forCopyright © 2024 Atlassian. All rights reserved.