com.atlassian.bitbucket.scm

Interface ScmCommandFactory

public interface ScmCommandFactory

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:

• CommitService
• ContentService
• RefService

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

Method Summary

Modifier and Type	Method and Description
Command<Page<Blame>>	blame(BlameCommandParameters parameters, PageRequest pageRequest) Retrieves blame (also sometimes referred to as annotations) for a file at a given revision.
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.
Command<Page<Branch>>	branches(BranchesCommandParameters parameters, PageRequest pageRequest) Retrieves a page of branches ordered either alphabetically or by modification and optionally filtered.
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.
Command<Page<Change>>	changes(ChangesCommandParameters parameters, PageRequest pageRequest) Retrieves a page of changes describing the modifications made between two revisions, optionally filtered by path.
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.
Command<Commit>	commit(CommitCommandParameters parameters) Retrieves details for the specified commit.
Command<Void>	commits(CommitsCommandParameters parameters, CommitCallback callback) Streams commits which match the provided parameters to the provided callback.
Command<Page<Commit>>	commits(CommitsCommandParameters parameters, PageRequest pageRequest) Retrieves a page of commits matching the specified parameters.
Command<MinimalCommit>	commonAncestor(CommonAncestorCommandParameters parameters) Retrieves the common ancestor for the provided commits
Command<Branch>	defaultBranch() Resolves the default branch for the specified repository.
Command<Void>	diff(DiffCommandParameters parameters, DiffContentCallback callback) Streams a diff between two commits.
Command<Void>	diff(DiffCommandParameters parameters, TypeAwareOutputSupplier outputSupplier) Streams a diff between two commits.
Command<Void>	directory(DirectoryCommandParameters parameters, ContentTreeCallback callback, PageRequest pageRequest) Streams the tree nodes (files, subdirectories and submodules) in the specified directory.
Command<Void>	file(FileCommandParameters parameters, FileContentCallback callback, PageRequest pageRequest) Streams the contents of the specified file.
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.
Command<Void>	refs(RefsCommandParameters parameters, RefCallback callback) Streams all of the refs in the repository.
Command<RepositorySize>	repositorySize(Repository repository, RepositorySizeCommandParameters parameters) Calculates the size for the specified repository.
Command<Map<String,String>>	resolveCommits(ResolveCommitsCommandParameters parameters) Resolves revisions provided on parameters to the referenced commit ID.
Command<Ref>	resolveRef(ResolveRefCommandParameters parameters) Resolves the specified refId, which may be a: branch name tag name commit hash If the refId should be resolved to a specific type, that type should be set to allow the SCM to restrict its search.
Command<Map<String,Ref>>	resolveRefs(ResolveRefsCommandParameters parameters) Resolves refs from the ref IDs provided on parameters, which may be one of branch name tag name commit hash Callers can specify on the parameters whether a provided ID is expected to resolve to a branch, tag, or a ref of unknown type.
Command<Long>	size(SizeCommandParameters parameters) Retrieves the size of the file at the requested path at the specified commit.
Command<Page<Tag>>	tags(TagsCommandParameters parameters, PageRequest pageRequest) Retrieves a page of tags ordered either alphabetically or by modification and optionally filtered.
Command<Void>	tags(TagsCommandParameters parameters, TagCallback callback) Streams tags ordered either alphabetically or by modification and optionally filtered.
Command<Void>	traverseCommits(TraversalCallback callback) Streams all of the commits in the repository reachable from any branch or tag, traversed in topological order.
Command<ContentTreeNode.Type>	type(TypeCommandParameters parameters) Retrieves the type for the specified path at the requested revision, if the path is present.

Method Detail

blame

@Nonnull
Command<Page<Blame>> blame(@Nonnull
                                    BlameCommandParameters parameters,
                                    @Nonnull
                                    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

Since:

5.0

See Also:

BlameCommandParameters, ContentService.getBlame(Repository, String, String, PageRequest), ContentService.streamFile(Repository, String, String, PageRequest, boolean, FileContentCallback)

branches

@Nonnull
Command<Void> branches(@Nonnull
                                BranchesCommandParameters parameters,
                                @Nonnull
                                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:

• If filtering, branches default to alphabetical order
• Otherwise, branches default to modification order

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

Since:

4.6

See Also:

BranchesCommandParameters, RefService.getBranches(RepositoryBranchesRequest, PageRequest)

branches

@Nonnull
Command<Page<Branch>> branches(@Nonnull
                                        BranchesCommandParameters parameters,
                                        @Nonnull
                                        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:

• If filtering, branches default to alphabetical order
• Otherwise, branches default to modification order

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:

BranchesCommandParameters, RefService.getBranches(RepositoryBranchesRequest, PageRequest)

changes

@Nonnull
Command<Void> changes(@Nonnull
                               ChangesCommandParameters parameters,
                               @Nonnull
                               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:

ChangesCommandParameters, CommitService.streamChanges(ChangesRequest, ChangeCallback)

changes

@Nonnull
Command<Page<Change>> changes(@Nonnull
                                       ChangesCommandParameters parameters,
                                       @Nonnull
                                       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:

ChangesCommandParameters, CommitService.getChanges(ChangesRequest, PageRequest)

changesets

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

CommitService.getChangesets(ChangesetsRequest, PageRequest)

commonAncestor

@Nonnull
Command<MinimalCommit> commonAncestor(@Nonnull
                                               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.

Since:

5.0

commit

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

Retrieves details for the specified commit.

If a path is provided, the Commit 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:

CommitCommandParameters, CommitService.getCommit(CommitRequest)

commits

@Nonnull
Command<Void> commits(@Nonnull
                               CommitsCommandParameters parameters,
                               @Nonnull
                               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:

CommitsCommandParameters, CommitService.streamCommits(BulkCommitsRequest, BulkCommitCallback), CommitService.streamCommits(CommitsRequest, CommitCallback), CommitService.streamCommitsBetween(CommitsBetweenRequest, CommitCallback)

commits

@Nonnull
Command<Page<Commit>> commits(@Nonnull
                                       CommitsCommandParameters parameters,
                                       @Nonnull
                                       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:

CommitsCommandParameters, CommitService.getCommits(CommitsRequest, PageRequest), CommitService.getCommitsBetween(CommitsBetweenRequest, PageRequest)

defaultBranch

@Nonnull
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:

RefService.getDefaultBranch(Repository)

diff

@Nonnull
Command<Void> diff(@Nonnull
                            DiffCommandParameters parameters,
                            @Nonnull
                            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:

DiffCommandParameters, CommitService.streamDiff(DiffRequest, DiffContentCallback)

diff

@Nonnull
Command<Void> diff(@Nonnull
                            DiffCommandParameters parameters,
                            @Nonnull
                            TypeAwareOutputSupplier outputSupplier)

Streams a diff between two commits.

Parameters:

parameters - parameters describing the diff to stream

outputSupplier - a supplier which will provide an output stream

Returns:

a command which, when executed, will stream the requested diff

Since:

6.7

See Also:

DiffCommandParameters, CommitService.streamDiff(DiffRequest, TypeAwareOutputSupplier)

directory

@Nonnull
Command<Void> directory(@Nonnull
                                 DirectoryCommandParameters parameters,
                                 @Nonnull
                                 ContentTreeCallback callback,
                                 @Nonnull
                                 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:

DirectoryCommandParameters, ContentService.streamDirectory(Repository, String, String, boolean, ContentTreeCallback, PageRequest)

file

@Nonnull
Command<Void> file(@Nonnull
                            FileCommandParameters parameters,
                            @Nonnull
                            FileContentCallback callback,
                            @Nonnull
                            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:

FileCommandParameters, ContentService.streamFile(Repository, String, String, PageRequest, boolean, FileContentCallback)

rawFile

@Nonnull
Command<Void> rawFile(@Nonnull
                               RawFileCommandParameters parameters,
                               @Nonnull
                               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:

RawFileCommandParameters, ContentService.streamFile(Repository, String, String, TypeAwareOutputSupplier)

refs

@Nonnull
Command<Void> refs(@Nonnull
                            RefsCommandParameters parameters,
                            @Nonnull
                            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

Since:

6.4

repositorySize

@Nonnull
Command<RepositorySize> repositorySize(@Nonnull
                                                Repository repository,
                                                @Nonnull
                                                RepositorySizeCommandParameters parameters)

Calculates the 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.

Parameters:

repository - the repository for which size needs to be calculated.

parameters - the additional parameters (if any) for the size calculation.

Returns:

a command which, when executed, will return the size of the given repository.

Since:

7.14

See Also:

RepositorySize

resolveCommits

@Nonnull
Command<Map<String,String>> resolveCommits(@Nonnull
                                                    ResolveCommitsCommandParameters parameters)

Resolves revisions provided on 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.

Parameters:

parameters - parameters describing the revisions to resolve

Returns:

a command which, when executed, will resolve the requested revisions to a commit ID.

Since:

7.14

resolveRef

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

Resolves the specified refId, which may be a:

• branch name
• tag name
• commit hash

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

Since:

4.6

See Also:

ResolveRefCommandParameters, RefService.resolveRef(ResolveRefRequest)

resolveRefs

@Nonnull
Command<Map<String,Ref>> resolveRefs(@Nonnull
                                              ResolveRefsCommandParameters parameters)

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

• branch name
• tag name
• commit hash

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

Since:

4.4

See Also:

ResolveRefsCommandParameters, RefService.resolveRefs(ResolveRefsRequest)

size

@Nonnull
Command<Long> size(@Nonnull
                            SizeCommandParameters parameters)

Retrieves the size of the file at the requested path at the specified commit. If the path identifies a directory, submodule or other non-file type, the command will return null.

Parameters:

parameters - parameters describing the commit and path to retrieve the size for

Returns:

a command which, when executed, will return the size of the requested path at the specified commit

Since:

7.7

See Also:

SizeCommandParameters, ContentService.getSize(Repository, String, String)

tags

@Nonnull
Command<Void> tags(@Nonnull
                            TagsCommandParameters parameters,
                            @Nonnull
                            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:

• If filtering, tags default to alphabetical order
• Otherwise, tags default to modification order

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:

TagsCommandParameters, RefService.streamTags(RepositoryTagsRequest, TagCallback)

tags

@Nonnull
Command<Page<Tag>> tags(@Nonnull
                                 TagsCommandParameters parameters,
                                 @Nonnull
                                 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:

• If filtering, tags default to alphabetical order
• Otherwise, tags default to modification order

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:

TagsCommandParameters, RefService.getTags(RepositoryTagsRequest, PageRequest)

traverseCommits

@Nonnull
Command<Void> traverseCommits(@Nonnull
                                       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:

CommitService.traverse(TraversalRequest, TraversalCallback)

type

@Nonnull
Command<ContentTreeNode.Type> type(@Nonnull
                                            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:

TypeCommandParameters, ContentService.getType(Repository, String, String)