com.atlassian.bitbucket.scm

Interface PluginExtendedCommandFactory

public interface PluginExtendedCommandFactory

Provides backing functionality for the ScmExtendedCommandFactory.

This interface is intended to be implemented by plugin developers. Functionality provided by this interface is intended to be consumed using the ScmExtendedCommandFactory exposed by the ScmService. Only the system should ever deal with this interface directly.

This interface describes optional commands which an SCM implementor may provide to extend the functionality of their SCM. Some features, like auto-merging between release branches and creating forks, rely on these optional commands. If the SCM does not implement them, the features which depend on them will be disabled.

Since:

4.6

Method Summary

Modifier and Type	Method and Description
default com.atlassian.bitbucket.scm.Command<Void>	archive(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.ArchiveCommandParameters parameters, com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier) Streams an archive of the repository at the specified commit, in the requested format.
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.commit.Commit>	editFile(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.EditFileCommandParameters parameters) Adds a new file or updates the content of an existing file as described in the parameters.
default com.atlassian.bitbucket.scm.Command<Void>	fork(com.atlassian.bitbucket.repository.Repository repository, ForkCommandParameters parameters) Creates a fork of repository, stored in the specified fork.
default com.atlassian.bitbucket.scm.Command<Void>	lastModified(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.LastModifiedCommandParameters parameters, com.atlassian.bitbucket.commit.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.
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Branch>	merge(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.MergeCommandParameters parameters) Merges the specified {@link MergeCommandParameters#getFromCommitId() fromCommitId} into the specified {@link MergeCommandParameters#getToBranch() toBranch}.
default com.atlassian.bitbucket.scm.Command<Void>	patch(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.PatchCommandParameters parameters, com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier) Streams a patch of the specified repository for a given commit or commit range.
default com.atlassian.bitbucket.scm.Command<Void>	push(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.PushCommandParameters parameters, com.atlassian.bitbucket.scm.PushCallback callback) Pushes the repository to the URL specified in the parameters.
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Branch>	revert(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.RevertCommandParameters parameters) Reverts the specified commit on a given branch as described by the parameters.
default com.atlassian.bitbucket.scm.Command<Void>	signedObjects(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.signed.SignedObjectsParameters parameters, com.atlassian.bitbucket.scm.signed.SignedObjectCallback callback) Retrieves requested objects and if the object is signed, provides the signature and signed content to the callback.
default com.atlassian.bitbucket.scm.Command<Void>	updateDefaultBranch(com.atlassian.bitbucket.repository.Repository repository, com.atlassian.bitbucket.scm.UpdateDefaultBranchCommandParameters parameters) Sets the default branch for the repository to the named branch.

Method Detail

archive

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> archive(@Nonnull
                                                                    com.atlassian.bitbucket.repository.Repository repository,
                                                                    @Nonnull
                                                                    com.atlassian.bitbucket.scm.ArchiveCommandParameters parameters,
                                                                    @Nonnull
                                                                    com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier)

Streams an archive of the repository at the specified commit, in the requested format. If paths are supplied, the streamed archive should be filtered to only include files from the specified paths.

Implementors: This operation is optional. Implementations which do not support streaming archives should return null and omit the ARCHIVE feature. For simplicity, this factory provides a default implementation which returns null. SCMs which implement this command are required to support streaming archives in all of the standard formats. If the underlying SCM does not innately support one or more of the standard formats, the implementation is required to augment the SCM and support them manually. If such augmentation is not possible, the SCM must not implement this command.

Parameters:

repository - the repository to stream the archive from

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 to stream an archive of the repository, or null if archiving is not supported

Since:

5.1

See Also:

ScmFeature.ARCHIVE

editFile

@Nullable
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.commit.Commit> editFile(@Nonnull
                                                                                                      com.atlassian.bitbucket.repository.Repository repository,
                                                                                                      @Nonnull
                                                                                                      com.atlassian.bitbucket.scm.EditFileCommandParameters parameters)

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

Implementors: This feature is optional. Implementations which do not support updating the content of a file should return null and omit the EDIT_FILE feature. For simplicity, this factory provides a default implementation which returns null.

Parameters:

repository - the repository

parameters - parameters describing the file path, file content, branch and the previous contentId of the file.

Returns:

a command to edit a file, or null if editing file is not supported

Since:

4.13

See Also:

ScmFeature.EDIT_FILE

fork

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> fork(@Nonnull
                                                                 com.atlassian.bitbucket.repository.Repository repository,
                                                                 @Nonnull
                                                                 ForkCommandParameters parameters)

Creates a fork of repository, stored in the specified fork. Similar to creating a repository, the specified fork must not exist on disk when this command is called. It is expected that the SCM will create it with contents based on repository, which becomes the fork's origin.

Implementors: This operation is optional. Implementations which do not support forking should return null and omit the FORK feature. For simplicity, this factory provides a default implementation which returns null.

Parameters:

repository - the fork repository

parameters - parameters describing the origin repository to be forked

Returns:

a command to create a fork of a repository, or null if forking is not supported

See Also:

ScmFeature.FORK

lastModified

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> lastModified(@Nonnull
                                                                         com.atlassian.bitbucket.repository.Repository repository,
                                                                         @Nonnull
                                                                         com.atlassian.bitbucket.scm.LastModifiedCommandParameters parameters,
                                                                         @Nonnull
                                                                         com.atlassian.bitbucket.commit.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.

Implementors: This feature is optional. Implementations which do not support updating the default branch should return null and omit the LAST_MODIFIED feature. For simplicity, this factory provides a default implementation which returns null.

Parameters:

repository - the repository containing the starting commit

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 to stream the latest commit to modify each files in the specified path, or null if streaming last modifications is not supported

See Also:

ScmFeature.LAST_MODIFIED

merge

@Nullable
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Branch> merge(@Nonnull
                                                                                                       com.atlassian.bitbucket.repository.Repository repository,
                                                                                                       @Nonnull
                                                                                                       com.atlassian.bitbucket.scm.MergeCommandParameters parameters)

Merges the specified {@link MergeCommandParameters#getFromCommitId() fromCommitId} into the specified {@link MergeCommandParameters#getToBranch() toBranch}.

SCMs are required to support the following values for fromCommitId:

• A 40-byte hash (Note: Short hashes are not supported)
• A fully-qualified branch name
• A short branch name

toBranch, as the parameter name suggests, must be a branch name, either fully qualified or short, and the SCM should validate that that is the case; using a hash (full or short) is not supported.

Implementors: This feature is optional. Implementations which do not support merging should return null and omit the MERGE feature. For simplicity, this factory provides a default implementation which returns null. Additionally, SCMs which support merging are not required to support different source repositories unless they offer cross-repository support. If a different from source repository is provided and cross-repository operations are not supported, implementations should throw an UnsupportedOperationException.

Parameters:

repository - the repository containing both the source commit and the target branch

parameters - parameters describing the branches to merge

Returns:

a command which, when executed, will merge the specified branch into the target branch, or null if merging is not supported

Throws:

UnsupportedOperationException - if a source repository is specified and cross-repository operations are not supported

See Also:

ScmFeature.CROSS_REPOSITORY, ScmFeature.MERGE

patch

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> patch(@Nonnull
                                                                  com.atlassian.bitbucket.repository.Repository repository,
                                                                  @Nonnull
                                                                  com.atlassian.bitbucket.scm.PatchCommandParameters parameters,
                                                                  @Nonnull
                                                                  com.atlassian.bitbucket.io.TypeAwareOutputSupplier outputSupplier)

Streams a patch of the specified repository for a given commit or commit range.

Implementors: This operation is optional. Implementations which do not support streaming patches should return null and omit the PATCH feature. For simplicity, this factory provides a default implementation which returns null.

Parameters:

repository - the repository from which to stream the patch

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

outputSupplier - a supplier which will provide an output stream

Returns:

a command to stream a patch of the repository, or null if not supported

Since:

6.7

See Also:

ScmFeature.PATCH

push

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> push(@Nonnull
                                                                 com.atlassian.bitbucket.repository.Repository repository,
                                                                 @Nonnull
                                                                 com.atlassian.bitbucket.scm.PushCommandParameters parameters,
                                                                 @Nonnull
                                                                 com.atlassian.bitbucket.scm.PushCallback callback)

Pushes the repository to the URL specified in the parameters.

Parameters:

repository - the repository to push

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, or null if not supported

Since:

7.11

See Also:

ScmFeature.PUSH

revert

@Nullable
default com.atlassian.bitbucket.scm.Command<com.atlassian.bitbucket.repository.Branch> revert(@Nonnull
                                                                                                        com.atlassian.bitbucket.repository.Repository repository,
                                                                                                        @Nonnull
                                                                                                        com.atlassian.bitbucket.scm.RevertCommandParameters parameters)

Reverts the specified commit on a given branch as described by the parameters.

Implementors: This feature is optional. Implementations which do not support reverting the commit should return null and omit the REVERT feature. For simplicity, this factory provides a default implementation which returns null.

Parameters:

repository - the repository which contains the commit to be reverted

parameters - describes the commit to be reverted

Returns:

a command which when executed reverts the commit and returns the Branch branch which contains the revert commit

Since:

8.13

See Also:

ScmFeature.REVERT

signedObjects

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> signedObjects(@Nonnull
                                                                          com.atlassian.bitbucket.repository.Repository repository,
                                                                          @Nonnull
                                                                          com.atlassian.bitbucket.scm.signed.SignedObjectsParameters parameters,
                                                                          @Nonnull
                                                                          com.atlassian.bitbucket.scm.signed.SignedObjectCallback callback)

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

Parameters:

repository - the repository containing the requested objects

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 provide them to the provided callback

Throws:

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

Since:

5.1

See Also:

ScmFeature.SIGNED_OBJECTS

updateDefaultBranch

@Nullable
default com.atlassian.bitbucket.scm.Command<Void> updateDefaultBranch(@Nonnull
                                                                                com.atlassian.bitbucket.repository.Repository repository,
                                                                                @Nonnull
                                                                                com.atlassian.bitbucket.scm.UpdateDefaultBranchCommandParameters parameters)

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

Implementors: This feature is optional. Implementations which do not support updating the default branch should return null and omit the UPDATE_DEFAULT_BRANCH feature. For simplicity, this factory provides a default implementation which returns null.

Parameters:

repository - the repository whose default branch should be updated

parameters - parameters describing the new branch to set as the default

Returns:

a command to update the default branch, or null if updating the default branch is not supported

See Also:

ScmFeature.UPDATE_DEFAULT_BRANCH