com.atlassian.bitbucket.project

Interface ProjectService

All Superinterfaces:

ProjectSupplier

public interface ProjectService
extends ProjectSupplier

Creates, updates and deletes projects.

Method Summary

Modifier and Type	Method and Description
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.
Page<Project>	findAll(PageRequest pageRequest) Retrieves a page of projects which are visible for the current user.
List<String>	findAllKeys() Retrieves the keys for all projects the current user can see.
CacheableAvatarSupplier	getAvatar(int projectId, int size) Retrieves the current avatar for the specified project at a requested size.
Project	getById(int id) Retrieve a Project by its ID.
Project	getByKey(String key) Retrieves a Project by its key.
Project	getByName(String name) Retrieves a Project by its name.
Page<Project>	search(ProjectSearchRequest searchRequest, PageRequest pageRequest) Searches for projects which match the provided criteria.
Project	update(ProjectUpdateRequest request) Update a project's data with new values.
void	updateAvatar(int projectId, AvatarSupplier supplier) Updates the specified project's avatar, replacing it with the one contained in the provided supplier.
void	updateAvatar(int projectId, String uri) Updates the specified project's avatar, replacing it with the one contained in the provided data URI.

Methods inherited from interface com.atlassian.bitbucket.project.ProjectSupplier

getByKey, getByName

Method Detail

create

@Nonnull
Project create(@Nonnull
                        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 AbstractProjectRequest.getKey() or AbstractProjectRequest.getName() is not unique

delete

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

findAll

@Nonnull
Page<Project> findAll(@Nonnull
                               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

findAllKeys

@Nonnull
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

getAvatar

@Nonnull
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

getById

@Nullable
Project getById(int id)

Retrieve a Project by its ID.

Specified by:

getById in interface ProjectSupplier

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

getByKey

@Nullable
Project getByKey(@Nonnull
                           String key)

Retrieves a Project by its key.

Specified by:

getByKey in interface ProjectSupplier

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

getByName

@Nullable
Project getByName(@Nonnull
                            String name)

Retrieves a Project by its name.

Specified by:

getByName in interface ProjectSupplier

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

search

@Nonnull
Page<Project> search(@Nonnull
                              ProjectSearchRequest searchRequest,
                              @Nonnull
                              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:

a page containing 0 or more projects which match the provided criteria

See Also:

ProjectSearchRequest

update

@Nonnull
Project update(@Nonnull
                        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:

javax.validation.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

updateAvatar

void updateAvatar(int projectId,
                  @Nonnull
                  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

updateAvatar

void updateAvatar(int projectId,
                  @Nonnull
                  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