@PublicApi public interface

AvatarManager

com.atlassian.jira.avatar.AvatarManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

Manager interface for Avatar domain objects.

Summary

Nested Classes
enum AvatarManager.ImageSize This enum is deprecated. in JIRA 6.0 -- use Avatar.Size.  
Constants
String AVATAR_IMAGE_FORMAT
String PNG_CONTENT_TYPE
String SVG_CONTENT_TYPE
String USER_AVATAR_ID_KEY
Fields
public static final AvatarFormat AVATAR_IMAGE_FORMAT_FULL
public static final AvatarFormat AVATAR_IMAGE_FORMAT_SVG
Public Methods
@Nonnull Avatar create(Avatar avatar, InputStream image, Selection selection)
Creates a database record for the given avatar and uses the content of the InputStream as the image.
@Nonnull Avatar create(Avatar.Type avatarType, String owningObjectId, AvatarImageDataProvider imageDataProvider)
Creates a database record for the given avatar and uses the content of the InputStream as the image.
@Nonnull Avatar create(Avatar avatar)
Creates a database record for the given avatar.
@Nonnull Avatar create(String fileName, String contentType, Project owner, InputStream image, Selection selection)
Creates a database record for the given avatar and uses the content of the InputStream as the image.
@Nonnull Avatar create(String fileName, String contentType, ApplicationUser owner, InputStream image, Selection selection)
Creates a database record for the given avatar and uses the content of the InputStream as the image.
boolean delete(Long avatarId)
Delete the avatar with the given id and the file on disk.
boolean delete(Long avatarId, boolean alsoDeleteAvatarFile)
Delete the avatar with the given id.
@Nonnull List<Avatar> getAllSystemAvatars(Avatar.Type type)
Provides a list of all system avatars.
Long getAnonymousAvatarId()
Gets the avatar id to use to represent an unknown or anonymous user
@Nonnull File getAvatarBaseDirectory()
Returns the directory for storing avatars.
Avatar getById(Long avatarId)
Retrieve the avatar with the given id.
Avatar getByIdTagged(Long avatarId)
Retrieve the avatar with the given id, ensuring the avatar file is tagged with metadata identifying the image came from JIRA.
@Nonnull @Deprecated List<Avatar> getCustomAvatarsForOwner(Avatar.Type type, String ownerId)
This method is deprecated. there can only be one. Since v6.4.
Long getDefaultAvatarId(Avatar.Type ofType)
Gets the default avatar for the given type.
boolean hasPermissionToEdit(ApplicationUser remoteUser, ApplicationUser owner)
Determines if the remoteUser provided has permission to edit avatars of a certain type for the owner provided.
boolean hasPermissionToEdit(ApplicationUser remoteUser, Project owner)
Determines if the remoteUser provided has permission to edit avatars of a certain type for the owner provided.
boolean hasPermissionToEdit(ApplicationUser remoteUser, Avatar.Type type, String ownerId)
boolean hasPermissionToView(ApplicationUser remoteUser, Project owner)
Determines if the remoteUser provided has permission to view avatars of a certain type for the owner provided.
boolean hasPermissionToView(ApplicationUser remoteUser, Avatar.Type type, String ownerId)
boolean hasPermissionToView(ApplicationUser remoteUser, ApplicationUser owner)
Determines if the remoteUser provided has permission to view avatars of a certain type for the owner provided.
boolean isAvatarOwner(Avatar avatar, String ownerId)
This method is deprecated. To be removed. Since v6.0
@Deprecated void readAvatarData(Avatar avatar, AvatarManager.ImageSize size, Consumer<InputStream> dataAccessor)
This method is deprecated. v7.0.1 Please use readAvatarData(Avatar, Avatar.Size, Consumer)
@ExperimentalApi void readAvatarData(Avatar avatar, Avatar.Size size, AvatarFormatPolicy avatarFormatPolicy, MediaConsumer mediaConsumer)
Provides read-only access to the data of the avatar image as an InputStream passed to the provided dataAccessor.
void readAvatarData(Avatar avatar, Avatar.Size size, Consumer<InputStream> dataAccessor)
Provides read-only access to the data of the avatar image as an InputStream passed to the provided dataAccessor.
void update(Avatar avatar)
Saves the avatar as an updated version of the avatar with the same id that is already in the database.

Constants

public static final String AVATAR_IMAGE_FORMAT

Constant Value: "PNG"

public static final String PNG_CONTENT_TYPE

Constant Value: "image/png"

public static final String SVG_CONTENT_TYPE

Constant Value: "image/svg+xml"

public static final String USER_AVATAR_ID_KEY

Constant Value: "user.avatar.id"

Fields

public static final AvatarFormat AVATAR_IMAGE_FORMAT_FULL

public static final AvatarFormat AVATAR_IMAGE_FORMAT_SVG

Public Methods

@Nonnull public Avatar create (Avatar avatar, InputStream image, Selection selection)

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

@Nonnull public Avatar create (Avatar.Type avatarType, String owningObjectId, AvatarImageDataProvider imageDataProvider)

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

@Nonnull public Avatar create (Avatar avatar)

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.

@Nonnull public Avatar create (String fileName, String contentType, Project owner, InputStream image, Selection selection)

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

@Nonnull public Avatar create (String fileName, String contentType, ApplicationUser owner, InputStream image, Selection selection)

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

public boolean delete (Long avatarId)

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.

public 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.

@Nonnull public List<Avatar> getAllSystemAvatars (Avatar.Type type)

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.

public Long getAnonymousAvatarId ()

Gets the avatar id to use to represent an unknown or anonymous user

Returns
  • the avatar id for an anonymous user

@Nonnull public File getAvatarBaseDirectory ()

Returns the directory for storing avatars.

Returns
  • the directory.

public Avatar getById (Long avatarId)

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.

public Avatar getByIdTagged (Long avatarId)

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.

@Nonnull @Deprecated public List<Avatar> getCustomAvatarsForOwner (Avatar.Type type, String ownerId)

This method is 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.

public Long getDefaultAvatarId (Avatar.Type ofType)

Gets the default avatar for the given type.

Parameters
ofType the Avatar type.
Returns
  • the default Avatar.

public boolean hasPermissionToEdit (ApplicationUser remoteUser, ApplicationUser owner)

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.

public boolean hasPermissionToEdit (ApplicationUser remoteUser, Project owner)

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.

public boolean hasPermissionToEdit (ApplicationUser remoteUser, Avatar.Type type, String ownerId)

This method is deprecated.
Use hasPermissionToEdit(ApplicationUser, ApplicationUser) or hasPermissionToEdit(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.Project). 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
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.

public boolean hasPermissionToView (ApplicationUser remoteUser, Project owner)

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.

public boolean hasPermissionToView (ApplicationUser remoteUser, Avatar.Type type, String ownerId)

This method is deprecated.
Use hasPermissionToView(com.atlassian.jira.user.ApplicationUser, ApplicationUser) or hasPermissionToView(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.Project). 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.

public boolean hasPermissionToView (ApplicationUser remoteUser, ApplicationUser owner)

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.

public boolean isAvatarOwner (Avatar avatar, String ownerId)

This method is 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.

@Deprecated public void readAvatarData (Avatar avatar, AvatarManager.ImageSize size, Consumer<InputStream> dataAccessor)

This method is 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.

@ExperimentalApi public void readAvatarData (Avatar avatar, Avatar.Size size, AvatarFormatPolicy avatarFormatPolicy, MediaConsumer mediaConsumer)

@ExperimentalApi

This method is considered usable by external developers but its contracts have not stabilized.

Experimental APIs may be changed at any time before being marked @Internal or @PublicApi.

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

public void readAvatarData (Avatar avatar, Avatar.Size size, Consumer<InputStream> dataAccessor)

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 createOriginalDataPolicy() as the requested type and 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.

public void update (Avatar avatar)

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.