public interface

ScmService

com.atlassian.stash.scm.ScmService

Class Overview

Describes a service for interacting with an SCM, allowing commands to be created/executed to perform SCM operations.

Summary

Public Methods
@Nonnull ScmCommandBuilder<?> createBuilder(Repository repository)
Creates a ScmCommandBuilder which can be used to construct free-form commands to interact directly with the underlying SCM implementation and perform custom functions on repositories.
@Nonnull Set<AvailableScm> getAvailable()
Retrieves the set of available SCMs.
@Nonnull ScmCommandFactory getCommandFactory(Repository repository)
Retrieves an ScmCommandFactory, used to create commands for performing standard SCM operations such as retrieving commits and viewing diffs.
@Nonnull ScmCompareCommandFactory getCompareCommandFactory(CompareRequest compareRequest)
Retrieves an ScmCompareCommandFactory, used to create commands tailored for comparing refs.
@Nonnull ScmHookHandlerFactory getHookHandlerFactory(Repository repository)
Retrieves a ScmHookHandlerFactory, used to create hook handlers that manage scm hook callbacks.
@Nonnull ScmPullRequestCommandFactory getPullRequestCommandFactory(PullRequest pullRequest)
Retrieves an ScmPullRequestCommandFactory, used to create commands tailored for use operating on pull requests.
@Nonnull ScmRefCommandFactory getRefCommandFactory(Repository repository)
Retrieves an ScmRefCommandFactory, used to create commands tailored for creating branches and tags.
@Nonnull String getScmName(Repository repository)
Retrieves the name for the SCM which powers the specified repository.
boolean isEmpty(Repository repository)
Retrieves a flag indicating whether the specified Repository is empty.
boolean isSupported(Repository repository, ScmFeature feature)
Retrieves a flag indicating whether the SCM for the specified Repository supports the requested feature.

Public Methods

@Nonnull public ScmCommandBuilder<?> createBuilder (Repository repository)

Creates a ScmCommandBuilder which can be used to construct free-form commands to interact directly with the underlying SCM implementation and perform custom functions on repositories.

Command builders are provided as a very powerful extension point for plugin developers, allowing them to create new functionality that uses commands the application does not, or uses them in different ways. However, plugin developers should be aware that:

  • The system may support multiple versions of an SCM, and those versions may support different commands and/or arguments, and even the "same" command may produce different output between versions
  • In a free-form builder, the command and arguments are not checked until the command is run; the system does not, and cannot, validate that the arguments are correct in advance
  • Above all, the system cannot verify the safety of commands being executed; plugin developers must apply due diligence to ensure the operations they perform do not damage the repository

The created ScmCommandBuilder will use the provided repository's directory as its initial working directory. After the builder has been created, it is possible to change the working directory on the instance, before commands are constructed.

Note: Per the contract of the ScmCommandBuilder API, the returned builder is not thread-safe. If multiple threads require use of a builder, each thread should always create its own builder.

Parameters
repository the repository to create a builder for, used to determine the correct SCM implementation to use and to provide the initial working directory for built commands
Returns
  • a new command builder
Throws
FeatureUnsupportedScmException if the target SCM does not support command builders
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled
See Also

@Nonnull public Set<AvailableScm> getAvailable ()

Retrieves the set of available SCMs. SCMs that are installed but not in a good state will not be included in the returned set. The returned set will never be empty; the system requires at least one available SCM or it will be locked out on startup.

Each SCM implementation is different, but examples of reasons why an installed SCM might not be available include:

  • The binary associated with the SCM, such as git or hg, may not be installed
  • The installed binary might be of an unsupported version, too old or too new
  • Another plugin the SCM depends on may not be installed or may be disabled
This list is by no means exhaustive; the individual SCM implementations are free to have their own requirements and dependencies.

Returns
  • the set of available installed SCMs

@Nonnull public ScmCommandFactory getCommandFactory (Repository repository)

Retrieves an ScmCommandFactory, used to create commands for performing standard SCM operations such as retrieving commits and viewing diffs.

Parameters
repository the repository to retrieve a command factory for, used to determine the correct SCM implementation to use and to specify the repository created commands operate on
Returns
  • a command factory which will create commands operating on the specified repository
Throws
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled
See Also

@Nonnull public ScmCompareCommandFactory getCompareCommandFactory (CompareRequest compareRequest)

Retrieves an ScmCompareCommandFactory, used to create commands tailored for comparing refs.

This differs from the normal getCommandFactory(Repository) in that any comparison will be rooted into the closest common ancestor between the refs. In other words, any comparison will be one sided and only includes the changes the source ref would bring to the target ref if they were merged.

Parameters
compareRequest the request describing the refs to compare
Returns
  • a command factory that will create commands allowing to compare two refs using their closest common ancestor
Throws
FeatureUnsupportedScmException if the target SCM does not support comapring refs using their closest common ancestor
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled
See Also

@Nonnull public ScmHookHandlerFactory getHookHandlerFactory (Repository repository)

Retrieves a ScmHookHandlerFactory, used to create hook handlers that manage scm hook callbacks.

SCMs are not required to implement support for SCM hooks.

Parameters
repository the repository for which to retrieve the Scm
Returns

@Nonnull public ScmPullRequestCommandFactory getPullRequestCommandFactory (PullRequest pullRequest)

Retrieves an ScmPullRequestCommandFactory, used to create commands tailored for use operating on pull requests.

SCMs are not required to implement support for pull requests.

Parameters
pullRequest the pull request to retrieve a command factory for, used to determine the correct SCM implementation to use and to specify the pull request created commands operate on
Returns
  • a command factory which will create commands operating on the specified pull request
Throws
FeatureUnsupportedScmException if the target SCM does not support pull requests
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled
See Also

@Nonnull public ScmRefCommandFactory getRefCommandFactory (Repository repository)

Retrieves an ScmRefCommandFactory, used to create commands tailored for creating branches and tags.

SCMs are not required to implement support for creating branches or tags.

Throws
FeatureUnsupportedScmException if the target SCM does not support mutable refs
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled
See Also

@Nonnull public String getScmName (Repository repository)

Retrieves the name for the SCM which powers the specified repository.

Parameters
repository the repository to retrieve the SCM name for
Returns
  • the name of the SCM powering the specified repository
Throws
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled

public boolean isEmpty (Repository repository)

Retrieves a flag indicating whether the specified Repository is empty.

Parameters
repository the repository to check
Returns
  • true if the repository is empty; otherwise, false
Throws
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled

public boolean isSupported (Repository repository, ScmFeature feature)

Retrieves a flag indicating whether the SCM for the specified Repository supports the requested feature.

Parameters
repository the repository to check
feature the feature to test
Returns
  • true if the SCM for the specified repository supports the requested feature; otherwise, false
Throws
UnavailableScmException if the target SCM is installed and enabled but unavailable for some reason
UnsupportedScmException if the target SCM has been uninstalled or disabled