Package 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 Details

    • 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:

    • 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 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

    • 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