com.atlassian.bitbucket.repository

Interface RepositoryService

All Superinterfaces:

RepositorySupplier

public interface RepositoryService
extends RepositorySupplier

Describes a service for interacting with repositories.

Method Summary

Modifier and Type	Method and Description
int	countByProject(Project project) Get the number of repositories that belong to a project.
Repository	create(RepositoryCreateRequest request) Create a new repository.
void	delete(Repository repository) Delete the repository.
Page<Repository>	findAll(PageRequest pageRequest) Find all repositories in the system in the default namespace.
Page<Repository>	findByOrigin(Repository origin, PageRequest pageRequest) Retrieves a page of repositories which have been forked from the specified origin.
Page<Repository>	findByOwner(ApplicationUser owner, PageRequest pageRequest) Retrieves a page of repositories owned by the specified user.
Page<Repository>	findByProjectId(int projectId, PageRequest pageRequest) Retrieves a page of repositories in the project with the given id.
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.
Page<Repository>	findByProjectKey(String projectNamespace, String projectKey, PageRequest pageRequest) List the names of the repositories in the project with the given key and namespace.
Repository	findPersonalFork(Repository repository) Retrieves the current user's personal fork of the specified repository.
Page<Repository>	findRelated(Repository repository, PageRequest pageRequest) Retrieves a page of repositories which belong to the same hierarchy as the specified repository.
Repository	fork(RepositoryForkRequest request) Create a new repository by forking from an existing repository.
Repository	getById(int id) Retrieves a Repository by its ID.
Repository	getBySlug(String projectKey, String slug) Retrieves a Repository by its slug.
Repository	getBySlug(String projectNamespace, String projectKey, String slug) Retrieves a Repository by its slug.
Set<NamedLink>	getCloneLinks(RepositoryCloneLinksRequest request) Retrieves links that can be used to clone the supplied repository via the repository's SCM's supported protocols.
String	getDefaultBranch() Retrieves the configured global default branch.
MinimalRef	getDefaultBranch(Repository repository) Retrieves the configured default branch for the specified repository.
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.
Repository	retryCreate(Repository repository) If a create operation fails, calling this method will clean up the broken repository and try again.
Page<Repository>	search(RepositorySearchRequest request, PageRequest pageRequest) Searches for repositories that match the provided request.
void	setDefaultBranch(String defaultBranch) Sets the global default branch to use when creating new repositories.
Repository	update(RepositoryUpdateRequest request) Update the metadata of a repository.

Method Detail

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:

• RepositoryCreationRequestedEvent
• RepositoryCreatedEvent

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:

• RepositoryDeletionRequestedEvent
• RepositoryDeletedEvent

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

findByProjectKey

@Nonnull
Page<Repository> findByProjectKey(@Nullable
                                           String projectNamespace,
                                           @Nonnull
                                           String projectKey,
                                           @Nonnull
                                           PageRequest pageRequest)
                                    throws NoSuchProjectException

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

Since:

4.6

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:

• RepositoryForkRequestedEvent
• RepositoryForkedEvent

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

getBySlug

@Nullable
Repository getBySlug(@Nullable
                               String projectNamespace,
                               @Nonnull
                               String projectKey,
                               @Nonnull
                               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.

Specified by:

getBySlug in interface RepositorySupplier

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

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:

setDefaultBranch(String)

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:

RefService.getDefaultBranch(Repository)

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:

Repository.isForkable()

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:

RepositorySearchRequest

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:

getDefaultBranch()

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:

• RepositoryModificationRequestedEvent
• RepositoryModifiedEvent

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