public interface

RepositoryService

implements RepositorySupplier
com.atlassian.stash.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<? extends Repository> findAll(PageRequest pageRequest)
Find all repositories in the system.
@Nonnull Page<? extends Repository> findByOrigin(Repository origin, PageRequest pageRequest)
Retrieves a page of repositories which have been forked from the specified origin.
@Nonnull Page<Repository> findByOwner(StashUser owner, PageRequest pageRequest)
Retrieves a page of repositories owned by the specified user.
@Nonnull Page<? extends Repository> findByProjectKey(String projectKey, PageRequest pageRequest)
List the names of the repositories in the given project.
@Nullable Repository findPersonalFork(Repository repository)
Retrieves the current user's personal fork of the specified repository.
@Nonnull Page<? extends 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.
@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 on disk for the specified repository and returns that size in bytes.
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.
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.stash.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<? extends Repository> findAll (PageRequest pageRequest)

Find all repositories in the system.

Parameters
pageRequest the page of repositories to return.
Returns
  • a page of repositories.

@Nonnull public Page<? extends 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 (StashUser 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<? extends Repository> findByProjectKey (String projectKey, PageRequest pageRequest)

List the names of the repositories in the given project.

Parameters
projectKey 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

@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<? extends 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 or the current user does not have access to it

@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

@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 although whether and how this customisation takes place is entirely up to each protocol. Stash's own SSH and HTTP protocols do exactly this.

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

public long getSize (Repository repository)

Calculates the size on disk for the specified repository and returns that size in bytes.

If the provided Repository does not exist, its size is always 0.

Parameters
repository the repository whose size should be calculated
Returns
  • the size of the specified repository in bytes

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

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