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.

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<List<Blame>> blame(BlameCommandParameters parameters, PageRequest pageRequest)
Retrieves blame (also sometimes referred to as annotations) for a file at a given revision.
@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 paramters to the provided callback.
@Nonnull Command<Page<Commit>> commits(CommitsCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of commits matching the specified parameters.
@Nonnull Command<Void> create()
Creates and initializes the repository, performing any initial configuration that is appropriate for 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.
@Nonnull Command<Void> fork(Repository fork)
Forks the working repository and stores the new fork in the provided fork repository.
@Nonnull Command<Void> heads(RefCallback callback)
Streams refs for all of the heads in the repository.
@Nonnull Command<Branch> merge(MergeCommandParameters parameters)
Merges the specified fromCommitId into the specified toBranch.
@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(String refId)
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.
@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.
@Nonnull Command<Void> updateDefaultBranch(String branchName)
Sets the default branch for the repository to the specified branch.

Public Methods

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

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
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 paramters 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<Void> create ()

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

@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

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

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

@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

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

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

@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<Ref> resolveRef (String refId)

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
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, 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

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

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