public interface

RepositoryService

implements RepositorySupplier
com.atlassian.bitbucket.repository.RepositoryService

Class Overview

Describes a service for interacting with repositories.

Summary

Public Methods
int countByProject(Project project)
Get the number of repositories that belong to a project.
@Nonnull Repository create(RepositoryCreateRequest request)
Create a new repository.
void delete(Repository repository)
Delete the repository.
@Nonnull Page<Repository> findAll(PageRequest pageRequest)
Find all repositories in the system in the default namespace.
@Nonnull Page<Repository> findByOrigin(Repository origin, PageRequest pageRequest)
Retrieves a page of repositories which have been forked from the specified origin.
@Nonnull Page<Repository> findByOwner(ApplicationUser owner, PageRequest pageRequest)
Retrieves a page of repositories owned by the specified user.
@Nonnull Page<Repository> findByProjectId(int projectId, PageRequest pageRequest)
Retrieves a page of repositories in the project with the given id.
@Nonnull Page<Repository> findByProjectKey(String projectKey, PageRequest pageRequest)
List the names of the repositories in the project with the given key and with a default (null) namespace.
@Nonnull Page<Repository> findByProjectKey(String projectNamespace, String projectKey, PageRequest pageRequest)
List the names of the repositories in the project with the given key and namespace.
@Nullable Repository findPersonalFork(Repository repository)
Retrieves the current user's personal fork of the specified repository.
@Nonnull Page<Repository> findRelated(Repository repository, PageRequest pageRequest)
Retrieves a page of repositories which belong to the same hierarchy as the specified repository.
@Nonnull Repository fork(RepositoryForkRequest request)
Create a new repository by forking from an existing repository.
@Nullable Repository getById(int id)
Retrieves a Repository by its ID.
@Nullable Repository getBySlug(String projectKey, String slug)
Retrieves a Repository by its slug.
@Nullable Repository getBySlug(String projectNamespace, String projectKey, String slug)
Retrieves a Repository by its slug.
@Nonnull Set<NamedLink> getCloneLinks(RepositoryCloneLinksRequest request)
Retrieves links that can be used to clone the supplied repository via the repository's SCM's supported protocols.
long getSize(Repository repository)
Calculates the size (in bytes) for the specified repository.
boolean isEmpty(Repository repository)
Retrieves a flag indicating whether the specified repository is empty or not.
boolean isForkingEnabled()
Retrieves a flag indicating whether the system has been configured to allow forking repositories.
@Nonnull Repository retryCreate(Repository repository)
If a create operation fails, calling this method will clean up the broken repository and try again.
@Nonnull Page<Repository> search(RepositorySearchRequest request, PageRequest pageRequest)
Searches for repositories that match the provided request.
@Nonnull Repository update(RepositoryUpdateRequest request)
Update the metadata of a repository.
[Expand]
Inherited Methods
From interface com.atlassian.bitbucket.repository.RepositorySupplier

Public Methods

public int countByProject (Project project)

Get the number of repositories that belong to a project.

Parameters
project the project
Returns
  • the number of repositories in the project.

@Nonnull public Repository create (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

public void delete (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

@Nonnull public Page<Repository> findAll (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.

@Nonnull public Page<Repository> findByOrigin (Repository origin, 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

@Nonnull public Page<Repository> findByOwner (ApplicationUser owner, 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

@Nonnull public Page<Repository> findByProjectId (int projectId, PageRequest pageRequest)

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

@Nonnull public Page<Repository> findByProjectKey (String projectKey, PageRequest pageRequest)

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

@Nonnull public Page<Repository> findByProjectKey (String projectNamespace, String projectKey, PageRequest pageRequest)

List the names of the repositories in the project with the given key and namespace. Unless in mirror mode the namespace specified should always be null.

Parameters
projectNamespace the namespace of the project for which to list the repositories.
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 in the specified namespace

@Nullable public Repository findPersonalFork (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

@Nonnull public Page<Repository> findRelated (Repository repository, 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

@Nonnull public Repository fork (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
ConstraintViolationException if the fork's slug matches another repository within the user's personal project

@Nullable public Repository getById (int id)

Retrieves a Repository by its ID.

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

@Nullable public Repository getBySlug (String projectKey, String slug)

Retrieves a Repository by its slug. Slugs are only unique within a given Project, so the project key is also required.

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

@Nullable public Repository getBySlug (String projectNamespace, String projectKey, String slug)

Retrieves a Repository by its slug. Slugs are only unique within a given Project, so the project key and project namespace are required. Unless in mirror mode the namespace specified should always be null.

Parameters
projectNamespace the namespace of the project to search in
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 and namespace

@Nonnull public Set<NamedLink> getCloneLinks (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

public long getSize (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

public boolean isEmpty (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

public 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 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

@Nonnull public Repository retryCreate (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

@Nonnull public Page<Repository> search (RepositorySearchRequest request, 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
See Also

@Nonnull public Repository update (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
RepositoryModificationCanceledException if modification is canceled by an event listener