public interface

UserService

com.atlassian.stash.user.UserService

Class Overview

Provides methods for querying users and managing authentication. 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 into Stash and may or may not have an associated StashUser. Inactive users are handled consistently as deleted and both are taken into consideration when determining isActive().

See Also

Summary

Public Methods
StashUser authenticate(String username, String password)
Attempts to authenticate the specified user given their password.
void deleteAvatar(StashUser 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 StashUser findUserByNameOrEmail(String value)
Retrieve the first active normal user whose username or e-mail address exactly matches the provided value.
@Nonnull Page<? extends StashUser> findUsers(PageRequest pageRequest)
Retrieves a page of active normal users.
@Nonnull Page<? extends StashUser> findUsersByGroup(String groupName, PageRequest pageRequest)
Retrieves a page of active users which are members of the specified group.
@Nonnull Page<? extends StashUser> 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(StashUser user, int size)
Retrieves the current avatar for the specified user at a requested size.
@Nullable StashUser getUserById(int id, boolean inactive)
Retrieves a StashUser by its ID.
@Nullable StashUser getUserById(int id)
Retrieves a StashUser by its ID.
@Nullable StashUser getUserByName(String username)
Retrieves an active StashUser by its username.
@Nullable StashUser getUserByName(String username, boolean inactive)
Retrieves a StashUser by its username, optionally returning the user even if it has been removed from the underlying user store.
@Nullable StashUser getUserBySlug(String slug)
Retrieves an active StashUser by its exact (case-sensitive) slug.
@Deprecated @Nonnull Set<? extends StashUser> getUsersById(Set<Integer> ids)
This method is deprecated. in 3.5, this method will be retained in 4.0 with the return type changed to Set<StashUser>. The upper bounded wildcard will be removed.
@Deprecated @Nonnull Set<? extends StashUser> getUsersById(Set<Integer> ids, boolean inactive)
This method is deprecated. in 3.5, this method will be retained in 4.0 with the return type changed to Set<StashUser>. The upper bounded wildcard will be removed.
@Nonnull Set<? extends StashUser> getUsersByName(Set<String> usernames, boolean inactive)
Retrieves a set of StashUsers by their usernames, optionally including users who have been removed from the underlying user store.
@Nonnull Set<? extends StashUser> getUsersByName(Set<String> usernames)
Retrieves a set of active StashUsers by their usernames.
boolean isUserInGroup(String username, String groupName)
Retrieves a flag indicating whether the specified user is a member of the specified group.
boolean isUserInGroup(StashUser user, String groupName)
Retrieves a flag indicating whether the specified user is a member of the specified group.
@Nullable StashUser preauthenticate(String username)
Authenticate as user username, without checking passwords.
@Nonnull Page<StashUser> search(UserSearchRequest request, PageRequest pageRequest)
Searches for users that match the provided request.
void unauthenticate()
Clears the authentication for the current user, logging them out.
void updateAvatar(StashUser user, AvatarSupplier supplier)
Updates the specified user's avatar, replacing it with the one contained in the provided supplier.
void updateAvatar(StashUser 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.
@Nonnull StashUser updateUser(String displayName, String emailAddress)
Updates the display name and e-mail address for the current user.

Public Methods

public StashUser authenticate (String username, String password)

Attempts to authenticate the specified user given their password.

Parameters
username the username
password the user's password
Returns
  • the StashUser representing the authenticated user
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

public void deleteAvatar (StashUser 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 StashUser 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<? extends StashUser> 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<? extends StashUser> 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<? extends StashUser> 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 (StashUser 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 StashUser getUserById (int id, boolean inactive)

Retrieves a StashUser 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 StashUser getUserById (int id)

Retrieves a StashUser 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 StashUser getUserByName (String username)

Retrieves an active StashUser 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 exact 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 StashUser getUserByName (String username, boolean inactive)

Retrieves a StashUser 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 exact 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 StashUser getUserBySlug (String slug)

Retrieves an active StashUser 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 exact 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

@Deprecated @Nonnull public Set<? extends StashUser> getUsersById (Set<Integer> ids)

This method is deprecated.
in 3.5, this method will be retained in 4.0 with the return type changed to Set<StashUser>. The upper bounded wildcard will be removed.

Retrieves a set of active StashUsers 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

@Deprecated @Nonnull public Set<? extends StashUser> getUsersById (Set<Integer> ids, boolean inactive)

This method is deprecated.
in 3.5, this method will be retained in 4.0 with the return type changed to Set<StashUser>. The upper bounded wildcard will be removed.

Retrieves a set of StashUsers 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<? extends StashUser> getUsersByName (Set<String> usernames, boolean inactive)

Retrieves a set of StashUsers 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 exact 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<? extends StashUser> getUsersByName (Set<String> usernames)

Retrieves a set of active StashUsers 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 exact usernames of the users to retrieve
Returns
  • users matching usernames from the specified set, if any

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

public boolean isUserInGroup (StashUser 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

@Nullable public StashUser preauthenticate (String username)

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

Parameters
username the username
Returns
  • the StashUser representing the authenticated user.

@Nonnull public Page<StashUser> 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

public void unauthenticate ()

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

public void updateAvatar (StashUser 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 updateAvatar (StashUser 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 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 StashUser 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