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

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

revert(RevertCommandParameters parameters)

Reverts the specified commit on a given branch as described by 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 Details
- 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
- revert
  
  @Nonnull Command<Branch> revert(@Nonnull RevertCommandParameters parameters)
  
  Reverts the specified commit on a given branch as described by 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 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
  
  @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

Interface ScmExtendedCommandFactory

Method Summary

Method Details

archive

editFile

lastModified

merge

patch

push

revert

signedObjects

updateDefaultBranch