public interface

ProjectService

com.atlassian.stash.project.ProjectService

Class Overview

Creates, updates and deletes projects.

Summary

Public Methods
@Deprecated @Nonnull Project create(String key, String name, String description, AvatarSupplier supplier)
This method is deprecated. in 2.5 for removal in 3.0. This method has been replaced by create(ProjectCreateRequest), which uses a request object to make it more readily extensible
@Deprecated @Nonnull Project create(String key, String name, String description, String avatarUri)
This method is deprecated. in 2.5 for removal in 3.0. This method has been replaced by create(ProjectCreateRequest), which uses a request object to make it more readily extensible
@Nonnull Project create(String key, String name, String description)
This method is deprecated. in 2.5 for removal in 3.0. This method has been replaced by create(ProjectCreateRequest), which uses a request object to make it more readily extensible
@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<? extends 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.
@Deprecated @Nonnull List<String> findAllProjectKeys()
This method is deprecated. in 2.4 for removal in 3.0. For consistency with other methods on this service, which omit the "Project" qualifier (since it is implied by the service itself), this method has been replaced by findAllKeys()
@Deprecated @Nullable Project findByKey(String projectKey)
This method is deprecated. in 2.4 for removal in 3.0. For consistency with other services, this method has been replaced by getByKey(String)
@Deprecated @Nullable Project findByName(String projectName)
This method is deprecated. in 2.4 for removal in 3.0. For consistency with other services, this method has been replaced by getByName(String)
@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<? extends Project> search(ProjectSearchCriteria criteria, PageRequest pageRequest)
Searches for projects which match the provided criteria.
@Nonnull Project update(ProjectUpdateRequest request)
Update a project's data with new values.
@Deprecated @Nonnull Project update(int id, String projectKey, String name, String description)
This method is deprecated. in 2.5 for removal in 3.0. This method has been replaced by update(ProjectUpdateRequest), which uses a request object to make it more readily extensible
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.

Public Methods

@Deprecated @Nonnull public Project create (String key, String name, String description, AvatarSupplier supplier)

This method is deprecated.
in 2.5 for removal in 3.0. This method has been replaced by create(ProjectCreateRequest), which uses a request object to make it more readily extensible

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

If an avatar is provided which cannot be read, or contains invalid data, project creation will fail. This operation is all-or-nothing. To allow project creation to succeed even if the avatar cannot be set, call create(String, String, String) to create the project and then use set the avatar as a separate operation.

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

Parameters
key the unique key to identify the project, always stored in uppercase
name the unique name for the project
description an optional description for the project
supplier a supplier containing an avatar image, or null to use a default avatar
Returns
  • the created project
Throws
ServiceException if the specified key or name is not unique

@Deprecated @Nonnull public Project create (String key, String name, String description, String avatarUri)

This method is deprecated.
in 2.5 for removal in 3.0. This method has been replaced by create(ProjectCreateRequest), which uses a request object to make it more readily extensible

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

The avatar 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, or the URI is otherwise invalid, project creation will fail. This operation is all-or-nothing. To allow project creation to succeed even if the avatar cannot be parsed, call create(String, String, String) to create the project and then use set the avatar as a separate operation.

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

Parameters
key the unique key to identify the project, always stored in uppercase
name the unique name for the project
description an optional description for the project
avatarUri a data URI containing a Base64-encoded avatar image, or null to use a default avatar
Returns
  • the created project
Throws
ServiceException if the specified key or name is not unique

@Nonnull public Project create (String key, String name, String description)

This method is deprecated.
in 2.5 for removal in 3.0. This method has been replaced by create(ProjectCreateRequest), which uses a request object to make it more readily extensible

Creates a new Project with a default avatar.

Both the project key and name must be unique.

Parameters
key the unique key to identify the project, always stored in uppercase
name the unique name for the project
description an optional description for the project.
Returns
  • the created project
Throws
ServiceException if the specified key or name is not unique

@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 repository 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<? extends 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

@Deprecated @Nonnull public List<String> findAllProjectKeys ()

This method is deprecated.
in 2.4 for removal in 3.0. For consistency with other methods on this service, which omit the "Project" qualifier (since it is implied by the service itself), this method has been replaced by 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

@Deprecated @Nullable public Project findByKey (String projectKey)

This method is deprecated.
in 2.4 for removal in 3.0. For consistency with other services, this method has been replaced by getByKey(String)

Finds a project by its key, ignoring case. This method may throw a security exception if the user does not have access to the project.

Parameters
projectKey the project key desired.
Returns
  • A project instance or null if no such project is found.

@Deprecated @Nullable public Project findByName (String projectName)

This method is deprecated.
in 2.4 for removal in 3.0. For consistency with other services, this method has been replaced by getByName(String)

Finds a project by its name, ignoring case. This method may throw a security exception if the user does not have access to the project.

Parameters
projectName the project name
Returns
  • the project instance or null if no such project exists.

@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<? extends Project> search (ProjectSearchCriteria criteria, PageRequest pageRequest)

Searches for projects which match the provided criteria.

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

@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

@Deprecated @Nonnull public Project update (int id, String projectKey, String name, String description)

This method is deprecated.
in 2.5 for removal in 3.0. This method has been replaced by update(ProjectUpdateRequest), which uses a request object to make it more readily extensible

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
id the id of the projects to be updated
projectKey the new value of the project key
name the new project name
description the new project description
Returns
  • the updated project instance
Throws
ConstraintViolationException if the updated key or name collide with another project
IntegrityException if the project is personal

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