public interface

UserService

com.atlassian.bitbucket.user.UserService

Class Overview

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

Summary

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

Public Methods

@Deprecated @Nonnull public ApplicationUser authenticate (String username, String password)

This method is deprecated.
in 5.5 for removal in 6.0. Use authenticate(String, String) instead.

Attempts to authenticate the specified user given their password. Failed authentications will not count towards the maximum number allowed before CAPTCHA is imposed for the supplied user.

Parameters
username the username
password the user's password
Returns
Throws
AuthenticationSystemException if a failure occurs in Crowd
ExpiredPasswordAuthenticationException if the user's password has expired and must be changed
InactiveUserAuthenticationException if the specified user is inactive
IncorrectPasswordAuthenticationException if the provided password is incorrect
NoSuchUserException if the specified user does not exist or their user details cannot be retrieved
See Also

@Deprecated @Nonnull public ApplicationUser authenticateWithCaptcha (String username, String password)

This method is deprecated.
in 5.5 for removal in 6.0. Use authenticateWithCaptcha(String, String) instead.

Attempts to authenticate the specified user given their password. Failed authentications will count towards the maximum number allowed before CAPTCHA is imposed for the supplied user. If the maximum number of allowed failed logins has already been exceeded the method will throw CaptchaRequiredAuthenticationException

Parameters
username the username
password the user's password
Returns
Throws
AuthenticationSystemException if a failure occurs in Crowd
CaptchaRequiredAuthenticationException if CAPTCHA is required
ExpiredPasswordAuthenticationException if the user's password has expired and must be changed
InactiveUserAuthenticationException if the specified user is inactive
IncorrectPasswordAuthenticationException if the provided password is incorrect
NoSuchUserException if the specified user does not exist or their user details cannot be retrieved
See Also

public void deleteAvatar (ApplicationUser user)

Delete the avatar associated with a user.

This will revert the avatar of the user in the UI to his/her 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

public 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

@Nonnull public Page<String> findGroups (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

@Nonnull public Page<String> findGroupsByName (String groupName, 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

@Nonnull public Page<String> findGroupsByPrefix (String groupPrefix, 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

@Nonnull public Page<String> findGroupsByUser (String username, 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

@Nullable public ApplicationUser findUserByEmail (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

@Nullable public ApplicationUser findUserByNameOrEmail (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

@Nonnull public Page<ApplicationUser> findUsers (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

@Nonnull public Page<ApplicationUser> findUsersByGroup (String groupName, 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

@Nonnull public 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. If the provided username is null, this method behaves identically to findUsers(PageRequest). Otherwise, the username is matched against:

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

@Nonnull public CacheableAvatarSupplier getAvatar (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

@Nullable public ServiceUser getServiceUserByName (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

@Nullable public ServiceUser getServiceUserByName (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

@Nullable public ServiceUser getServiceUserBySlug (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

@Nonnull public Set<ServiceUser> getServiceUsersByName (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

@Nonnull public Set<ServiceUser> getServiceUsersByName (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

@Nullable public 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

@Nullable public 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

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

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

@Nullable public ApplicationUser getUserByName (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

@Nullable public ApplicationUser getUserBySlug (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

@Nonnull public Set<ApplicationUser> getUsersById (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

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

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

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

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

@Nonnull public Set<ApplicationUser> getUsersByName (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

public boolean isUserActive (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

public boolean isUserActive (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

public boolean isUserInGroup (ApplicationUser user, 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

public boolean isUserInGroup (String username, 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

@Deprecated @Nullable public ApplicationUser preauthenticate (String username)

This method is deprecated.
in 5.5 for removal in 6.0. Use set(Authentication) instead.

Authenticate as user username, without checking passwords. Should only be used for trusted logins.

Parameters
username the username
Returns

@Nonnull public Page<ApplicationUser> search (UserSearchRequest request, 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

@Deprecated public void unauthenticate ()

This method is deprecated.
in 5.5 for removal in 6.0. Use clear() instead.

Clears the authentication for the current user, logging them out.

public void updateAvatar (ApplicationUser user, 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

public void updateAvatar (ApplicationUser user, 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

public void updatePassword (String currentPassword, String newPassword)

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

@Nonnull public ApplicationUser updateUser (String displayName, String emailAddress)

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