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.

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
@Nonnull Command<Page<Blame>> blame(BlameCommandParameters parameters, PageRequest pageRequest)
Retrieves blame (also sometimes referred to as annotations) for a file at a given revision.
@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<Branch>> branches(BranchesCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of 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.
@Nonnull Command<MinimalCommit> commonAncestor(CommonAncestorCommandParameters parameters)
Retrieves the common ancestor for the provided commits
@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> heads(RefCallback callback)
This method is deprecated. in 6.4 for removal in 7.0. Use refs(RefsCommandParameters, RefCallback) 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<Void> refs(RefsCommandParameters parameters, RefCallback callback)
Streams all of the refs in the repository.
@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.
@Nonnull Command<Map<String, Ref>> 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 reachable from any branch or tag, 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.

Public Methods

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

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

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
See Also

@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
See Also

@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
See Also

@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
See Also

@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
See Also

@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
See Also

@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
See Also

@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
See Also

@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
See Also

@Nonnull public Command<MinimalCommit> commonAncestor (CommonAncestorCommandParameters parameters)

Retrieves the common ancestor for the provided commits

Parameters
parameters parameters describing which common ancestor to retrieve
Returns
  • a command which, when executed, returns the common ancestor of the provided commits. If the provided commits do not have a common ancestor, the command returns null.

@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
See Also

@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
See Also

@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
See Also

@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
See Also

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

This method is deprecated.
in 6.4 for removal in 7.0. Use refs(RefsCommandParameters, RefCallback) instead.

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

@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
See Also

@Nonnull public Command<Void> refs (RefsCommandParameters parameters, RefCallback callback)

Streams all of the refs in the repository. The exact specification for what "refs" includes 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
parameters parameters to allow evolving the SPI over time
callback the ref callback that will be called for each ref
Returns
  • a command which, when executed, will stream repository refs

@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
See Also

@Nonnull public Command<Map<String, Ref>> 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
See Also

@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
See Also

@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
See Also

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

Streams all of the commits in the repository reachable from any branch or tag, 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
See Also

@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
See Also