com.atlassian.bitbucket.scm

Interface Scm

All Known Implementing Classes:

AbstractScm

@ThreadSafe
public interface Scm

Describes a pluggable extension point for implementing custom SCMs.

In order for an SCM to be usable by the system, it must implement:

• getCommandFactory()
• getFeatures()
• getId()
• getName()
• getStatus()
• isEmpty(Repository)

It may also implement the following to enable additional system functionality:

• getBulkContentCommandFactory()
• getCompareCommandFactory()
• getExtendedCommandFactory()
• getMirrorCommandFactory()
• getPullRequestCommandFactory()
• getRefCommandFactory()

It may also implement the following to provide extra functionality for other plugin developers:

• getCommandBuilderFactory()

Further details about each of these, and how to implement them correctly, is divided between method documentation and documentation on the interfaces being returned. SCM plugins are complicated to implement, so it is encouraged that developers read the documentation provided thoroughly to ensure they do not violate invariants that allow the system to use its SCMs correctly.

SCMs which support additional functionality, or have custom factory types, are encouraged to provide a sub- interface extending from this one exposing that functionality. For example:

     //Overrides the builder(Repository) method using a covariant return type to return a builder supporting both
     //type-safe and free-form commands, instead of ScmCommandBuilder
     public interface MyScmCommandBuilderFactory extends PluginCommandBuilderFactory {
         //See the documentation for PluginCommandBuilderFactory
     }

     //Overrides methods using covariant return types to return an enhanced CancelableCommands instead of
     //Commands
     public interface MyScmCommandFactory extends PluginCommandFactory {
         //See the documentation for PluginCommandFactory
     }

     //Overrides methods using covariant return types to return custom versions of the PluginCommandFactory,
     //PluginCommandBuilderFactory and PluginPullRequestCommandFactory interfaces
     public interface MyScm extends Scm {
         //Supports both free-form and type-safe builders
          @Nonnull
          @Override
         MyScmCommandBuilderFactory getCommandBuilderFactory();

         //Uses enhanced CancelableCommands
          @Nonnull
          @Override
         MyScmCommandFactory getCommandFactory();

          @Nonnull
          @Override
         MyScmPullRequestCommandFactory getPullRequestCommandFactory();
     }
 

Notice that the getCommandBuilderFactory() and getPullRequestCommandFactory() have had their annotations changed to @Nonnull, indicating that MyScm definitely supports both builders and pull requests. This allows other plugin developers to know the features supported by the custom SCM so they can leverage them fully.

SCM plugins are encouraged to define a separate component for their Scm implementations, but they are required to define an scm entry or the SCM will not be detected by the system. The following example illustrates both directives:

     <!-- Note: These should be in the SCM provider's atlassian-plugin.xml -->
     <component key="myScm" class="com.example.DefaultMyScm" public="true">
         <interface>com.example.MyScm</interface>
     </component>

     <scm key="scm" class="bean:myScm"/>
 

The public="true" allows other plugins to import the component. This approach allows other plugin developers to import the SCM directly 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="myScm" interface="com.example.MyScm"/>
 

For SCMs which define a component for their Scm, it is strongly encouraged that they reference that component for their scm directive, as shown above. This ensures a single instance of the Scm is constructed for use by other plugins and by the system.

Note: Implementors are strongly encouraged to extend from AbstractScm. This interface will change, over time, and any class implementing it directly will be broken by such changes. Extending from the abstract class will help prevent such breakages.

Note: Implementations of this interface are required to be thread-safe. Implementations of related interfaces such as PluginCommandBuilderFactory, PluginCommandFactory and PluginPullRequestCommandFactory are not required to be thread-safe if distinct instances are returned for each call.

Warning: If a component directive is defined but the scm directive does not reference it and instead defines class="com.example.MyScm", two instances will be created. The one created with the component directive may be imported by plugins (assuming it is public; otherwise, it may never be used anywhere!) and the one created with the scm directive will be used by the system.

See Also:

AbstractScm

Method Summary

Modifier and Type	Method and Description
default PluginBulkContentCommandFactory	getBulkContentCommandFactory() Retrieves a PluginBulkContentCommandFactory, used to create commands tailored for getting content from a repository in bulk.
default PluginCommandBuilderFactory	getCommandBuilderFactory() Retrieves a PluginCommandBuilderFactory, used to create command builders for custom SCM commands.
PluginCommandFactory	getCommandFactory() Retrieves a PluginCommandFactory, used to create commands for performing standard SCM operations such as retrieving commits and viewing diffs.
default PluginCompareCommandFactory	getCompareCommandFactory() Retrieves a PluginCompareCommandFactory, used to create commands tailored for comparing refs.
default com.atlassian.bitbucket.repository.MinimalRef	getDefaultBranch(com.atlassian.bitbucket.repository.Repository repository) Retrieves the configured default branch for the specified repository.
default PluginExtendedCommandFactory	getExtendedCommandFactory() Retrieves an optional command factory, which enables additional system features for SCMs which implement its commands.
Set<com.atlassian.bitbucket.scm.ScmFeature>	getFeatures() Retrieves the features that are supported by this SCM.
String	getId() Retrieves a unique identifier for the SCM that is provided by the plugin.
default PluginIntegrityCheckCommandFactory	getIntegrityCheckCommandFactory() Retrieves a PluginIntegrityCheckCommandFactory, used to create commands that perform integrity checks on SCMs.
default PluginMergeStrategies	getMergeStrategies() Retrieves a set of merge strategies supported by the SCM.
default PluginMirrorCommandFactory	getMirrorCommandFactory() Retrieves a PluginMirrorCommandFactory, used to create commands tailored for mirroring repositories.
String	getName() Retrieves a well-known name for the SCM that is provided by the plugin.
default PluginPullRequestCommandFactory	getPullRequestCommandFactory() Retrieves a PluginPullRequestCommandFactory, used to create commands tailored for use supporting pull requests.
default PluginRefCommandFactory	getRefCommandFactory() Retrieves a PluginRefCommandFactory, used to create commands tailored for creating branches and tags.
ScmStatus	getStatus() Retrieves the current status for the SCM.
boolean	isEmpty(com.atlassian.bitbucket.repository.Repository repository) Retrieves a flag indicating whether the specified Repository is empty, from the perspective of the SCM implementation.

Method Detail

getBulkContentCommandFactory

@Nullable
default PluginBulkContentCommandFactory getBulkContentCommandFactory()

Retrieves a PluginBulkContentCommandFactory, used to create commands tailored for getting content from a repository in bulk.

Implementation Note: This method is optional. SCMs which do not support bulk content retrieval may return null.

Returns:

a command factory which will create commands operating on the specified repository, or null if the SCM does not support bulk content retrieval

Since:

4.2

See Also:

PluginBulkContentCommandFactory, ScmFeature.BULK_CONTENT

getCommandBuilderFactory

@Nullable
default PluginCommandBuilderFactory getCommandBuilderFactory()

Retrieves a PluginCommandBuilderFactory, used to create command builders for custom SCM commands.

Implementation Note: This method is optional. SCMs which do not support a ScmCommandBuilder may return null.

Returns:

a command builder factory, or null if the SCM does not support command builders

See Also:

PluginCommandBuilderFactory, ScmFeature.COMMAND_BUILDERS

getCommandFactory

@Nonnull
PluginCommandFactory getCommandFactory()

Retrieves a PluginCommandFactory, used to create commands for performing standard SCM operations such as retrieving commits and viewing diffs. The commands created by the returned factory are used to support normal system functionality; as a result, SCMs are required to provide an implementation.

Implementation Note: This method is required and may not return null.

Returns:

a command factory, providing access to required SCM functionality

See Also:

PluginCommandFactory

getCompareCommandFactory

@Nullable
default PluginCompareCommandFactory getCompareCommandFactory()

Retrieves a PluginCompareCommandFactory, used to create commands tailored for comparing refs.

Implementation Note: This method is optional. SCMs which do not support comparing refs may return null.

Returns:

a compare command factory, or null if the SCM does not support it

See Also:

PluginCompareCommandFactory, ScmFeature.COMPARE

getDefaultBranch

@Nonnull
default com.atlassian.bitbucket.repository.MinimalRef getDefaultBranch(@Nonnull
                                                                                com.atlassian.bitbucket.repository.Repository repository)

Retrieves the configured default branch for the specified repository.

Each repository in an SCM is required to have a default branch. However, that branch is not actually required to exist within the repository. Regardless of whether the branch exists within the repository or not, this method should return the configured default. If the default branch exists, SCMs may optionally return a full Branch instead of a MinimalRef.

Implementors: The default implementation of this method will be removed in 9.0. SCMs are required to implement this accessor for themselves; they cannot rely on the default.

Parameters:

repository - the repository to retrieve the configured default branch for

Returns:

the configured default branch, which may not exist

Since:

7.5

See Also:

PluginCommandFactory.defaultBranch(Repository)

getExtendedCommandFactory

@Nullable
default PluginExtendedCommandFactory getExtendedCommandFactory()

Retrieves an optional command factory, which enables additional system features for SCMs which implement its commands. Each optional command is associated with an SCM feature, and SCMs are free to implement any subset of the factory's methods. If the SCM does not implement any optional features, the returned factory may be null. However, SCM implementors are encouraged to implement as many optional commands as they can.

Returns:

a command factory providing optional, extended functionality for this SCM, or null if the SCM does not support any optional commands

Since:

4.6

getFeatures

@Nonnull
Set<com.atlassian.bitbucket.scm.ScmFeature> getFeatures()

Retrieves the features that are supported by this SCM.

Since the system relies on optional features to provide some functionality, like branch compare and pull requests, it relies on this set to disable functionality that requires features the SCM doesn't provide. Similarly, plugin developers can use the returned features to control which optional features they try to use, rather than checking for null or handling UnsupportedOperationExceptions.

Returns:

the set of optional features this SCM supports, which may be empty but never null

getIntegrityCheckCommandFactory

@Nullable
default PluginIntegrityCheckCommandFactory getIntegrityCheckCommandFactory()

Retrieves a PluginIntegrityCheckCommandFactory, used to create commands that perform integrity checks on SCMs.

Returns:

a integrity check command factory, or null if the SCM does not support integrity checks.

Since:

4.12

getId

@Nonnull
String getId()

Retrieves a unique identifier for the SCM that is provided by the plugin.

Identifiers should be unique to the SCM's type. Using the name of the SCM's binary is a good approach. For example, a plugin implementing support for git might return "git" as its identifier. This approach allows the system to detect when multiple plugins are installed which implement git support, potentially leading to unexpected behaviour from some repositories.

Implementation Note: This method is required and may not return null.

Returns:

a unique identifier for the SCM, preferably based on its binary

getMergeStrategies

@Nullable
default PluginMergeStrategies getMergeStrategies()

Retrieves a set of merge strategies supported by the SCM.

If the SCM supports pull requests and selectable merge strategies, the system will use the returned strategies to allow administrators to configure the default and enabled strategies for the "Merge" dialog.

SCMs which support selectable merge strategies are required to return at least one PluginMergeStrategy. SCMs which support multiple merge strategies must support the same set of strategies for merge commands and pull requests. SCMs must not support different strategies for merge commands and pull requests.

Implementation Notes: This method is optional. SCMs which do not support selectable merge strategies, or which don't support the merge command or pull requests, may return null.

Returns:

the merge strategies supported by this SCM, or null if the SCM doesn't support selectable strategies

Since:

4.9

See Also:

ScmFeature.MERGE_STRATEGIES

getMirrorCommandFactory

@Nullable
default PluginMirrorCommandFactory getMirrorCommandFactory()

Retrieves a PluginMirrorCommandFactory, used to create commands tailored for mirroring repositories.

Implementation Note: This method is optional. SCMs which do not support mirroring may return null. Repositories using such SCMs will not be able to mirror repositories.

Returns:

a command factory which will create commands used to mirror repositories, or null if the SCM does not support mirroring

Since:

4.1

See Also:

PluginMirrorCommandFactory, ScmFeature.MIRRORS

getName

@Nonnull
String getName()

Retrieves a well-known name for the SCM that is provided by the plugin.

Most SCMs use binaries which do not match the well-known name of the SCM. For example, Subversion's binary is svn, and Mercurial's is hg. This method should return the SCM's well-known name, suitable for display in a user interface.

Implementation Note: This method is required and may not return null.

Returns:

the SCM's well-known name

getPullRequestCommandFactory

@Nullable
default PluginPullRequestCommandFactory getPullRequestCommandFactory()

Retrieves a PluginPullRequestCommandFactory, used to create commands tailored for use supporting pull requests. Repositories using an SCM which implements this method will have the ability to create, view and merge pull requests.

Implementation Note: This method is optional. SCMs which do not support pull requests may return null. Repositories using such SCMs will not be able to create pull requests.

Returns:

a pull request command factory, or null if the SCM does not support pull requests

See Also:

PluginPullRequestCommandFactory, ScmFeature.PULL_REQUESTS

getRefCommandFactory

@Nullable
default PluginRefCommandFactory getRefCommandFactory()

Retrieves a PluginRefCommandFactory, used to create commands tailored for creating branches and tags.

Implementation Note: This method is optional. SCMs which do not support mutable refs may return null. Repositories using such SCMs will not be able create branches and tags.

Returns:

a plugin ref command factory

See Also:

ScmFeature.REFS

getStatus

@Nonnull
ScmStatus getStatus()

Retrieves the current status for the SCM.

Available SCMs are expected to be able to process requests. However, there may be situations in which an SCM is unavailable. For example, if the plugin relies on a binary, or common library, which is not installed on the host system, the SCM may be unavailable. When an SCM is unavailable, a message explaining the reason must be provided on the returned ScmStatus.

An SCM's status may be capable of changing over time. However, where possible, it is best for SCMs to determine their status up front. An ScmStatusChangedEvent should be raised if an SCM's status changes at runtime, but is not required. However, the system may not detect the change to the SCM's status if it does not raise an event.

Implementation Note: This method is required and may not return null.

Returns:

the current status of the SCM

See Also:

ScmStatus

isEmpty

boolean isEmpty(@Nonnull
                com.atlassian.bitbucket.repository.Repository repository)

Retrieves a flag indicating whether the specified Repository is empty, from the perspective of the SCM implementation. Potential criteria for determining whether a repository is empty include:

• Whether it has branches
• Whether it has tags
• Whether it has commits

The contract for Scm.isEmpty(Repository) only mandates that a newly-created repository must be considered empty.

How to determine whether a repository is "empty" depends on the SCM, as most SCMs create housekeeping files in their repositories to allow them to manage state. As a result, the system cannot simply test for the absence of any files. Instead, it calls this method to allow the SCM to perform the test.

Implementation Note: This method is required.

Parameters:

repository - the repository to check

Returns:

true if the repository is empty; otherwise, false