Package com.atlassian.bitbucket.repository

Interface RepositoryService

All Superinterfaces:
RepositorySupplier
public interface RepositoryService extends RepositorySupplier
Describes a service for interacting with repositories.

  • Method Details

    • countByProject

      int countByProject(@Nonnull Project project)
      Get the number of repositories that belong to a project.
      Parameters:
      project - the project
      Returns:
      the number of repositories in the project.

    • create

      @Nonnull Repository create(@Nonnull RepositoryCreateRequest request)
      Create a new repository. The repository's slug will be derived from the name. Both the name and the generated slug must be unique within the project.

      Before the repository is created, a creation requested event is raised. This event is cancelable, allowing plugins to prevent repository creation based on arbitrary considerations. If any listener cancels creation, the repository will not be created. It does not require consensus among all registered listeners. If no listeners cancel, the repository will be created.

      Events raised:

      Parameters:
      request - describes the repository to create
      Returns:
      the new repository
      Throws:
      RepositoryCreationCanceledException - if creation is canceled by an event listener

    • delete

      void delete(@Nonnull Repository repository)
      Delete the repository. Both the on-disk repository and the database record are deleted. Any child and parent relationships are updated. The repository will be scheduled for deletion, which may happen after this call completes.

      Before the repository is deleted, a deletion requested event is raised. This event is cancelable, allowing plugins to prevent repository deletion based on arbitrary considerations. If any listener cancels deletion, the repository will not be deleted. It does not require consensus among all registered listeners. If no listeners cancel, the repository will be deleted.

      Events raised:

      Parameters:
      repository - the repository to be deleted.
      Throws:
      RepositoryDeletionCanceledException - if deletion is canceled by an event listener
      AuthorisationException - if the user does not have sufficient permission to delete a repository (as specified by the instance repository delete policy)

    • findAll

      @Nonnull Page<Repository> findAll(@Nonnull PageRequest pageRequest)
      Find all repositories in the system in the default namespace.
      Parameters:
      pageRequest - the page of repositories to return.
      Returns:
      a page of repositories.

    • findByOrigin

      @Nonnull Page<Repository> findByOrigin(@Nonnull Repository origin, @Nonnull PageRequest pageRequest)
      Retrieves a page of repositories which have been forked from the specified origin.

      The returned list is not guaranteed to be complete; it will be filtered to contain only those repositories which the requesting user has access to. This may not include forks in other users' personal projects, for example.

      Parameters:
      origin - the origin repository for which forks should be found
      pageRequest - the bounds of the page
      Returns:
      a page containing zero or more forks for the specified origin

    • findByOwner

      @Nonnull Page<Repository> findByOwner(@Nonnull ApplicationUser owner, @Nonnull PageRequest pageRequest)
      Retrieves a page of repositories owned by the specified user. These are personal repositories, which may be personal forks of other repositories or the user's own repositories.

      Only repositories visible to the current user will be returned, which may not be the full set of repositories owned by the specified user.

      Parameters:
      owner - the user to retrieve personal repositories for
      pageRequest - the bounds of the page
      Returns:
      a page containing zero or more personal repositories for the specified user

    • findByProjectId

      @Nonnull Page<Repository> findByProjectId(int projectId, @Nonnull PageRequest pageRequest) throws NoSuchProjectException
      Retrieves a page of repositories in the project with the given id.
      Parameters:
      projectId - the ID of the project for which to list the repositories
      pageRequest - the page parameters for this query
      Returns:
      the request page of repositories within the specified project, which may be empty but never null
      Throws:
      NoSuchProjectException - if the specified project does not exist
      Since:
      5.7

    • findByProjectKey

      @Nonnull Page<Repository> findByProjectKey(@Nonnull String projectKey, @Nonnull PageRequest pageRequest) throws NoSuchProjectException
      List the names of the repositories in the project with the given key and with a default (null) namespace.
      Parameters:
      projectKey - the key of the project for which to list the repositories
      pageRequest - the page parameters for this query
      Returns:
      the request page of repositories within the specified project, which may be empty but never null
      Throws:
      NoSuchProjectException - if the specified project does not exist

    • findPersonalFork

      @Nullable Repository findPersonalFork(@Nonnull Repository repository)
      Retrieves the current user's personal fork of the specified repository. If the current user has not yet forked the repository, or has forked it with a different name, null will be returned.
      Parameters:
      repository - the repository to retrieve the current user's personal fork for
      Returns:
      the current user's personal fork of the specified repository, or null if the current user has not forked the repository or has forked it with a different name

    • findRelated

      @Nonnull Page<Repository> findRelated(@Nonnull Repository repository, @Nonnull PageRequest pageRequest)
      Retrieves a page of repositories which belong to the same hierarchy as the specified repository. The specified repository will never itself be returned, even though it is also part of the hierarchy.

      The related repositories returned are not guaranteed to be the complete hierarchy; they will be filtered to contain only those repositories which the requesting user has access to. This may not include other users' personal forks of the repository, for example.

      Parameters:
      repository - the repository to retrieve related repositories for
      pageRequest - the bounds of the page
      Returns:
      a page containing zero or more repositories from the same hierarchy as the specified repository

    • fork

      @Nonnull Repository fork(@Nonnull RepositoryForkRequest request)
      Create a new repository by forking from an existing repository. As with creating a repository from scratch, the fork's slug will be derived from its name, and both the name and the slug must be unique within the target project.
      • If no explicit project is provided, the fork will be created in the forking user's personal project.
      • If no explicit name is provided, the parent repository's name is retained for the fork.
      Before the fork is created, a fork requested event is raised. This event is cancelable, allowing plugins to prevent fork creation based on arbitrary considerations. If any listener cancels forking, the fork will not be created. It does not require consensus among all registered listeners. If no listeners cancel, the fork will be created.

      Events raised:

      Parameters:
      request - describes the repository to fork, as well as the project in which the fork should be created and the name that should be assigned to it
      Returns:
      the newly-forked repository
      Throws:
      RepositoryForkCanceledException - if forking is canceled by an event listener
      FeatureUnsupportedScmException - if the SCM for the parent repository does not support forking
      javax.validation.ConstraintViolationException - if the fork's slug matches another repository within the user's personal project

    • getById

      @Nullable Repository getById(int id)
      Retrieves a Repository by its ID.
      Specified by:
      getById in interface RepositorySupplier
      Parameters:
      id - the repository's ID
      Returns:
      the request repository, or null if there is no repository with the specified ID
      Throws:
      AuthorisationException - if the current user does not have permission to access the requested repository

    • getBySlug

      @Nullable Repository getBySlug(@Nonnull String projectKey, @Nonnull String slug)
      Retrieves a Repository by its slug. Slugs are only unique within a given Project, so the project key is also required.
      Specified by:
      getBySlug in interface RepositorySupplier
      Parameters:
      projectKey - the key of the project to search in
      slug - the slug of the repository to search for
      Returns:
      the repository, or null if no repository matches the specified slug within the specified project
      Throws:
      AuthorisationException - if the current user does not have permission to access the requested repository

    • getCloneLinks

      @Nonnull Set<NamedLink> getCloneLinks(@Nonnull RepositoryCloneLinksRequest request)
      Retrieves links that can be used to clone the supplied repository via the repository's SCM's supported protocols.

      Where appropriate to the underlying SCM type, SCM protocols may return link URLs that are customised to the supplied user or the currently authenticated user (if any). This might be achieved, for instance, by inserting the user's name in the URL's authority part. Whether and how this customisation takes place is entirely up to each protocol.

      Each link has a name that indicates the protocol it supports e.g. "ssh" or "http".

      Parameters:
      request - the request used to generate clone links
      Returns:
      the set of clone links for the supplied repository
      Throws:
      AuthorisationException - if the current user does not have permission to access the requested repository

    • getDefaultBranch

      @Nullable String getDefaultBranch()
      Retrieves the configured global default branch. When new repositories are created, this will be used as the default branch unless the creator specifies their own. If no global default is configured, the SCM's default will be used.

      Note: SCMs may change their default branch between versions, so relying on their default may produce inconsistent results over time.

      Returns:
      the configured default branch, which will be used by default when creating new repositories, or null if no default has been configured
      Since:
      7.5
      See Also:

    • getDefaultBranch

      @Nonnull MinimalRef getDefaultBranch(@Nonnull Repository repository)
      Retrieves the configured default branch for the specified repository.

      This method differs from RefService.getDefaultBranch(com.atlassian.bitbucket.repository.Repository) in that, where that method will throw an exception if the configured default branch does not exist (i.e. is not a ref in the repository pointing to some commit), this method will not. Every repository has a configured default branch, even if no ref exists with the configured name.

      Parameters:
      repository - the repository to retrieve the configured default branch for
      Returns:
      the configured default branch for the specified repository, which may not exist
      Since:
      7.5
      See Also:

    • 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)
      Retrieves a flag indicating whether the specified repository is empty or not. While the definition of "empty" is SCM-specific, it generally distills to a repository which contains no branches or tags.
      Parameters:
      repository - the repository to check
      Returns:
      true if the repository is empty; otherwise false

    • isForkingEnabled

      boolean isForkingEnabled()
      Retrieves a flag indicating whether the system has been configured to allow forking repositories.

      In addition to this system-wide setting, each Repository may be explicitly configured as Repository.isForkable() or not. If forking is disabled system-wide, even repositories configured as forkable cannot be forked. By the same token, even if forking is enabled system-wide, any repository which is explicitly configured to disallow forks cannot be forked.

      Returns:
      true if the system is configured to allow repository forking; otherwise, false
      See Also:

    • retryCreate

      @Nonnull Repository retryCreate(@Nonnull Repository repository)
      If a create operation fails, calling this method will clean up the broken repository and try again.

      The repository must be in INITIALISATION_FAILED state in order to retry creation.

      Parameters:
      repository - the repository to retry
      Returns:
      the new repository
      Throws:
      IllegalRepositoryStateException - if the repository is not in the required state

    • search

      @Nonnull Page<Repository> search(@Nonnull RepositorySearchRequest request, @Nonnull PageRequest pageRequest)
      Searches for repositories that match the provided request.
      Parameters:
      request - a request object describing the repositories to return
      pageRequest - the bounds of the page
      Returns:
      a page containing 0 or more repositories that match the provided criteria
      See Also:

    • setDefaultBranch

      void setDefaultBranch(@Nullable String defaultBranch)
      Sets the global default branch to use when creating new repositories.
      Parameters:
      defaultBranch - the new default branch name to use when creating repositories, which may be null to clear a previously-set default
      Since:
      7.5
      See Also:

    • setReadOnly

      @Nonnull Repository setReadOnly(@Nonnull Repository repository, boolean readOnly)
      Enable/disable read-only mode for the given repository.

      Note: If a repository is archived, its read-only state cannot be cleared. It must first be unarchived, and then it can be restored to read/write access.

      Parameters:
      repository - the repository to enable/disable read-only mode on
      readOnly - true to enable read-only mode; false to disable
      Throws:
      RepositoryArchivedException - if attempting to clear read-only from an archived repository
      Since:
      8.0

    • update

      @Nonnull Repository update(@Nonnull RepositoryUpdateRequest request)
      Update the metadata of a repository. The possible updates are described in detail by the the RepositoryUpdateRequest documentation.

      Repository slugs are derived from their names. Updating a repository's name may change its slug, which will also change all browser and clone URLs for the affected repository. Old URLs will no longer work after such an update.

      Before the repository is updated, a modification requested event is raised. This event is cancelable, allowing plugins to prevent repository modification based on arbitrary considerations. If any listener cancels modification, the repository will not be updated. It does not require consensus among all registered listeners. If no listeners cancel, the repository will be updated with the provided name.

      Events raised:

      Parameters:
      request - describes the repository to update and the updates to apply
      Returns:
      the updated repository instance
      Throws:
      ArchiveRepositoryFailedException - if repository archiving or unarchiving failed
      ForbiddenException - if the authenticated user does not have appropriate permissions
      NoSuchEntityException - if the repository does not exist
      RepositoryArchivedException - if the repository is archived
      RepositoryModificationCanceledException - if modification is canceled by an event listener