com.atlassian.bitbucket.scm

Interface ScmService

public interface ScmService

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

Method Summary

Modifier and Type	Method and Description
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.
Set<AvailableScm>	getAvailable() Retrieves the set of available SCMs.
ScmBulkContentCommandFactory	getBulkContentCommandFactory(Repository repository) Retrieves an ScmBulkContentCommandFactory, used to create commands for retrieving bulk data from the SCM.
ScmCommandFactory	getCommandFactory(Repository repository) Retrieves an ScmCommandFactory, used to create commands for performing standard SCM operations such as retrieving commits and viewing diffs.
ScmCompareCommandFactory	getCompareCommandFactory(CompareRequest compareRequest) Retrieves an ScmCompareCommandFactory, used to create commands tailored for comparing refs.
ScmExtendedCommandFactory	getExtendedCommandFactory(Repository repository) Retrieves an ScmExtendedCommandFactory, used to create commands for extended SCM functionality.
ScmHookHandlerFactory	getHookHandlerFactory(Repository repository) Retrieves a ScmHookHandlerFactory, used to create hook handlers that manage scm hook callbacks.
ScmMirrorCommandFactory	getMirrorCommandFactory(Repository repository) Retrieves an ScmMirrorCommandFactory, used to create commands tailored for mirroring repositories.
ScmPullRequestCommandFactory	getPullRequestCommandFactory(PullRequest pullRequest) Retrieves an ScmPullRequestCommandFactory, used to create commands tailored for use operating on pull requests.
ScmRefCommandFactory	getRefCommandFactory(Repository repository) Retrieves an ScmRefCommandFactory, used to create commands tailored for creating branches and tags.
String	getScmName(Repository repository) Retrieves the name for the SCM which powers the specified repository.
long	getSize(Repository repository) Calculates the size (in bytes) for the specified repository.
boolean	isEmpty(Repository repository) Tests whether the specified Repository is empty.
boolean	isSupported(Repository repository, ScmFeature feature) Tests whether the SCM for the specified Repository supports the requested feature.
boolean	isSupported(String scmId, ScmFeature feature) Tests whether the specified SCM supports the requested feature.

Method Detail

createBuilder

@Nonnull
ScmCommandBuilder<?> createBuilder(@Nonnull
                                            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:

ScmCommandBuilder

getAvailable

@Nonnull
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

getBulkContentCommandFactory

@Nonnull
ScmBulkContentCommandFactory getBulkContentCommandFactory(@Nonnull
                                                                   Repository repository)

Retrieves an ScmBulkContentCommandFactory, used to create commands for retrieving bulk data from the SCM.

SCMs are not required to implement support for bulk commands. However, an SCM which does support them may be capable of significantly increased efficiency when performing large operations.

Note: Since 5.8, this method will no longer throw FeatureUnsupportedScmException. Instead, an exception will be thrown when trying to create a specific command, if the SCM doesn't support it. Prior to 5.8, since ScmBulkContentCommandFactory only supported a single command, the associated feature could be eagerly checked when retrieving the factory. Now that it offers multiple commands, features must be checked when commands are requested instead.

Parameters:

repository - the repository to retrieve a command factory for, used to determine the correct SCM implementation to use

Returns:

a command factory providing bulk SCM functionality

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

Since:

4.2

See Also:

ScmBulkContentCommandFactory

getCommandFactory

@Nonnull
ScmCommandFactory getCommandFactory(@Nonnull
                                             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:

ScmCommandFactory

getCompareCommandFactory

@Nonnull
ScmCompareCommandFactory getCompareCommandFactory(@Nonnull
                                                           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:

ScmCommandFactory, ScmPullRequestCommandFactory

getExtendedCommandFactory

@Nonnull
ScmExtendedCommandFactory getExtendedCommandFactory(@Nonnull
                                                             Repository repository)

Retrieves an ScmExtendedCommandFactory, used to create commands for extended SCM functionality.

SCMs are not required to implement support for any of the commands on this factory, and implementing support for any one command does not require supporting any other command. Attempting to use a command which has not been implemented by the SCM will trigger a FeatureUnsupportedScmException. Callers should check support prior to using any command on this factory. Each command is associated with its own feature. The mapping between features and commands is documented on the ScmExtendedCommandFactory interface.

Note: Unlike other command factories, like the pull request command factory, calling this method will never throw a FeatureUnsupportedScmException. Feature support is checked against each method on the returned factory, not against retrieving the factory itself.

Parameters:

repository - the repository to retrieve a command factory for, used to determine the correct SCM implementation to use

Returns:

a command factory providing optional SCM functionality

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

Since:

4.6

See Also:

ScmExtendedCommandFactory

getHookHandlerFactory

@Nonnull
ScmHookHandlerFactory getHookHandlerFactory(@Nonnull
                                                     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:

the ScmHookHandlerFactory used to create hook handlers

getMirrorCommandFactory

@Nonnull
ScmMirrorCommandFactory getMirrorCommandFactory(@Nonnull
                                                         Repository repository)

Retrieves an ScmMirrorCommandFactory, used to create commands tailored for mirroring repositories.

SCMs are not required to implement support for mirroring.

Parameters:

repository - the repository to retrieve a command factory for, used to determine the correct SCM implementation to use

Returns:

a command factory which will create commands operating on the specified repository

Throws:

FeatureUnsupportedScmException - if the target SCM does not support mirroring

UnavailableScmException - if the target SCM is installed and enabled but unavailable for some reason

UnsupportedScmException - if the target SCM has been uninstalled or disabled

Since:

4.1

See Also:

ScmMirrorCommandFactory

getPullRequestCommandFactory

@Nonnull
ScmPullRequestCommandFactory getPullRequestCommandFactory(@Nonnull
                                                                   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:

ScmPullRequestCommandFactory

getRefCommandFactory

@Nonnull
ScmRefCommandFactory getRefCommandFactory(@Nonnull
                                                   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.

Parameters:

repository - repository to get refs for

Returns:

a command factory which will create commands operating on the specified repository

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:

ScmFeature.REFS

getScmName

@Nonnull
String getScmName(@Nonnull
                           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

getSize

long getSize(@Nonnull
             Repository repository)

Calculates the size (in bytes) for the specified repository. If the provided Repository does not exist, its size is always 0.

Note: Calculating the size can be an expensive operation. The returned value may be a best effort estimation of the repository size.

Parameters:

repository - the repository whose size should be calculated

Returns:

the size of the specified repository in bytes

isEmpty

boolean isEmpty(@Nonnull
                Repository repository)

Tests 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

isSupported

boolean isSupported(@Nonnull
                    Repository repository,
                    @Nonnull
                    ScmFeature feature)

Tests 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

isSupported

boolean isSupported(@Nonnull
                    String scmId,
                    @Nonnull
                    ScmFeature feature)

Tests whether the specified SCM supports the requested feature.

Parameters:

scmId - identifier of the SCM 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