com.atlassian.bitbucket.user

Interface UserService

public interface UserService

Provides methods for querying users. This service also offers limited ability to update the current user.

A note about user stores and deleted users: the system uses Crowd to provide access to LDAP servers, other Crowd servers, or Jira (which is able to serve as a central user store for other Atlassian products). Crowd maintains a local cache of users, which is termed the "user store" by this service. The system also maintains a secondary table of users, outside Crowd, allowing it to decorate Crowd users with additional properties as well as to anchor relationships between users and their data, such as comments and pull requests.

Because the Crowd user store is a cache of users managed elsewhere, be they in LDAP, Jira, etc., it is possible for users to be deleted from that user store but still exist in the system's secondary user table. Such users are termed "deleted", and, when retrieved, will only offer a minimal set of data. Generally, after deletion, only a user's username is still available. Display names, e-mail addresses and other data are managed by Crowd and are lost when the user is deleted.

In addition to deleted users, Crowd has the concept of an inactive user. These users cannot log in and may or may not have an associated ApplicationUser. Inactive users are handled consistently as deleted and both are taken into consideration when determining ApplicationUser.isActive().

Groups are reported as strings. When persisting or displaying groups, it is recommended to store the group name as reported by the API; when performing tests for equality on groups, it is recommended to ignore case.

See Also:

UserAdminService

Method Summary

Modifier and Type	Method and Description
void	deleteAvatar(ApplicationUser user) Delete the avatar associated with a user.
boolean	existsGroup(String groupName) Retrieves a flag indicating whether the specified group exists.
Page<String>	findGroups(PageRequest pageRequest) Retrieves a page of groups.
Page<String>	findGroupsByName(String groupName, PageRequest pageRequest) Retrieves a page of groups, optionally filtering the returned results to those containing the specified groupName.
Page<String>	findGroupsByPrefix(String groupPrefix, PageRequest pageRequest) Retrieves a page of groups, optionally filtering the returned results to those beginning with the specified groupPrefix.
Page<String>	findGroupsByUser(String username, PageRequest pageRequest) Retrieves a page of groups which the specified user is a member of.
ApplicationUser	findUserByEmail(String value) Retrieve the first active normal user whose e-mail address exactly matches the provided value.
ApplicationUser	findUserByNameOrEmail(String value) Retrieve the first active normal user whose username or e-mail address exactly matches the provided value.
Page<ApplicationUser>	findUsers(PageRequest pageRequest) Retrieves a page of active normal users.
Page<ApplicationUser>	findUsersByGroup(String groupName, PageRequest pageRequest) Retrieves a page of active users which are members of the specified group.
Page<ApplicationUser>	findUsersByName(String username, PageRequest pageRequest) Retrieves a page of active normal users, optionally filtering the returned results to those containing the specified username.
CacheableAvatarSupplier	getAvatar(ApplicationUser user, int size) Retrieves the current avatar for the specified user at a requested size.
ServiceUser	getServiceUserByName(String username) Retrieves an active ServiceUser by its username.
ServiceUser	getServiceUserByName(String username, boolean inactive) Retrieves a ServiceUser by its username, optionally returning the user even if it has been marked inactive.
ServiceUser	getServiceUserBySlug(String slug) Retrieves an active ServiceUser by its exact (case-sensitive) slug.
Set<ServiceUser>	getServiceUsersByName(Set<String> usernames) Retrieves a set of active ServiceUsers by their usernames.
Set<ServiceUser>	getServiceUsersByName(Set<String> usernames, boolean inactive) Retrieves a set of ServiceUsers by their usernames, optionally including deleted service users.
ApplicationUser	getUserById(int id) Retrieves a ApplicationUser by its ID.
ApplicationUser	getUserById(int id, boolean inactive) Retrieves a ApplicationUser by its ID.
ApplicationUser	getUserByName(String username) Retrieves an active ApplicationUser by its username.
ApplicationUser	getUserByName(String username, boolean inactive) Retrieves a ApplicationUser by its username, optionally returning the user even if it has been removed from the underlying user store.
ApplicationUser	getUserBySlug(String slug) Retrieves an active ApplicationUser by its exact (case-sensitive) slug.
Set<ApplicationUser>	getUsersById(Set<Integer> ids) Retrieves a set of active ApplicationUsers by their IDs.
Set<ApplicationUser>	getUsersById(Set<Integer> ids, boolean inactive) Retrieves a set of ApplicationUsers by their IDs, optionally including users who have been removed from the underlying user store.
Set<ApplicationUser>	getUsersByName(Set<String> usernames) Retrieves a set of active ApplicationUsers by their usernames.
Set<ApplicationUser>	getUsersByName(Set<String> usernames, boolean inactive) Retrieves a set of ApplicationUsers by their usernames, optionally including users who have been removed from the underlying user store.
boolean	isUserActive(ApplicationUser user) Retrieves the active state of the user.
boolean	isUserActive(ApplicationUser user, boolean checkDirectory) Retrieves the active state of the user.
boolean	isUserInGroup(ApplicationUser user, String groupName) Retrieves a flag indicating whether the specified user is a member of the specified group.
boolean	isUserInGroup(String username, String groupName) Retrieves a flag indicating whether the specified user is a member of the specified group.
Page<ApplicationUser>	search(UserSearchRequest request, PageRequest pageRequest) Searches for users that match the provided request.
void	updateAvatar(ApplicationUser user, AvatarSupplier supplier) Updates the specified user's avatar, replacing it with the one contained in the provided supplier.
void	updateAvatar(ApplicationUser user, String uri) Updates the specified user's avatar, replacing it with the one contained in the provided data URI.
void	updatePassword(String currentPassword, String newPassword) Updates the password for the current user.
ApplicationUser	updateUser(String displayName, String emailAddress) Updates the display name and e-mail address for the current user.

Method Detail

deleteAvatar

void deleteAvatar(@Nonnull
                  ApplicationUser user)

Delete the avatar associated with a user.

This will revert the avatar of the user in the UI to their Gravatar image (if the Gravatar integration is enabled) or to the default user avatar (if the Gravatar integration is disabled)

Parameters:

user - the user whose (local) avatar will be removed

existsGroup

boolean existsGroup(String groupName)

Retrieves a flag indicating whether the specified group exists.

Parameters:

groupName - the group name

Returns:

true if a group with the specified name exists in any directory; otherwise, false

findGroups

@Nonnull
Page<String> findGroups(@Nonnull
                                 PageRequest pageRequest)

Retrieves a page of groups.

Note: To filter the retrieved groups by name, use findGroupsByName(String, PageRequest) instead.

Parameters:

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, which may be empty but never null

See Also:

findGroupsByName(String, PageRequest)

findGroupsByName

@Nonnull
Page<String> findGroupsByName(@Nullable
                                       String groupName,
                                       @Nonnull
                                       PageRequest pageRequest)

Retrieves a page of groups, optionally filtering the returned results to those containing the specified groupName. If the provided groupName is null, this method behaves identically to findGroups(PageRequest).

Parameters:

groupName - 0 or more characters to apply as a filter on returned groups

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, potentially filtered, which may be empty but never null

See Also:

findGroups(PageRequest)

findGroupsByPrefix

@Nonnull
Page<String> findGroupsByPrefix(@Nullable
                                         String groupPrefix,
                                         @Nonnull
                                         PageRequest pageRequest)

Retrieves a page of groups, optionally filtering the returned results to those beginning with the specified groupPrefix. If the provided groupPrefix is null, this method behaves identically to findGroups(PageRequest).

This method varies slightly from findGroupsByName(String, PageRequest), which will match the specified name at the beginning of any word boundary in the group. For example, "test-group" will match "group". With this method, a prefix of "group" will not match "test-group".

Parameters:

groupPrefix - 0 or more characters defining a prefix which returned group names must start with

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, potentially filtered by prefix, which may be empty but never null

See Also:

findGroups(PageRequest)

findGroupsByUser

@Nonnull
Page<String> findGroupsByUser(@Nonnull
                                       String username,
                                       @Nonnull
                                       PageRequest pageRequest)

Retrieves a page of groups which the specified user is a member of. The username provided must match exactly in order for any results to be returned.

Parameters:

username - the exact name of the user to retrieve groups for

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, which may be empty but never null

See Also:

findUsersByGroup(String, PageRequest)

findUserByEmail

@Nullable
ApplicationUser findUserByEmail(@Nonnull
                                          String value)

Retrieve the first active normal user whose e-mail address exactly matches the provided value.

Parameters:

value - the value to match against e-mail addresses

Returns:

a user whose e-mail address matches the specified value, or null if no matching user was found

Since:

5.1

findUserByNameOrEmail

@Nullable
ApplicationUser findUserByNameOrEmail(@Nonnull
                                                String value)

Retrieve the first active normal user whose username or e-mail address exactly matches the provided value.

Usernames are the preferred match, so they will be tested first. If no user exists with a username matching the value, e-mail addresses will then be checked.

Parameters:

value - the value to match, first against usernames and then against e-mail addresses

Returns:

a user whose username or e-mail address matches the specified value, or null if no matching user was found

findUsers

@Nonnull
Page<ApplicationUser> findUsers(@Nonnull
                                         PageRequest pageRequest)

Retrieves a page of active normal users.

Note: To filter the retrieved users by name, use findUsersByName(String, PageRequest) instead.

Parameters:

pageRequest - defines the page of users to retrieve

Returns:

the requested page of users, which may be empty but never null

See Also:

findUsersByName(String, PageRequest)

findUsersByName

@Nonnull
Page<ApplicationUser> findUsersByName(@Nullable
                                               String username,
                                               @Nonnull
                                               PageRequest pageRequest)

Retrieves a page of active normal users, optionally filtering the returned results to those containing the specified username. If the provided username is null, this method behaves identically to findUsers(PageRequest). Otherwise, the username is matched against:

• Display names
• E-mail addresses
• Usernames

Parameters:

username - 0 or more characters to apply as a filter on returned users

pageRequest - defines the page of users to retrieve

Returns:

the requested page of users, potentially filtered, which may be empty but never null

See Also:

findUsers(PageRequest)

findUsersByGroup

@Nonnull
Page<ApplicationUser> findUsersByGroup(@Nonnull
                                                String groupName,
                                                @Nonnull
                                                PageRequest pageRequest)

Retrieves a page of active users which are members of the specified group. The groupName provided must match exactly in order for any results to be returned.

Parameters:

groupName - the exact name of the group to retrieve members for

pageRequest - defines the page of users to retrieve

Returns:

the requested page of users, which may be empty but never null

See Also:

findGroupsByUser(String, PageRequest)

getAvatar

@Nonnull
CacheableAvatarSupplier getAvatar(@Nonnull
                                           ApplicationUser user,
                                           int size)

Retrieves the current avatar for the specified user 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:

user - the user whose avatar should be retrieved

size - the desired height and width for the avatar

Returns:

a supplier which can be used to access the requested avatar

getServiceUserByName

@Nullable
ServiceUser getServiceUserByName(@Nonnull
                                           String username)

Retrieves an active ServiceUser by its username.

This method will not return inactive users; use getServiceUserByName(String, boolean) instead if inactive users are desired.

Parameters:

username - the username of the user to retrieve

Returns:

the user with the specified username, or null if no matching user exists or the matching user has been deleted from the user store

getServiceUserByName

@Nullable
ServiceUser getServiceUserByName(@Nonnull
                                           String username,
                                           boolean inactive)

Retrieves a ServiceUser by its username, optionally returning the user even if it has been marked inactive.

If requested, this method will return inactive users.

Parameters:

username - the username of the user to retrieve

inactive - true if inactive users should be returned, false otherwise.

Returns:

the user with the specified username, or null if no matching user exists or the matching user is inactive and inactive users were not requested

getServiceUserBySlug

@Nullable
ServiceUser getServiceUserBySlug(@Nonnull
                                           String slug)

Retrieves an active ServiceUser by its exact (case-sensitive) slug.

This method will not return inactive users.

Parameters:

slug - the slug of the user to retrieve

Returns:

the user with the specified slug, or null if no matching user exists or the matching user is inactive

getServiceUsersByName

@Nonnull
Set<ServiceUser> getServiceUsersByName(@Nonnull
                                                Set<String> usernames)

Retrieves a set of active ServiceUsers by their usernames.

This method will not return inactive users; use getServiceUsersByName(Set, boolean) instead if inactive users are desired.

Parameters:

usernames - the usernames of the users to retrieve

Returns:

users matching usernames from the specified set, if any

Since:

5.13

getServiceUsersByName

@Nonnull
Set<ServiceUser> getServiceUsersByName(@Nonnull
                                                Set<String> usernames,
                                                boolean inactive)

Retrieves a set of ServiceUsers by their usernames, optionally including deleted service users.

If requested, this method will return deleted users. See the class documentation for more details about what "deleted" means in this context.

Parameters:

usernames - the usernames of the users to retrieve

inactive - true if deleted and inactive users should be returned, false otherwise

Returns:

users matching usernames from the specified set, if any

Since:

5.13

getUserById

@Nullable
ApplicationUser getUserById(int id)

Retrieves a ApplicationUser by its ID.

This method will not return deleted or inactive users; use getUserById(int, boolean) instead if deleted users are desired. See the class documentation for more details about what "deleted" means in this context.

Parameters:

id - the ID of the user to retrieve

Returns:

the user with the specified ID, or null if no matching user exists

getUserById

@Nullable
ApplicationUser getUserById(int id,
                                      boolean inactive)

Retrieves a ApplicationUser by its ID.

If requested, this method will return deleted or inactive users. See the class documentation for more details about what "deleted" means in this context.

Parameters:

id - the ID of the user to retrieve

inactive - true if deleted and inactive users should be returned, false otherwise.

Returns:

the user with the specified ID, or null if no matching user exists

getUserByName

@Nullable
ApplicationUser getUserByName(@Nonnull
                                        String username)

Retrieves an active ApplicationUser by its username.

This method will not return deleted or inactive users; use getUserByName(String, boolean) instead if deleted users are desired. See the class documentation for more details about what "deleted" means in this context.

Parameters:

username - the username of the user to retrieve

Returns:

the user with the specified username, or null if no matching user exists or the matching user has been deleted from the user store

getUserByName

@Nullable
ApplicationUser getUserByName(@Nonnull
                                        String username,
                                        boolean inactive)

Retrieves a ApplicationUser by its username, optionally returning the user even if it has been removed from the underlying user store.

If requested, this method will return deleted or inactive users. See the class documentation for more details about what "deleted" means in this context.

Parameters:

username - the username of the user to retrieve

inactive - true if deleted and inactive users should be returned, false otherwise.

Returns:

the user with the specified username, or null if no matching user exists or the matching user has been deleted from the user store and deleted users were not requested

getUsersById

@Nonnull
Set<ApplicationUser> getUsersById(@Nonnull
                                           Set<Integer> ids)

Retrieves a set of active ApplicationUsers by their IDs.

This method will not return deleted or inactive users; use getUsersById(Set, boolean) instead if deleted users are desired. See the class documentation for more details about what "deleted" means in this context.

Parameters:

ids - the IDs of the users to retrieve

Returns:

a set of non-deleted users

getUsersById

@Nonnull
Set<ApplicationUser> getUsersById(@Nonnull
                                           Set<Integer> ids,
                                           boolean inactive)

Retrieves a set of ApplicationUsers by their IDs, optionally including users who have been removed from the underlying user store.

If requested, this method will return deleted users. See the class documentation for more details about what "deleted" means in this context.

Parameters:

ids - the IDs of the users to retrieve

inactive - true if deleted and inactive users should be returned, false otherwise

Returns:

users matching IDs from the specified set, if any

getUserBySlug

@Nullable
ApplicationUser getUserBySlug(@Nonnull
                                        String slug)

Retrieves an active ApplicationUser by its exact (case-sensitive) slug.

This method will not return deleted or inactive users. See the class documentation for more details about what "deleted" means in this context.

Parameters:

slug - the slug of the user to retrieve

Returns:

the user with the specified slug, or null if no matching user exists or the matching user has been deleted or is inactive

getUsersByName

@Nonnull
Set<ApplicationUser> getUsersByName(@Nonnull
                                             Set<String> usernames)

Retrieves a set of active ApplicationUsers by their usernames.

This method will not return deleted or inactive users; use getUsersByName(Set, boolean) instead if deleted users are desired. See the class documentation for more details about what "deleted" means in this context.

Parameters:

usernames - the usernames of the users to retrieve

Returns:

users matching usernames from the specified set, if any

getUsersByName

@Nonnull
Set<ApplicationUser> getUsersByName(@Nonnull
                                             Set<String> usernames,
                                             boolean inactive)

Retrieves a set of ApplicationUsers by their usernames, optionally including users who have been removed from the underlying user store.

If requested, this method will return deleted users. See the class documentation for more details about what "deleted" means in this context.

Parameters:

usernames - the usernames of the users to retrieve

inactive - true if deleted and inactive users should be returned, false otherwise

Returns:

users matching usernames from the specified set, if any

isUserActive

boolean isUserActive(@Nonnull
                     ApplicationUser user)

Retrieves the active state of the user. Returning true if the user can be found in the authoritative directory in which they're stored, and the user is active within that directory.

Parameters:

user - the user to query activity state for

Returns:

true if the user has been found and is active

Since:

4.10

isUserActive

boolean isUserActive(@Nonnull
                     ApplicationUser user,
                     boolean checkDirectory)

Retrieves the active state of the user. Returning true if the user can be found in the directory in which they're stored, and the user is active within that directory. Checks their authorative remote directory if one exists and checkDirectory is true.

Parameters:

user - the user to query activity state for

checkDirectory - whether to check the users authoriative directory to confirm their active state

Returns:

true if the user has been found and is active

Since:

4.14

isUserInGroup

boolean isUserInGroup(@Nonnull
                      ApplicationUser user,
                      @Nonnull
                      String groupName)

Retrieves a flag indicating whether the specified user is a member of the specified group. If the provided user does not exist in the user store, or if the group does not exist, false is returned in preference to throwing an exception.

Parameters:

user - the user to query group membership for

groupName - the exact name of the group to query membership in

Returns:

true if the specified user is a member of the specified group; otherwise, false if the user does not exist in the backing store, the group does not exist or the user is not a member of the group

isUserInGroup

boolean isUserInGroup(@Nonnull
                      String username,
                      @Nonnull
                      String groupName)

Retrieves a flag indicating whether the specified user is a member of the specified group. If the user or group does not exist, false is returned in preference to throwing an exception.

Parameters:

username - the exact name of the user to query group membership for

groupName - the exact name of the group to query membership in

Returns:

true if the specified user is a member of the specified group; otherwise, false if the user does not exist, the group does not exist or the user is not a member of the group

search

@Nonnull
Page<ApplicationUser> search(@Nonnull
                                      UserSearchRequest request,
                                      @Nonnull
                                      PageRequest pageRequest)

Searches for users that match the provided request.

Parameters:

request - a request object describing the users to return

pageRequest - the bounds of the page

Returns:

a page containing 0 or more users that match the provided criteria

See Also:

UserSearchRequest

updateAvatar

void updateAvatar(@Nonnull
                  ApplicationUser user,
                  @Nonnull
                  AvatarSupplier supplier)

Updates the specified user's avatar, replacing it with the one contained in the provided supplier. Updating a user's avatar also updates the avatar for their personal project.

Previous avatars are not retained. When a user's avatar is updated, the previous avatar is removed. To reuse a previous avatar, it must be provided again.

Parameters:

user - the user to update the avatar for

supplier - a supplier providing access to the new avatar to use

updateAvatar

void updateAvatar(@Nonnull
                  ApplicationUser user,
                  @Nonnull
                  String uri)

Updates the specified user's avatar, replacing it with the one contained in the provided data URI. Updating a user's avatar also updates the avatar for their personal project.

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.

Parameters:

user - the user to update the avatar for

uri - a data URI containing a Base64-encoded avatar image

updatePassword

void updatePassword(@Nonnull
                    String currentPassword,
                    @Nonnull
                    String newPassword)
             throws IncorrectPasswordAuthenticationException,
                    ServerException

Updates the password for the current user.

The current user always has permission to modify their own password. However, the underlying user store may not support the operation, or it may apply specific requirements to the complexity of the new password. If the user store is read-only, or the password does not meet complexity requirements, a ServerException is thrown.

Parameters:

currentPassword - the current user's current password

newPassword - the current user's desired new password

Throws:

IncorrectPasswordAuthenticationException - if the current password provided does not match the user's current password

ServerException - if the underlying user store does not support updating users' passwords

updateUser

@Nonnull
ApplicationUser updateUser(@Nonnull
                                    String displayName,
                                    @Nonnull
                                    String emailAddress)
                             throws ServerException

Updates the display name and e-mail address for the current user.

The current user always has permission to modify their own details. However, the underlying user store may not support the operation. A ServerException will be thrown if the user store is read-only.

Parameters:

displayName - the new display name for the current user

emailAddress - the new e-mail address for the current user

Returns:

the current user, with the updated details

Throws:

ServerException - if the underlying user store does not support updating users' details