Atlassian Stash SPI
| com.atlassian.stash.scm.PluginCommandFactory |
 Known Indirect Subclasses
|
Provides backing functionality for the ScmCommandFactory.
This interface is intended to be implemented by plugin developers. Functionality provided by this interface is intended to be consumed using the ScmCommandFactory exposed by the ScmService. Only the system should ever deal with this interface directly. All command types on this interface are required to have a working implementation, as this factory describes the basic SCM commands used by the system to provide day-to-day functionality, unless documented otherwise. The following commands are optional:fork (ScmFeature#FORK)merge (ScmFeature#MERGE)updateDefaultBranch (ScmFeature#UPDATE_DEFAULT_BRANCH)fork which has its own ScmFeature#FORK feature, SCMs which do not support cross-repository
operations should fail fast, throwing an UnsupportedOperationException rather than returning a
Command; they should not return a command which throws that exception.
SCM implementations may also provide additional functionality to allow the system to offer enhanced
features, such as pull requests. Such functionality is exposed by other interfaces:
PluginCommandBuilderFactoryPluginCompareCommandFactoryPluginHookHandlerFactoryPluginPullRequestCommandFactory
//Extends Command to allow canceling it after it has been called and checking whether it's been canceled.
public interface CancelableCommand<T> extends Command<T> {
void cancel();
boolean isCanceled();
}
//Overrides methods on the PluginCommandFactory interface using covariant return types to return the
//enhanced CancelableCommand instead of simple Command
public interface MyScmCommandFactory extends PluginCommandFactory {
@Nonnull
@Override
CancelableCommand<List<Blame>> blame(@Nonnull Repository repository,
@Nonnull BlameCommandParameters parameters,
@Nonnull PageRequest pageRequest);
//Overrides for other methods as appropriate
}
MyScmCommandFactory using a
component directive:
<!-- Note: This should be in the SCM provider's atlassian-plugin.xml -->
<component key="myScmCommandFactory"
class="com.example.DefaultMyScmCommandFactory"
public="true">
<interface>com.example.MyScmCommandFactory</interface>
</component>
public="true" allows other plugins to import the component. This approach allows other plugin developers
to import the SCM plugin's command factory and leverage its enhanced functionality with a component-import
directive:
<!-- Note: This should be in the SCM consumer's atlassian-plugin.xml -->
<component-import key="myScmCommandFactory"
interface="com.example.MyScmCommandFactory"/>
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common term
for the data they represent. Owing to Java generics, there is no backward compatible way that change
can be applied here. Based on that, this method signature will be changed in 4.0, to return a
Command<Commit>. It will not be possible for an SCM to be compatible with both 3.x and
4.x due to this change.
| |||||||||||
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common term
for the data they represent. Owing to Java generics, there is no backward compatible way that change
can be applied here. Based on that, this method signature will be changed in 4.0, to return a
Command<Page<Commit>>. It will not be possible for an SCM to be compatible with
both 3.x and 4.x due to this change.
| |||||||||||
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common term
for the data they represent. This method will be replaced by
commits(Repository, CommitsCommandParameters, CommitCallback) in 4.0.
| |||||||||||
Creates and initializes the repository on disk, performing any SCM-specific configuration that is appropriate
for new repositories.
| |||||||||||
Deletes the repository, allowing the underlying SCM to carry out any special processing necessary to clean up
repository storage.
| |||||||||||
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common
term for the data they represent, allowing DetailedChangeset to be renamed to what it is:
com.atlassian.stash.commit.Changeset Changeset. This method will be replaced by
changesets(Repository, ChangesetsCommandParameters, PageRequest)
in 4.0.
| |||||||||||
Creates a fork of
repository, stored in fork. | |||||||||||
Merges the specified
fromChangesetId into the specified toBranch. | |||||||||||
Streams all of the commits in the repository in topological order.
| |||||||||||
Set the default branch for the specified repository to the named branch.
| |||||||||||
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common term
for the data they represent. Owing to Java generics, there is no backward compatible way that change
can be applied here. Based on that, this method signature will be changed in 4.0, to return a
Command<Commit>. It will not be possible for an SCM to be compatible with both 3.x and
4.x due to this change.
| repository | the repository to retrieve the commit from |
|---|---|
| parameters | parameters describing the commit to retrieve |
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common term
for the data they represent. Owing to Java generics, there is no backward compatible way that change
can be applied here. Based on that, this method signature will be changed in 4.0, to return a
Command<Page<Commit>>. It will not be possible for an SCM to be compatible with
both 3.x and 4.x due to this change.
Retrieves a page of commits which match the provided CommitsCommandParameters paramters.
Implementors: SCMs are required to support this operation. However, they are not required to support CommitsCommandParameters#getSecondaryRepository() secondary repositories unless they offer ScmFeature#CROSS_REPOSITORY cross-repository support. If a secondary repository is provided and cross- repository operations are not supported, implementations should throw anUnsupportedOperationException.| repository | the repository to retrieve commits from |
|---|---|
| parameters | parameters describing the commits to retrieve |
| pageRequest | describes the page of commits to retrieve |
| UnsupportedOperationException | if a CommitsCommandParameters#getSecondaryRepository() secondary repository is provided an ScmFeature#CROSS_REPOSITORY cross- repository operations are not supported |
|---|
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common term
for the data they represent. This method will be replaced by
commits(Repository, CommitsCommandParameters, CommitCallback) in 4.0.
Streams commits which match the provided CommitsCommandParameters paramters to the provided callback.
Implementors: SCMs are required to support this operation. However, they are not required to support CommitsCommandParameters#getSecondaryRepository() secondary repositories unless they offer ScmFeature#CROSS_REPOSITORY cross-repository support. If a secondary repository is provided and cross- repository operations are not supported, implementations should throw anUnsupportedOperationException.| repository | the repository to retrieve commits from |
|---|---|
| parameters | parameters describing the commits to retrieve |
| callback | a callback to receive the streamed commits |
| UnsupportedOperationException | if a CommitsCommandParameters#getSecondaryRepository() secondary repository is provided an ScmFeature#CROSS_REPOSITORY cross- repository operations are not supported |
|---|
Creates and initializes the repository on disk, performing any SCM-specific configuration that is appropriate
for new repositories. repository does not exist on disk when this method is called. It is expected that
the SCM will create it with contents that are appropriate for an empty new repository.
| repository | the repository to create |
|---|
Deletes the repository, allowing the underlying SCM to carry out any special processing necessary to clean up repository storage.
Note: By the time this method is called, the repository has already been deleted from the database, and the associated database transaction has been committed. Warning: This method is irreversible. It should never be called by a plugin. It is intended solely for use by the system.| repository | the repository to delete |
|---|---|
| parameters | additional parameters, such as IDs for forks of the deleted repository |
This method is deprecated.
in 3.7 for removal in 4.0. All things "changeset" are being renamed to "commit", the more common
term for the data they represent, allowing DetailedChangeset to be renamed to what it is:
com.atlassian.stash.commit.Changeset Changeset. This method will be replaced by
changesets(Repository, ChangesetsCommandParameters, PageRequest)
in 4.0.
| repository | the repository to retreive the changesets from |
|---|---|
| parameters | parameters describing the changesets to retrieve |
| pageRequest | describes the page of changesets to retrieve |
Creates a fork of repository, stored in fork. Similar to creating
a repository, fork does not exist on disk when this method is called. It is expected that the SCM will
create it with contents based on repository, which becomes its origin.
UnsupportedOperationException and omit the ScmFeature#FORK FORK feature.| repository | the repository to be forked |
|---|---|
| fork | the fork |
| UnsupportedOperationException | if forking is not a supported feature |
|---|
Merges the specified fromChangesetId into the specified toBranch.
fromChangesetId:
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 throw an
UnsupportedOperationException and omit the ScmFeature#MERGE MERGE feature. Additionally, SCMs
which support merging are not required to support MergeCommandParameters#getFromRepository() different
source repositories unless they offer ScmFeature#CROSS_REPOSITORY cross-repository support. If a
different from source repository is provided and cross-repository operations are not supported, implementations
should throw an UnsupportedOperationException.| repository | the repository containing both the source changeset and the target branch |
|---|
| UnsupportedOperationException | if a MergeCommandParameters#getFromRepository() source repository is specified and ScmFeature#CROSS_REPOSITORY cross-repository operations are not supported |
|---|
Streams all of the commits in the repository in topological order. Topological order means no parent is output before all of its descendants have been output. It does not require that descendants be streamed in date order, but SCMs may optionally do so (so long as topological order is retained).
| repository | the repository to traverse commits for |
|---|---|
| callback | the callback to receive the streamed commits |
Set the default branch for the specified repository to the named branch.
Implementors: This feature is optional. Implementations which do not support updating the default branch should throw anUnsupportedOperationException and omit the ScmFeature#UPDATE_DEFAULT_BRANCH
UPDATE_DEFAULT_BRANCH feature.| repository | the repository whose default branch should be updated |
|---|---|
| branchName | the branch to make the default |
| IllegalArgumentException | if the provided branchName is null or blank. |
|---|---|
| UnsupportedOperationException | if the underlying SCM does not support setting the default branch. |