Package com.atlassian.bitbucket.project

Interface ProjectService

All Superinterfaces:
ProjectSupplier
public interface ProjectService extends ProjectSupplier
Creates, updates and deletes projects.

  • Method Details

    • 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:

    • 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