Package 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
    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 Details

    • 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:
      com.atlassian.bitbucket.scm.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