public interface

ScmCommandFactory

com.atlassian.bitbucket.scm.ScmCommandFactory

Class Overview

Creates commands which provide basic SCM functionality such as creating repositories, retrieving commits and viewing diffs. Each method accepts a set of CommandParameters which are used to control the command's behaviour and output.

In general, commands fall into two categories:

  • Paged: Accept a PageRequest describing the page of output that should be returned and return an object graph when the command is executed
  • Streamed: Accept a callback to receive output and return Void (usually null) when the command is executed
Streaming commands are generally expected to handle their own paging, though there are some exceptions.

Most of the commands on this factory are required, and any SCM used with the system must support them. However, the following commands are optional:

The features for the optional commands should be checked with the ScmService prior to use.

Warning: All of the optional commands on this factory will be removed in 5.0. Callers should update their code to use ScmExtendedCommandFactory instead. From 5.0, only required commands will be provided by this factory.

Note: The repository against which created commands will operate was specified when the factory was retrieved from the ScmService, and cannot be changed.

Plugin developers: This is probably not the interface you want to use. The API provides services whose functionality is backed by the SCM. Using those services automatically chooses the correct SCM based on the repository, and provides a more stable, compatible API. In general, the functionality of this command factory is exposed by:

The documentation for each method on this interface includes a link to the API service method or methods which expose it.

Summary

Public Methods
@Deprecated @Nonnull Command<List<Blame>> blame(BlameCommandParameters parameters, PageRequest pageRequest)
This method is deprecated. in 4.6 to note that the return type will change to Command<Page<Blame>> in 5.0.
@Nonnull Command<Page<Branch>> branches(BranchesCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of branches ordered either alphabetically or by modification and optionally filtered.
@Nonnull Command<Void> branches(BranchesCommandParameters parameters, BranchCallback callback)
Retrieves a Command which, when executed, will stream branches ordered either alphabetically or by modification and optionally filtered.
@Nonnull Command<Page<Change>> changes(ChangesCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of changes describing the modifications made between two revisions, optionally filtered by path.
@Nonnull Command<Void> changes(ChangesCommandParameters parameters, ChangeCallback callback)
Retrieves a Command which, when executed, will stream changes describing modifications made between two revisions, optionally filtered by path.
@Nonnull Command<Page<Changeset>> changesets(ChangesetsCommandParameters parameters, 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.
@Nonnull Command<Commit> commit(CommitCommandParameters parameters)
Retrieves details for the specified commit.
@Nonnull Command<Void> commits(CommitsCommandParameters parameters, CommitCallback callback)
Streams commits which match the provided parameters to the provided callback.
@Nonnull Command<Page<Commit>> commits(CommitsCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of commits matching the specified parameters.
@Deprecated @Nonnull Command<Void> create()
This method is deprecated. in 4.6 for removal without replacement in 5.0. Creating repositories should be done using the RepositoryService, which creates the repository in the database as well as in the SCM.
@Nonnull Command<Branch> defaultBranch()
Resolves the default branch for the specified repository.
@Nonnull Command<Void> diff(DiffCommandParameters parameters, DiffContentCallback callback)
Streams a diff between two commits.
@Nonnull Command<Void> directory(DirectoryCommandParameters parameters, ContentTreeCallback callback, PageRequest pageRequest)
Streams the tree nodes (files, subdirectories and submodules) in the specified directory.
@Nonnull Command<Void> file(FileCommandParameters parameters, FileContentCallback callback, PageRequest pageRequest)
Streams the contents of the specified file.
@Deprecated @Nonnull Command<Void> fork(Repository fork)
This method is deprecated. in 4.6 for removal without replacement in 5.0. Forking repositories should be done using the RepositoryService, which creates the forked repository in the database as well as in the SCM.
@Nonnull Command<Void> heads(RefCallback callback)
Streams refs for all of the heads in the repository.
@Deprecated @Nonnull Command<Branch> merge(MergeCommandParameters parameters)
This method is deprecated. in 4.6 for removal in 5.0. Use merge(MergeCommandParameters) instead.
@Nonnull Command<Void> rawFile(RawFileCommandParameters parameters, TypeAwareOutputSupplier outputSupplier)
Streams the raw content of the given file after performing a best effort detection of its MIME type.
@Nonnull Command<Ref> resolveRef(ResolveRefCommandParameters parameters)
Resolves the specified refId, which may be a: If the refId should be resolved to a specific type, that type should be set to allow the SCM to restrict its search.
@Deprecated @Nonnull Command<Ref> resolveRef(String refId)
This method is deprecated. in 4.6 for removal in 5.0. Use resolveRef(ResolveRefCommandParameters) instead.
@Nonnull Command<Map<StringRef>> resolveRefs(ResolveRefsCommandParameters parameters)
Resolves refs from the ref IDs provided on parameters, which may be one of Callers can specify on the parameters whether a provided ID is expected to resolve to a branch, tag, or a ref of unknown type.
@Nonnull Command<Page<Tag>> tags(TagsCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of tags ordered either alphabetically or by modification and optionally filtered.
@Nonnull Command<Void> tags(TagsCommandParameters parameters, TagCallback callback)
Streams tags ordered either alphabetically or by modification and optionally filtered.
@Nonnull Command<Void> traverseCommits(TraversalCallback callback)
Streams all of the commits in the repository, traversed in topological order.
@Nonnull Command<ContentTreeNode.Type> type(TypeCommandParameters parameters)
Retrieves the type for the specified path at the requested revision, if the path is present.
@Deprecated @Nonnull Command<Void> updateDefaultBranch(String branchName)
This method is deprecated. in 4.6 for removal in 5.0. Use updateDefaultBranch(UpdateDefaultBranchCommandParameters) instead.

Public Methods

@Deprecated @Nonnull public Command<List<Blame>> blame (BlameCommandParameters parameters, PageRequest pageRequest)

This method is deprecated.
in 4.6 to note that the return type will change to Command<Page<Blame>> in 5.0.

Retrieves blame (also sometimes referred to as annotations) for a file at a given revision.

This command is paged somewhat differently than others, in that it does not return a Page and instead returns a List. The PageRequest provided determines the lines in the file for which blame is calculated, and only lines within the scope of the page request will be returned. However, because adjacent lines may be spanned by a single author, the number of distinct Blame objects returned will frequently be less than the limit.

Parameters
parameters parameters describing the file and revision used to calculate blame
pageRequest describes the set of lines in the file to calculate blame for
Returns
  • a command which, when executed, will return the calculated Blame for the specified file and revision for the requested set of lines

@Nonnull public Command<Page<Branch>> branches (BranchesCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of branches ordered either alphabetically or by modification and optionally filtered.

When no explicit order is requested, the default ordering depends on whether a filter was provided:

Modification order retrieves branches based on the date of their most recent commit.

Parameters
parameters parameters describing desired order and filter text
pageRequest describes the set of branches to return
Returns
  • a command which, when executed, will return the requested page of branches

@Nonnull public Command<Void> branches (BranchesCommandParameters parameters, BranchCallback callback)

Retrieves a Command which, when executed, will stream branches ordered either alphabetically or by modification and optionally filtered.

When no explicit order is requested, the default ordering depends on whether a filter was provided:

Modification order retrieves branches based on the date of their most recent commit.

Parameters
parameters parameters describing desired order and filter text
callback the callback to receive streamed branches
Returns
  • a command which, when executed, will stream branches

@Nonnull public Command<Page<Change>> changes (ChangesCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of changes describing the modifications made between two revisions, optionally filtered by path.

If no explicit "since" revision is specified, it defaults to the parent of the "until" revision. If the "until" revision specifies a merge commit (a commit with multiple parents), no changes will be returned.

Note: Some changes, such as copies and moves, affect more than one path. When filtering by path, if both paths are not available the change's type may not be correctly detected by some SCMs.

Parameters
parameters parameters describing the revisions to compare and paths to filter by
pageRequest describes the set of changes to return
Returns
  • a command which, when executed, will return the requested page of changes

@Nonnull public Command<Void> changes (ChangesCommandParameters parameters, ChangeCallback callback)

Retrieves a Command which, when executed, will stream changes describing modifications made between two revisions, optionally filtered by path.

If no explicit "since" revision is specified, it defaults to the parent of the "until" revision. If the "until" revision specifies a merge commit (a commit with multiple parents), no changes will be returned.

Note: Some changes, such as copies and moves, affect more than one path. When filtering by path, if both paths are not available the change's type may not be correctly detected by some SCMs.

Parameters
parameters parameters describing the revisions to compare and paths to filter by
callback the callback to receive streamed commits
Returns
  • a command which, when executed, will stream changes

@Nonnull public Command<Page<Changeset>> changesets (ChangesetsCommandParameters parameters, 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.

Parameters
parameters parameters describing the changesets to retrieve
pageRequest describes the page of changesets to retrieve
Returns
  • a command which, when executed, will retrieve a page of changesets

@Nonnull public Command<Commit> commit (CommitCommandParameters parameters)

Retrieves details for the specified commit.

If a path is provided, the Changeset returned may not be for the specified commit. Instead, that commit is used as a starting point and details for the first commit in its ancestry which affects that path are returned.

Parameters
parameters parameters describing the commit to retrieve details for
Returns
  • a command which, when executed, will return details for the specified commit

@Nonnull public Command<Void> commits (CommitsCommandParameters parameters, CommitCallback callback)

Streams commits which match the provided parameters to the provided callback.

Parameters
parameters parameters describing the commits to retrieve
callback a callback to receive the streamed commits
Returns
  • a command which, when executed, will stream commits to the provided callback
Throws
UnsupportedOperationException if a secondary repository is provided an cross- repository operations are not supported

@Nonnull public Command<Page<Commit>> commits (CommitsCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of commits matching the specified parameters.

If the SCM supports cross-repository operations, a secondary repository may be provided. Otherwise, it must be omitted or match the target repository.

Parameters
parameters parameters describing which commits to retrieve
pageRequest describes the set of commits to return
Returns
  • a command which, when executed, will retrieve a page of commits
Throws
UnsupportedOperationException if a secondary repository was provided and the underlying SCM does not support cross-repository operations

@Deprecated @Nonnull public Command<Void> create ()

This method is deprecated.
in 4.6 for removal without replacement in 5.0. Creating repositories should be done using the RepositoryService, which creates the repository in the database as well as in the SCM.

Creates and initializes the repository, performing any initial configuration that is appropriate for the SCM.

Note: This command may be called exactly once for any repository. Subsequent executions will fail; they will not reinitialise the repository.

Returns
  • a command which, when executed, will create the repository and configure it

@Nonnull public Command<Branch> defaultBranch ()

Resolves the default branch for the specified repository.

The returned command may throw NoDefaultBranchException, when executed, if the specified repository does not have a resolvable default branch. This might happen, for example, on a new repository with no commits, or if the only commits to a repository have been to a branch other than the default branch.

Returns
  • a command which, when executed, will retrieve the repository's default branch
Throws
NoDefaultBranchException if the repository does not have a resolvable default branch

@Nonnull public Command<Void> diff (DiffCommandParameters parameters, DiffContentCallback callback)

Streams a diff between two commits.

Parameters
parameters parameters describing the diff to stream
callback the callback to receive the streamed diff
Returns
  • a command which, when executed, will stream the requested diff

@Nonnull public Command<Void> directory (DirectoryCommandParameters parameters, ContentTreeCallback callback, PageRequest pageRequest)

Streams the tree nodes (files, subdirectories and submodules) in the specified directory.

Parameters
parameters parameters providing the directory to stream and the revision to stream it for
callback the callback to receive the streamed nodes
pageRequest describes the set of nodes to stream
Returns
  • a command which, when executed, will stream the requested directory's contents

@Nonnull public Command<Void> file (FileCommandParameters parameters, FileContentCallback callback, PageRequest pageRequest)

Streams the contents of the specified file.

Parameters
parameters parameters describing the file to stream and the revision to stream it for
callback the callback to receive the streamed content
pageRequest describes the set of lines in the file to stream
Returns
  • a command which, when executed, will stream the requested file's content

@Deprecated @Nonnull public Command<Void> fork (Repository fork)

This method is deprecated.
in 4.6 for removal without replacement in 5.0. Forking repositories should be done using the RepositoryService, which creates the forked repository in the database as well as in the SCM.

Forks the working repository and stores the new fork in the provided fork repository.

This operation is optional and may not be supported by all SCM implementations. Such implementations will throw an UnsupportedOperationException.

Parameters
fork the forked repository
Returns
  • a command to create the specified fork
Throws
UnsupportedOperationException if the underlying SCM does not support forking repositories

@Nonnull public Command<Void> heads (RefCallback callback)

Streams refs for all of the heads in the repository. The exact definition of "heads" is an SCM-specific detail, but it will generally include all branches and tags in the repository.

Note: This method is not exposed via the service API. It is only available directly on the SCM API.

Parameters
callback the ref callback that will be called for each head
Returns
  • a command which, when executed, will stream repository heads

@Deprecated @Nonnull public Command<Branch> merge (MergeCommandParameters parameters)

This method is deprecated.
in 4.6 for removal in 5.0. Use merge(MergeCommandParameters) instead.

Merges the specified fromCommitId into the specified toBranch.

The provided fromCommitId may be:

  • A 40-byte hash (Note: Short hashes are not supported)
  • A fully-qualified branch name
  • A short branch name
The provided toBranch, as the parameter name suggests, must be a branch name, either fully qualified or short; using a hash (full or short) is not supported.

If the SCM supports cross-repository merges, a different from repository may be provided. Otherwise, it must be omitted or match the target repository.

This operation is optional and may not be supported by all SCM implementations. Such implementations will throw an UnsupportedOperationException.

Note: This method is not exposed via the service API. It is only available directly on the SCM API.

Returns
  • a command which, when executed, will merge the specified commit into the target branch
Throws
UnsupportedOperationException if the underlying SCM does not support merging branches, or if a cross-repository merge was requested and the SCM doesn't support cross-repository merges

@Nonnull public Command<Void> rawFile (RawFileCommandParameters parameters, TypeAwareOutputSupplier outputSupplier)

Streams the raw content of the given file after performing a best effort detection of its MIME type. That MIME type will be used to retrieve an OutputStream from the provided supplier, and the file's raw content will then be written to the returned stream.

Parameters
parameters parameters used to specify the path and version of the file to stream
outputSupplier the supplier which, when given a content type, will provide an output stream
Returns
  • a command which, when executed, will determine the file's type and then stream its data

@Nonnull public Command<Ref> resolveRef (ResolveRefCommandParameters parameters)

Resolves the specified refId, which may be a:

If the refId should be resolved to a specific type, that type should be set to allow the SCM to restrict its search.

If a hash is provided, it will be resolved to the branch or tag it is the tip of. If it is not the tip of any branch or tag, it will resolve to null. If a type was specified, the hash will only be resolved against that type.

When a hash is provided and resolves to multiple branches, tags or a combination of both, it is left to the SCM implementation to determine the result. SCM implementors are encouraged to choose a tag over a branch, and to return the "first" branch or tag, ordered alphabetically, but this is not enforced.

Parameters
parameters parameters describing the ref to resolve
Returns
  • a command which, when executed, will resolve the specified ref

@Deprecated @Nonnull public Command<Ref> resolveRef (String refId)

This method is deprecated.
in 4.6 for removal in 5.0. Use resolveRef(ResolveRefCommandParameters) instead.

Resolves the specified refId, which may be a:

If a hash is provided, it will be resolved to the branch or tag it is the tip of. If it is not the tip of any branch or tag, it will resolve to null.

When a hash is provided and resolves to multiple branches, tags or a combination of both, it is left to the SCM implementation to determine the result. SCM implementors are encouraged to choose a tag over a branch, and to return the "first" branch or tag, ordered alphabetically, but this is not enforced.

Parameters
refId the ref ID to resolve, which may be a branch or tag name or a commit hash
Returns
  • a command which, when executed, will resolve the specified ref

@Nonnull public Command<Map<StringRef>> resolveRefs (ResolveRefsCommandParameters parameters)

Resolves refs from the ref IDs provided on parameters, which may be one of

Callers can specify on the parameters whether a provided ID is expected to resolve to a branch, tag, or a ref of unknown type.

If hashes are provided, they will be resolved to branches or tags they are the tip of. If they are not the tip of any branch or tag, they will resolve to null and will not be included in the returned map.

When a hash is provided and resolves to multiple branches, tags or a combination of both, it is left to the SCM implementation to determine the result. SCM implementors are encouraged to choose a tag over a branch, and to return the "first" branch or tag, ordered alphabetically, but this is not enforced.

Parameters
parameters describes the ref IDs to resolve
Returns
  • a command which, when executed, will resolve the specified refs

@Nonnull public Command<Page<Tag>> tags (TagsCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of tags ordered either alphabetically or by modification and optionally filtered.

When no explicit order is requested, the default ordering depends on whether a filter was provided:

Modification order retrieves tags based on the date of their most recent commit.

Parameters
parameters parameters describing desired order and filter text
pageRequest describes the set of tags to return
Returns
  • a command which, when executed, will return the requested page of tags

@Nonnull public Command<Void> tags (TagsCommandParameters parameters, TagCallback callback)

Streams tags ordered either alphabetically or by modification and optionally filtered.

When no explicit order is requested, the default ordering depends on whether a filter was provided:

Modification order retrieves tags based on the date of their most recent commit.

Parameters
parameters parameters describing desired order and filter text
callback a callback to receive the streamed commits
Returns
  • a command which, when executed, will stream tags to the provided callback

@Nonnull public Command<Void> traverseCommits (TraversalCallback callback)

Streams all of the commits in the repository, traversed in topological order.

Parameters
callback the callback to receive the streamed commits
Returns
  • a command which, when executed, will stream a topological traversal of all of the commits in the repository

@Nonnull public Command<ContentTreeNode.Type> type (TypeCommandParameters parameters)

Retrieves the type for the specified path at the requested revision, if the path is present. Note that the same path might have different types between revisions but the root entry ("", "\" or "/") will always be a directory.

Parameters
parameters parameters describing the path to check, and the revision to check it for
Returns
  • a command which, when executed, will return the requested path's type

@Deprecated @Nonnull public Command<Void> updateDefaultBranch (String branchName)

This method is deprecated.
in 4.6 for removal in 5.0. Use updateDefaultBranch(UpdateDefaultBranchCommandParameters) instead.

Sets the default branch for the repository to the specified branch.

This operation is optional and may not be supported by all SCM implementations. Such implementations will throw an UnsupportedOperationException.

Parameters
branchName the branch to make the default
Returns
  • a command which, when executed, will update the repository's default branch
Throws
IllegalArgumentException if the provided branchName is null or blank
UnsupportedOperationException if the underlying SCM does not support setting the default branch