com.atlassian.bitbucket.scm

Interface ScmExtendedCommandFactory

public interface ScmExtendedCommandFactory

Creates commands which provide optional SCM functionality such as merging two branches or updating the default branch. Each method accepts a set of CommandParameters which are used to control the command's behaviour and output.

Each command on this factory has an associated SCM feature. Prior to using any of these commands, callers should check if the feature is supported. Failure to do so will result in FeatureUnsupportedScmExceptions when requesting unsupported commands.

Since:

4.6

Method Summary

Modifier and Type	Method and Description
Command<Void>	archive(ArchiveCommandParameters parameters, TypeAwareOutputSupplier outputSupplier) Streams an archive of the specified commit in the requested format.
Command<Commit>	editFile(EditFileCommandParameters parameters) Adds a new file or updates the content of an existing file as described in the parameters.
Command<Void>	lastModified(LastModifiedCommandParameters parameters, LastModifiedCallback callback) Streams the latest commit to modify each file in the specified path, using the provided commit as the starting point for the traversal.
Command<Branch>	merge(MergeCommandParameters parameters) Merges the specified fromCommitId into the specified toBranch.
Command<Void>	patch(PatchCommandParameters parameters, TypeAwareOutputSupplier outputSupplier) Streams a patch for a given commit or commit range.
Command<Void>	push(PushCommandParameters parameters, PushCallback callback) Pushes the repository to the URL specified in the parameters.
Command<Void>	signedObjects(SignedObjectsParameters parameters, SignedObjectCallback callback) Retrieves requested objects and if the object is signed, provides the signature and signed content to the callback.
Command<Void>	updateDefaultBranch(UpdateDefaultBranchCommandParameters parameters) Sets the default branch for the repository to the specified branch.

Method Detail

archive

@Nonnull
Command<Void> archive(@Nonnull
                               ArchiveCommandParameters parameters,
                               @Nonnull
                               TypeAwareOutputSupplier outputSupplier)

Streams an archive of the specified commit in the requested format.

The provided commit ID may be:

• A branch ID or display ID
• A commit ID
  • Display IDs are not supported; there is no guarantee a given display ID will be unique within the repository
• A tag ID or display ID

This operation is optional and may not be supported by all SCM implementations. Calling this method on an SCM which does not support it will result in a FeatureUnsupportedScmException.

Parameters:

parameters - parameters describing the commit to archive and the format to produce the archive in

outputSupplier - a supplier which, when given the archive content type, will provide an output stream

Returns:

a command which, when executed, will stream an archive of the repository at the specified commit

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support archiving repositories

Since:

5.1

See Also:

ContentService.streamArchive(ArchiveRequest, TypeAwareOutputSupplier), ScmFeature.ARCHIVE

editFile

@Nonnull
Command<Commit> editFile(@Nonnull
                                  EditFileCommandParameters parameters)

Adds a new file or updates the content of an existing file as described in the parameters.

This operation is optional and may not be supported by all SCM implementations. Calling this method on an SCM which does not support it will result in a FeatureUnsupportedScmException.

Parameters:

parameters - parameters describing the file to be edited

Returns:

a command which, when executed, will edit the content of a file

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support editing a file.

Since:

4.13

See Also:

ContentService.editFile(EditFileRequest), ScmFeature.EDIT_FILE

lastModified

@Nonnull
Command<Void> lastModified(@Nonnull
                                    LastModifiedCommandParameters parameters,
                                    @Nonnull
                                    LastModifiedCallback callback)

Streams the latest commit to modify each file in the specified path, using the provided commit as the starting point for the traversal.

This operation is optional and may not be supported by all SCM implementations. Calling this method on an SCM which does not support it will result in a FeatureUnsupportedScmException.

Parameters:

parameters - parameters describing the path to stream modifications for, and the starting commit for the traversal

callback - a callback to receive the latest commit for files in the specified path

Returns:

a command which, when executed, will stream the latest commit to modify each file in the specified path

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support streaming modifications

See Also:

CommitService.streamLastModified(LastModifiedRequest, LastModifiedCallback), ScmFeature.LAST_MODIFIED

merge

@Nonnull
Command<Branch> merge(@Nonnull
                               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. Calling this method on an SCM which does not support it will result in a FeatureUnsupportedScmException.

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

Parameters:

parameters - parameters describing the branches to merge

Returns:

a command which, when executed, will merge the specified commit into the target branch

Throws:

FeatureUnsupportedScmException - 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:

ScmFeature.MERGE

patch

@Nonnull
Command<Void> patch(@Nonnull
                             PatchCommandParameters parameters,
                             @Nonnull
                             TypeAwareOutputSupplier outputSupplier)

Streams a patch for a given commit or commit range.

If PatchCommandParameters.isAllAncestors() is true then the patch includes all ancestors of the "until" revision. Otherwise the patch starts from the "since" revision, if specified, or from the parent of the "until" revision.

This operation is optional and may not be supported by all SCM implementations. Calling this method on an SCM which does not support it will result in a FeatureUnsupportedScmException.

Parameters:

parameters - parameters describing the commit for which to generate the patch

outputSupplier - a supplier which will provide an output stream

Returns:

a command which, when executed, will stream a patch of the diff at the specified commit

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support patches for repositories

Since:

6.7

See Also:

ContentService.streamPatch(PatchRequest, TypeAwareOutputSupplier), ScmFeature.PATCH

push

@Nonnull
Command<Void> push(@Nonnull
                            PushCommandParameters parameters,
                            @Nonnull
                            PushCallback callback)

Pushes the repository to the URL specified in the parameters.

Parameters:

parameters - parameters describing the target of the push, optional authentication and which refs should be included

callback - a callback that will receive ref updates, ref failures and progress updates

Returns:

a command which, when executed, will perform a push of the repository to the URL specified

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support pushing

Since:

7.11

See Also:

ScmFeature.PUSH

signedObjects

@Nonnull
Command<Void> signedObjects(@Nonnull
                                     SignedObjectsParameters parameters,
                                     @Nonnull
                                     SignedObjectCallback callback)

Retrieves requested objects and if the object is signed, provides the signature and signed content to the callback.

Parameters:

parameters - describes which objects to retrieve

callback - callback to receive the requested objects

Returns:

a command which, when executed, will retrieve the requested objects and provides them to the provided callback

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support retrieving signed objects

Since:

5.1

See Also:

ScmFeature.SIGNED_OBJECTS

updateDefaultBranch

@Nonnull
Command<Void> updateDefaultBranch(@Nonnull
                                           UpdateDefaultBranchCommandParameters parameters)

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

This operation is optional and may not be supported by all SCM implementations. Calling this method on an SCM which does not support it will result in a FeatureUnsupportedScmException.

Parameters:

parameters - parameters describing the branch to make the default

Returns:

a command which, when executed, will update the repository's default branch

Throws:

FeatureUnsupportedScmException - if the underlying SCM does not support setting the default branch

See Also:

RefService.setDefaultBranch(Repository, String), ScmFeature.UPDATE_DEFAULT_BRANCH