Package com.atlassian.jira.avatar

Interface AvatarManager

All Known Implementing Classes:
AvatarManagerImpl
@PublicApi public interface AvatarManager
Manager interface for Avatar domain objects.
Since:
v4.0

  • Field Details

  • Method Details

    • getById

      Avatar getById(Long avatarId) throws DataAccessException
      Retrieve the avatar with the given id.
      Parameters:
      avatarId - must not be null.
      Returns:
      the Avatar if there is one or null if not.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • getByIdTagged

      Avatar getByIdTagged(Long avatarId) throws DataAccessException
      Retrieve the avatar with the given id, ensuring the avatar file is tagged with metadata identifying the image came from JIRA.
      Parameters:
      avatarId - must not be null.
      Returns:
      the Avatar if there is one or null if not.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • delete

      boolean delete(Long avatarId) throws DataAccessException
      Delete the avatar with the given id and the file on disk.
      Parameters:
      avatarId - must not be null.
      Returns:
      true only if there was an avatar with the given id which was deleted.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • delete

      boolean delete(Long avatarId, boolean alsoDeleteAvatarFile)
      Delete the avatar with the given id.
      Parameters:
      avatarId - must not be null.
      alsoDeleteAvatarFile - if false, the avatar file will be left on disk.
      Returns:
      true only if there was an avatar with the given id which was deleted.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • update

      void update(Avatar avatar) throws DataAccessException
      Saves the avatar as an updated version of the avatar with the same id that is already in the database.
      Parameters:
      avatar - must not be null.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • create

      @Nonnull Avatar create(Avatar avatar) throws DataAccessException
      Creates a database record for the given avatar. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      avatar - must not be null, must have a null id.
      Returns:
      the created avatar which has an assigned id.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • create

      @Nonnull Avatar create(Avatar avatar, InputStream image, Selection selection) throws DataAccessException, IOException
      Creates a database record for the given avatar and uses the content of the InputStream as the image. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      avatar - must not be null, must have a null id.
      image - the data of the original avatar image.
      selection - the cropping selection for the image or null to take whole image.
      Returns:
      the created avatar which has an assigned id.
      Throws:
      DataAccessException - if there is a back-end database problem.
      IOException
      Since:
      v6.3

    • create

      @Nonnull Avatar create(Avatar.Type avatarType, @Nonnull String owningObjectId, @Nonnull AvatarImageDataProvider imageDataProvider) throws IOException
      Deprecated.
      Use create(IconType, IconOwningObjectId, AvatarImageDataProvider) since v7.1
      Creates a database record for the given avatar and uses the content of the InputStream as the image. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      avatarType - type of new avatar to create.
      owningObjectId - id of object (project/user/issuetype) to which this avatar is connected to.
      imageDataProvider - provider of image data
      Returns:
      the created avatar which has an assigned id.
      Throws:
      DataAccessException - if there is a back-end database problem.
      IOException - if there are arrors when processing image data
      Since:
      v6.3
      See Also:

    • create

      @Nonnull Avatar create(@Nonnull IconType iconType, @Nonnull IconOwningObjectId owningObjectId, @Nonnull AvatarImageDataProvider imageDataProvider) throws IOException
      Creates a database record for the given avatar and uses the content of the InputStream as the image. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      iconType - type of new avatar to create.
      owningObjectId - id of object (project/user/issuetype) to which this avatar is connected to.
      imageDataProvider - provider of image data
      Returns:
      the created avatar which has an assigned id.
      Throws:
      DataAccessException - if there is a back-end database problem.
      IOException - if there are arrors when processing image data
      Since:
      v7.1
      See Also:

    • create

      @Nonnull Avatar create(String fileName, String contentType, IconType iconType, IconOwningObjectId owner, InputStream image, Selection selection) throws DataAccessException, IOException
      Creates a database record for the given avatar and uses the content of the InputStream as the image. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      fileName - the name of the avatar
      contentType - MIME content type for the avatar
      iconType - The type of avatar to create.
      owner - The object that will own the icon.
      image - the data of the original avatar image (it will be automatically closed)
      selection - the cropping selection for the image or null to take whole image
      Returns:
      the created avatar which has an assigned id
      Throws:
      IOException - If there was a problem consuming the image data, or a problem storing the image data.
      DataAccessException
      Since:
      v7.1

    • create

      @Nonnull Avatar create(String fileName, String contentType, Project owner, InputStream image, Selection selection) throws DataAccessException, IOException
      Deprecated.
      Use create(String, String, IconType, IconOwningObjectId, InputStream, Selection). Since v7.1
      Creates a database record for the given avatar and uses the content of the InputStream as the image. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      fileName - the name of the avatar
      contentType - MIME content type for the avatar
      image - the data of the original avatar image (it will be automatically closed)
      selection - the cropping selection for the image or null to take whole image
      Returns:
      the created avatar which has an assigned id
      Throws:
      DataAccessException - if there is a back-end database problem.
      IOException

    • create

      @Nonnull Avatar create(String fileName, String contentType, ApplicationUser owner, InputStream image, Selection selection) throws DataAccessException, IOException
      Deprecated.
      Use create(String, String, IconType, IconOwningObjectId, InputStream, Selection). Since v7.1.
      Creates a database record for the given avatar and uses the content of the InputStream as the image. Use the return value as the persistent avatar, not the one you passed in.
      Parameters:
      fileName - the name of the avatar
      contentType - MIME content type for the avatar
      image - the data of the original avatar image (it will be automatically closed)
      selection - the cropping selection for the image or null to take whole image
      Returns:
      the created avatar which has an assigned id
      Throws:
      DataAccessException - if there is a back-end database problem.
      IOException

    • getAllSystemAvatars

      @Nonnull List<Avatar> getAllSystemAvatars(Avatar.Type type) throws DataAccessException
      Deprecated.
      Use getAllSystemAvatars(IconType) instead. Since v7.1
      Provides a list of all system avatars.
      Parameters:
      type - The type of system avatars to return
      Returns:
      the system avatars.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • getAllSystemAvatars

      @Nonnull List<Avatar> getAllSystemAvatars(IconType iconType) throws DataAccessException
      Provides a list of all system avatars.
      Parameters:
      iconType - The type of system avatars to return
      Returns:
      the system avatars.
      Throws:
      DataAccessException - if there is a back-end database problem.
      Since:
      v7.1

    • getCustomAvatarsForOwner

      @Nonnull @Deprecated List<Avatar> getCustomAvatarsForOwner(Avatar.Type type, String ownerId) throws DataAccessException
      Deprecated.
      there can only be one. Since v6.4.
      Provides a list of all avatars that are of the given type which have the given owner.
      Parameters:
      type - the desired type of the avatars to retrieve.
      ownerId - the id of the owner, matches the type (project id or user key).
      Returns:
      all the avatars that have the given type and owner, never null.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • getCustomAvatarsForOwner

      @Nonnull List<Avatar> getCustomAvatarsForOwner(IconType iconType, String ownerId) throws DataAccessException
      Provides a list of all avatars that are of the given type which have the given owner.
      Parameters:
      iconType - the desired type of the avatars to retrieve.
      ownerId - the id of the owner, matches the type (project id or user key).
      Returns:
      all the avatars that have the given type and owner, never null.
      Throws:
      DataAccessException - if there is a back-end database problem.

    • isAvatarOwner

      boolean isAvatarOwner(Avatar avatar, String ownerId)
      Deprecated.
      To be removed. Since v6.0
      Tells whether the given avatar is owned by the given ownerId.
      Parameters:
      avatar - the avatar to check, must not be null.
      ownerId - the ownerId to check, must not be null.
      Returns:
      true only if the given ownerId is the ownerId of the given avatar.

    • readAvatarData

      @Deprecated void readAvatarData(Avatar avatar, AvatarManager.ImageSize size, Consumer<InputStream> dataAccessor) throws IOException
      Deprecated.
      v7.0.1 Please use readAvatarData(Avatar, Avatar.Size, Consumer)
      Provides read-only access to the data of the avatar image as an InputStream passed to the provided dataAccessor. The InputStream is closed after the dataAccessor completes. The dataAccessor is immediately invoked on the data for the avatar.
      Parameters:
      avatar - the avatar for which the data is to be processed.
      size - the size to return for this avatar
      dataAccessor - something to read the data.
      Throws:
      IOException - if an IOException occurs in the dataAccessor or in acquiring the InputStream for the avatar.
      See Also:

    • readAvatarData

      void readAvatarData(@Nonnull Avatar avatar, @Nonnull Avatar.Size size, @Nonnull Consumer<InputStream> dataAccessor) throws IOException
      Provides read-only access to the data of the avatar image as an InputStream passed to the provided dataAccessor. The InputStream is closed after the dataAccessor completes. The dataAccessor is immediately invoked on the data for the avatar.

      This is equivalent to calling readAvatarData(Avatar, Avatar.Size, AvatarFormatPolicy, MediaConsumer) with AvatarFormatPolicy.createOriginalDataPolicy() as the requested type and Optional.empty() as type Accessor.

      Parameters:
      avatar - the avatar for which the data is to be processed.
      size - the size to return for this avatar
      dataAccessor - something to read the data.
      Throws:
      IOException - if an IOException occurs in the dataAccessor or in acquiring the InputStream for the avatar.
      Since:
      v7.0.1
      See Also:

    • readAvatarData

      @ExperimentalApi void readAvatarData(@Nonnull Avatar avatar, @Nonnull Avatar.Size size, @Nonnull AvatarFormatPolicy avatarFormatPolicy, @Nonnull MediaConsumer mediaConsumer) throws IOException
      Provides read-only access to the data of the avatar image as an InputStream passed to the provided dataAccessor. The InputStream is closed after the dataAccessor completes. The dataAccessor is immediately invoked on the data for the avatar.

      The format that the image will be served in, is determined by the AvatarFormatPolicy that is provided as a parameter. This should be used to set the content type of the data being provided to the @Consumer<InputStream>. If the parameters are non-strict, it will be a best attempt, and to know which content type has been used please provide a typeAccessor.

      Parameters:
      avatar - the avatar for which the data is to be processed.
      size - the size to return for this avatar
      avatarFormatPolicy - the requested format for avatar data.
      mediaConsumer - consumer that will read the data.
      Throws:
      IOException - if an IOException occurs in the dataAccessor or in acquiring the InputStream for the avatar.
      IllegalArgumentException - If a strict request is made, but it is not possible to obey
      Since:
      v7.0.1

    • getDefaultAvatarId

      Long getDefaultAvatarId(@Nonnull Avatar.Type ofType)
      Deprecated.
      Use getDefaultAvatarId(IconType) Since v7.1
      Gets the default avatar ID for the given type.
      Parameters:
      ofType - the Avatar type.
      Returns:
      the default Avatar ID.

    • getDefaultAvatarId

      Long getDefaultAvatarId(@Nonnull IconType iconType)
      Gets the default avatar ID for the given type.
      Parameters:
      iconType - the Icon type.
      Returns:
      the default Avatar ID.

    • getDefaultAvatar

      Avatar getDefaultAvatar(@Nonnull IconType iconType)
      Gets the default avatar for the given type.
      Parameters:
      iconType - the Icon type.
      Returns:
      the default Avatar, or null if the default avatar cannot be found for some reason. (e.g. There are no avatars for this type, or the type is invalid.)

    • isValidIconType

      boolean isValidIconType(@Nonnull IconType iconType)
      Check if this is a valid icon type.
      Parameters:
      iconType - The icon type to check.
      Returns:
      True if this iconType is recognised, or false otherwise.

    • getAnonymousAvatarId

      Long getAnonymousAvatarId()
      Gets the avatar id to use to represent an unknown or anonymous user
      Returns:
      the avatar id for an anonymous user

    • hasPermissionToView

      boolean hasPermissionToView(ApplicationUser remoteUser, Avatar.Type type, String ownerId)
      Deprecated.
      Use userCanView(ApplicationUser, Avatar) Since v6.0
      Determines if the remoteUser provided has permission to view avatars of a certain type for the owner provided. For project avatars, this method checks that the user is either and admin, project admin or has browse permission for the owner project. For user avatars, the method checks that the remoteUser has use permission for JIRA or the remoteUser and avatar owner are the same person
      Parameters:
      remoteUser - The remote user trying to view an avatar
      type - The type of avatar
      ownerId - The owner id of the avatar being viewed (project id or user key)
      Returns:
      true if the remote user has permission to view avatars owned by the owner provided.

    • hasPermissionToView

      boolean hasPermissionToView(ApplicationUser remoteUser, ApplicationUser owner)
      Deprecated.
      Use userCanView(ApplicationUser, Avatar) Since v7.1
      Determines if the remoteUser provided has permission to view avatars of a certain type for the owner provided. For project avatars, this method checks that the user is either and admin, project admin or has browse permission for the owner project. For user avatars, the method checks that the remoteUser has use permission for JIRA or the remoteUser and avatar owner are the same person
      Parameters:
      remoteUser - The remote user trying to view an avatar
      owner - The owner of the avatar being viewed
      Returns:
      true if the remote user has permission to view avatars owned by the owner provided.
      Since:
      v6.0

    • hasPermissionToView

      boolean hasPermissionToView(ApplicationUser remoteUser, Project owner)
      Deprecated.
      Use userCanView(ApplicationUser, Avatar) Since v7.1
      Determines if the remoteUser provided has permission to view avatars of a certain type for the owner provided. For project avatars, this method checks that the user is either and admin, project admin or has browse permission for the owner project. For user avatars, the method checks that the remoteUser has use permission for JIRA or the remoteUser and avatar owner are the same person
      Parameters:
      remoteUser - The remote user trying to view an avatar
      owner - The owner of the avatar being viewed
      Returns:
      true if the remote user has permission to view avatars owned by the owner provided.
      Since:
      v6.0

    • hasPermissionToEdit

      boolean hasPermissionToEdit(ApplicationUser remoteUser, Avatar.Type type, String ownerId)
      Deprecated.
      Use userCanCreateFor(ApplicationUser, IconType, IconOwningObjectId) Since v7.1
      Determines if the remoteUser provided has permission to edit avatars of a certain type for the owner provided. For project avatars, this method checks that the user is either and admin or project admin for the owner project. For user avatars, the method checks that the remoteUser has admin permissions for JIRA or the remoteUser and avatar owner are the same person. If external user management is enabled this method returns false
      Parameters:
      remoteUser - The remote user trying to edit an avatar
      type - The type of avatar
      ownerId - The owner id of the avatar being edited (project id or user key)
      Returns:
      true if the remote user has permission to edit avatars owned by the owner provided.

    • hasPermissionToEdit

      boolean hasPermissionToEdit(ApplicationUser remoteUser, ApplicationUser owner)
      Deprecated.
      Use userCanCreateFor(ApplicationUser, IconType, IconOwningObjectId) Since v6.0
      Determines if the remoteUser provided has permission to edit avatars of a certain type for the owner provided. For project avatars, this method checks that the user is either and admin or project admin for the owner project. For user avatars, the method checks that the remoteUser has admin permissions for JIRA or the remoteUser and avatar owner are the same person. If external user management is enabled this method returns false
      Parameters:
      remoteUser - The remote user trying to edit an avatar
      owner - The owner of the avatar being edited
      Returns:
      true if the remote user has permission to edit avatars owned by the owner provided.
      Since:
      v6.0

    • hasPermissionToEdit

      boolean hasPermissionToEdit(ApplicationUser remoteUser, Project owner)
      Deprecated.
      Use userCanCreateFor(ApplicationUser, IconType, IconOwningObjectId) Since v7.1
      Determines if the remoteUser provided has permission to edit avatars of a certain type for the owner provided. For project avatars, this method checks that the user is either and admin or project admin for the owner project. For user avatars, the method checks that the remoteUser has admin permissions for JIRA or the remoteUser and avatar owner are the same person. If external user management is enabled this method returns false
      Parameters:
      remoteUser - The remote user trying to edit an avatar
      owner - The owner of the avatar being edited
      Returns:
      true if the remote user has permission to edit avatars owned by the owner provided.
      Since:
      v6.0

    • userCanView

      boolean userCanView(@Nullable ApplicationUser remoteUser, @Nonnull Avatar icon)
      Check if the user can view the icon.
      Parameters:
      remoteUser - user whose permissions should be used. Null means anonymous access.
      icon - The icon that the user wishes to access.
      Returns:
      Returns true if the user is allowed to view the avatar, or false otherwise.

    • userCanDelete

      boolean userCanDelete(@Nullable ApplicationUser remoteUser, @Nonnull Avatar icon)
      Check if the user can delete the icon.
      Parameters:
      remoteUser - user whose permissions should be used. Null means anonymous access.
      icon - The icon that the user wishes to delete.
      Returns:
      Returns true if the user is allowed to delete the avatar, or false otherwise.

    • userCanCreateFor

      boolean userCanCreateFor(@Nullable ApplicationUser remoteUser, @Nonnull IconType iconType, @Nonnull IconOwningObjectId owningObjectId)
      Check if the user could create an avatar for this owning object.
      Parameters:
      remoteUser - user whose permissions should be used. Null means anonymous access.
      iconType - The type of icon the user is trying to create.
      owningObjectId - id of the object to which this avatar is connected to. This helps set the scope for the provider of the IconType to determine permissions for icons that have not been created yet.

    • hasImage

      @ExperimentalApi boolean hasImage(@Nonnull Avatar avatar, @Nonnull Avatar.Size size)
      Checks if valid image exists for avatar and image can be consumed by readAvatarData(Avatar, Avatar.Size, AvatarFormatPolicy, MediaConsumer). An example of avatar with invalid image would be avatar with its image removed from the filesystem.
      Parameters:
      avatar - Avatar
      size - Avatar size
      Returns:
      true if avatar contains valid image that can be consumed.