public interface

ProjectService

implements ProjectSupplier
com.atlassian.bitbucket.project.ProjectService

Class Overview

Creates, updates and deletes projects.

Summary

Public Methods
@Nonnull Project create(ProjectCreateRequest request)
Creates a new Project and sets its avatar, if provided.
boolean delete(Project project)
Deletes the specified project, if it exists.
@Nonnull Page<Project> findAll(PageRequest pageRequest)
Retrieves a page of projects which are visible for the current user.
@Nonnull List<String> findAllKeys()
Retrieves the keys for all projects the current user can see.
@Nonnull CacheableAvatarSupplier getAvatar(int projectId, int size)
Retrieves the current avatar for the specified project at a requested size.
@Nullable Project getById(int id)
Retrieve a Project by its ID.
@Nullable Project getByKey(String key)
Retrieves a Project by its key.
@Nullable Project getByName(String name)
Retrieves a Project by its name.
@Nonnull Page<Project> search(ProjectSearchRequest searchRequest, PageRequest pageRequest)
Searches for projects which match the provided criteria.
@Nonnull Project update(ProjectUpdateRequest request)
Update a project's data with new values.
void updateAvatar(int projectId, String uri)
Updates the specified project's avatar, replacing it with the one contained in the provided data URI.
void updateAvatar(int projectId, AvatarSupplier supplier)
Updates the specified project's avatar, replacing it with the one contained in the provided supplier.
[Expand]
Inherited Methods
From interface com.atlassian.bitbucket.project.ProjectSupplier

Public Methods

@Nonnull public Project create (ProjectCreateRequest request)

Creates a new Project and sets its avatar, if provided.

Note: Both the project key and name must be unique.

Parameters
request describes the project to create
Returns
  • the created project
Throws
ProjectCreationCanceledException if creation is canceled by an event listener
ServiceException if the specified getKey() or getName() is not unique

public boolean delete (Project project)

Deletes the specified project, if it exists.

Personal projects cannot be deleted. Additionally, if the project contains any repositories, they must all be deleted before the project can be deleted.

Parameters
project the project to delete
Returns
  • true if the project was deleted; otherwise false if the project did not exist
Throws
ProjectDeletionCanceledException if deletion is canceled by an event listener
IntegrityException if the project is personal, or has repositories
ServiceException if the project exists and could not be deleted

@Nonnull public Page<Project> findAll (PageRequest pageRequest)

Retrieves a page of projects which are visible for the current user.

Note: Personal projects are never included in the returned page.

Parameters
pageRequest the bounds of the page
Returns
  • a page containing 0 or more projects to which the current user has access

@Nonnull public List<String> findAllKeys ()

Retrieves the keys for all projects the current user can see.

Note: Personal projects keys are never included in the returned list.

Warning: This mechanism is not paged. For systems with large numbers of projects, the returned list may be very large. For callers wishing to iterate over all existing projects, findAll(PageRequest) is the correct mechanism to use.

Returns
  • an unpaged list of keys for all projects the current user can see

@Nonnull public CacheableAvatarSupplier getAvatar (int projectId, int size)

Retrieves the current avatar for the specified project at a requested size. Avatars are square, so the size provided here is used as both height and width for the avatar.

The requested size will be normalised to fall within a well-defined set sizes. The supported sizes are:

  • 256
  • 128
  • 96
  • 64
  • 48
Any size larger than 256 will be normalised down to 256, and any size smaller than 48 will be normalised up to 48. Otherwise, sizes are normalised to the next size up, where they don't match exactly: 56 will be normalised to 64, 100 will be normalised to 128, and so on.

Parameters
projectId the ID of the project to retrieve the avatar for
size the desired height and width for the avatar
Returns
  • a supplier which can be used to access the requested avatar

@Nullable public Project getById (int id)

Retrieve a Project by its ID.

Parameters
id the ID of the project to retrieve
Returns
  • the project instance or null if no such project exists
Throws
AuthorisationException if the current user does not have permission to access the requested project

@Nullable public Project getByKey (String key)

Retrieves a Project by its key.

Parameters
key the key of the project to retrieve
Returns
  • the keyed project, or null if the key does not match an existing project
Throws
AuthorisationException if the current user does not have permission to access the requested project

@Nullable public Project getByName (String name)

Retrieves a Project by its name.

Parameters
name the name of the project to retrieve
Returns
  • the named project, or null if the name does not match an existing project
Throws
AuthorisationException if the current user does not have permission to access the requested project

@Nonnull public Page<Project> search (ProjectSearchRequest searchRequest, PageRequest pageRequest)

Searches for projects which match the provided criteria.

Parameters
searchRequest a criteria describing the projects to return
pageRequest the bounds of the page
Returns
See Also

@Nonnull public Project update (ProjectUpdateRequest request)

Update a project's data with new values. Project keys and names must be unique, so if the provided values match those of another Project an exception will be thrown.

Personal projects cannot be updated. Their keys, names and descriptions are managed by the system.

Parameters
request describes the project to update and the updates to apply
Returns
  • the updated project instance
Throws
ConstraintViolationException if the updated key or name collide with another project
IntegrityException if the project is personal
ProjectModificationCanceledException if modification is canceled by an event listener

public void updateAvatar (int projectId, String uri)

Updates the specified project's avatar, replacing it with the one contained in the provided data URI. The data URI is required to contain Base64-encoded image data, and should be in the format: data:(content type, e.g. image/png);base64,(data) If the data is not Base64-encoded, or if a character set is defined in the URI, it will be rejected.

Previous avatars are not retained. When a project's avatar is updated, the previous avatar is removed. To reuse a previous avatar, it must be provided again.

Personal project avatars cannot be updated. Their avatars are drawn from their owning users. If Gravatar support is enabled, personal project avatars may be updated by changing the user's avatar in Gravatar. Otherwise, they may not be updated at all.

Parameters
projectId the ID of the project to update the avatar for
uri a data URI containing a Base64-encoded avatar image
Throws
IntegrityException if the project is personal

public void updateAvatar (int projectId, AvatarSupplier supplier)

Updates the specified project's avatar, replacing it with the one contained in the provided supplier.

Previous avatars are not retained. When a project's avatar is updated, the previous avatar is removed. To reuse a previous avatar, it must be provided again.

Personal project avatars cannot be updated. Their avatars are drawn from their owning users. If Gravatar support is enabled, personal project avatars may be updated by changing the user's avatar in Gravatar. Otherwise, they may not be updated at all.

Parameters
projectId the ID of the project to update the avatar for
supplier a supplier providing access to the new avatar to use
Throws
IntegrityException if the project is personal