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

  • Method Details

    • 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

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

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

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

    • 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

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

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

    • 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

    • getSystemServiceUser

      @Nonnull ServiceUser getSystemServiceUser()
      Retrieves the service user used for system activity.
      Returns:
      the system service user
      Since:
      9.0

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

    • 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

      @Deprecated @Nonnull ApplicationUser updateUser(@Nonnull String displayName, @Nonnull String emailAddress) throws ServerException
      Deprecated.
      in 9.4 for removal in 10.0. Use updateUser(String, String, String) instead.
      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

    • updateUser

      @Nonnull ApplicationUser updateUser(@Nonnull String displayName, @Nonnull String emailAddress, @Nullable String currentPassword) throws IncorrectPasswordAuthenticationException, 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.

      When updating the email address, the user's current password also needs to be provided, unless the StandardFeature.ENFORCE_PASSWORD_USER_EMAIL_UPDATE feature is disabled.

      Parameters:
      displayName - the new display name for the current user
      emailAddress - the new e-mail address for the current user
      currentPassword - the current user's current password
      Returns:
      the current user, with the updated details
      Throws:
      IncorrectPasswordAuthenticationException - if the system requires users to provide their password when updating their email, and the password provided does not match the user's current password
      ArgumentValidationException - if the user's current password was required, but not provided
      ServerException - if the underlying user store does not support updating users' passwords
      Since:
      9.4