@PublicApi public interface

UserManager

com.atlassian.jira.user.util.UserManager
Known Indirect Subclasses

@PublicApi

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

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

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

Class Overview

Simple user utilities that do not require an implementation with too many dependencies.

Summary

Nested Classes
enum UserManager.UserState The current state of a user with regard to the same username existing in other user directories. 
Public Methods
boolean canDirectoryUpdateUserPassword(Directory directory)
Checks if the given directory is able to update user passwords.
boolean canRenameUser(ApplicationUser user)
Test if this user can be renamed.
boolean canUpdateGroupMembershipForUser(ApplicationUser user)
Test if this user's group membership can be updated, i.e.
boolean canUpdateUser(ApplicationUser user)
Test if this user can be updated, i.e.
boolean canUpdateUserPassword(ApplicationUser user)
Test if this user's password can be updated, i.e.
@Nonnull @ExperimentalApi ApplicationUser createUser(UserDetails userData)
Creates a user in the specified directory (userDirectoryId).
@Nullable ApplicationUser findUserInDirectory(String userName, Long directoryId)
Returns a User based on user name and directoryId
@Nonnull String generateRandomPassword()
Generates a random password that can be used when the admin has entered a blank password.
@Nonnull @Deprecated Collection<ApplicationUser> getAllApplicationUsers()
This method is deprecated. Since v7.0. Only retrieve the users you really need. See UserSearchService
@IncompatibleReturnType @Deprecated Set<Group> getAllGroups()
This method is deprecated. Since v7.0. Only retrieve the groups you really need. See GroupPickerSearchService
@Nonnull @Deprecated Set<ApplicationUser> getAllUsers()
This method is deprecated. Since v7.0. Only retrieve the users you really need. See UserSearchService
@Nonnull Optional<Directory> getDefaultCreateDirectory()
Get the Directory in which users will be created by default
Directory getDirectory(Long directoryId)
@IncompatibleReturnType Group getGroup(String groupName)
Returns a Group based on user name.
Group getGroupObject(String groupName)
Returns a Group based on user name.
@Deprecated Collection<Group> getGroups()
This method is deprecated. Since v7.0. Only retrieve the users you really need. See GroupPickerSearchService
int getTotalUserCount()
Returns the total number of users defined in JIRA, regardless of whether they are active or not.
ApplicationUser getUser(String userName)
This method is deprecated. Use getUserByKey(String) or getUserByName(String) instead. Since v6.0.
Optional<ApplicationUser> getUserById(Long id)
Returns a user based in id.
@Nullable ApplicationUser getUserByKey(String userKey)
Returns an ApplicationUser based on user key.
@Nullable ApplicationUser getUserByKeyEvenWhenUnknown(String userKey)
Returns an ApplicationUser based on user key.
@Nullable ApplicationUser getUserByName(String userName)
Returns an ApplicationUser based on user name.
@Nullable ApplicationUser getUserByNameEvenWhenUnknown(String userName)
Returns an ApplicationUser based on user name.
@Nullable ApplicationUser getUserEvenWhenUnknown(String userName)
This method is deprecated. Use getUserByKeyEvenWhenUnknown(String) or getUserByNameEvenWhenUnknown(String) instead. Since v6.0.
Optional<UserIdentity> getUserIdentityById(Long id)
Returns an identity of the user with the specified id.
Optional<UserIdentity> getUserIdentityByKey(String key)
Returns an identity of the user with the specified key.
Optional<UserIdentity> getUserIdentityByUsername(String username)
Returns an identity of the user with the specified username.
ApplicationUser getUserObject(String userName)
This method is deprecated. Use getUserByKey(String) or getUserByName(String) instead. Since v6.0.
@ExperimentalApi @Nonnull UserManager.UserState getUserState(ApplicationUser user)
This convenience method is equivalent to getUserState(user.getUsername(), user.getDirectoryId()) except that a null user is permitted and returns INVALID_USER.
@ExperimentalApi @Nonnull UserManager.UserState getUserState(String username, long directoryId)
Checks for the existence of this user across all directories to determine whether or not the user exists in the specified directory and whether or not it is shadowing or shadowed by a user with the same username in another active user directory.
@Nonnull @Deprecated Collection<ApplicationUser> getUsers()
This method is deprecated. Since v7.0. Only retrieve the users you really need. See UserSearchService
@Nonnull List<Directory> getWritableDirectories()
Returns an ordered list of directories that have "read-write" permission.
boolean hasGroupWritableDirectory()
Returns true if any of the directories have permission to update groups.
boolean hasPasswordWritableDirectory()
Returns true if any of the directories have permission to update user passwords, false if otherwise.
boolean hasWritableDirectory()
Returns true if at least one User Directory has "read-write" permission.
boolean isUserExisting(ApplicationUser user)
Checks if given user is existing user
void updateUser(ApplicationUser user)
Updates the ApplicationUser.
@ExperimentalApi boolean userCanUpdateOwnDetails(ApplicationUser user)
Check if this user is allowed to update their own user details.

Public Methods

public boolean canDirectoryUpdateUserPassword (Directory directory)

Checks if the given directory is able to update user passwords.

Parameters
directory the Directory
Returns
  • true if the directory can update user passwords, false if otherwise.

public boolean canRenameUser (ApplicationUser user)

Test if this user can be renamed. In addition to the constraints of canUpdateUser(ApplicationUser), renaming a user is only allowed when:

  1. The user is in either an INTERNAL or DELEGATING user directory; AND
  2. Either JIRA is not configured as a crowd server, or JIRA_OPTION_USER_CROWD_ALLOW_RENAME is enabled to bypass this check.

Parameters
user The user to rename.
Returns
  • true if the user is not null and can be renamed.

public boolean canUpdateGroupMembershipForUser (ApplicationUser user)

Test if this user's group membership can be updated, i.e. is in a writable directory or a directory with Local Group support. This relies upon the local directory configuration and does not guarantee that the actual remote directory, e.g. the remote LDAP directory, will actually allow the user membership to be updated.

Parameters
user The user to update.
Returns
  • true if the user is not null and can be updated.

public boolean canUpdateUser (ApplicationUser user)

Test if this user can be updated, i.e. is in a writable directory. This relies upon the local directory configuration and does not guarantee that the actual remote directory, e.g. the remote LDAP directory, will actually allow the user to be updated.

Parameters
user The user to update.
Returns
  • true if the user can be updated.

public boolean canUpdateUserPassword (ApplicationUser user)

Test if this user's password can be updated, i.e. is in a writable directory which is not a Delegated LDAP directory. This relies upon the local directory configuration and does not guarantee that the actual remote directory, e.g. the remote LDAP directory, will actually allow the user to be updated.

If the "External user management", or "External password management" setting is on, then you cannot update the password.

Parameters
user The user to update.
Returns
  • true if the user is not null and the user's password can be updated.

@Nonnull @ExperimentalApi public ApplicationUser createUser (UserDetails userData)

@ExperimentalApi

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

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

Creates a user in the specified directory (userDirectoryId). If the directory is none(), the user is created in the default directory (usually an Embedded Crowd internal directory).

Parameters
userData the user request containing user details.
Returns
  • the newly created user.
Throws
CreateException unable to create user.
PermissionException unable to create user due to permission error.

@Nullable public ApplicationUser findUserInDirectory (String userName, Long directoryId)

Returns a User based on user name and directoryId

Parameters
userName the user name of the user
directoryId the Directory to look in
Returns
  • the User object, or null if the user cannot be found including null userName.

@Nonnull public String generateRandomPassword ()

Generates a random password that can be used when the admin has entered a blank password.

The password is guaranteed to contain at least one upper-case letter, lower-case letter and number in case the backend user Directory has password restrictions.

Returns
  • a random password.

@Nonnull @Deprecated public Collection<ApplicationUser> getAllApplicationUsers ()

This method is deprecated.
Since v7.0. Only retrieve the users you really need. See UserSearchService

Returns all users defined in JIRA, regardless of whether they are active or not.

Returns
  • the set of all users

@IncompatibleReturnType @Deprecated public Set<Group> getAllGroups ()

This method is deprecated.
Since v7.0. Only retrieve the groups you really need. See GroupPickerSearchService

Returns all groups defined in JIRA.

Warning: previous incarnations of this method returned com.opensymphony.user.User. This class has now been removed from the JIRA API, meaning that the 5.0 version is not binary or source compatible with earlier versions.

Returns
  • the set of all groups

@Nonnull @Deprecated public Set<ApplicationUser> getAllUsers ()

This method is deprecated.
Since v7.0. Only retrieve the users you really need. See UserSearchService

Returns all users defined in JIRA, regardless of whether they are active or not.

Returns
  • the set of all users

@Nonnull public Optional<Directory> getDefaultCreateDirectory ()

Get the Directory in which users will be created by default

Returns

public Directory getDirectory (Long directoryId)

@IncompatibleReturnType public Group getGroup (String groupName)

Returns a Group based on user name.

Warning: previous incarnations of this method returned com.opensymphony.user.User. This class has now been removed from the JIRA API, meaning that the 5.0 version is not binary or source compatible with earlier versions.

Parameters
groupName the user name of the group
Returns
  • the Group object, or null if the group cannot be found including null groupName.

public Group getGroupObject (String groupName)

Returns a Group based on user name.

Legacy synonym for getGroup(String).

Parameters
groupName the user name of the group
Returns
  • the Group object, or null if the group cannot be found including null groupName.
See Also

@Deprecated public Collection<Group> getGroups ()

This method is deprecated.
Since v7.0. Only retrieve the users you really need. See GroupPickerSearchService

Returns all groups defined in JIRA.

Legacy synonym for getAllGroups().

Returns
  • the set of all groups
See Also

public int getTotalUserCount ()

Returns the total number of users defined in JIRA, regardless of whether they are active or not.

Returns
  • the total number of users defined in JIRA

public ApplicationUser getUser (String userName)

This method is deprecated.
Use getUserByKey(String) or getUserByName(String) instead. Since v6.0.

Returns a User based on user name.

Parameters
userName the user name of the user
Returns
  • the User object, or null if the user cannot be found including null userName.

public Optional<ApplicationUser> getUserById (Long id)

Returns a user based in id.

Parameters
id user id
Returns
  • user if found or none

@Nullable public ApplicationUser getUserByKey (String userKey)

Returns an ApplicationUser based on user key.

Parameters
userKey the key of the user
Returns
  • the ApplicationUser object

@Nullable public ApplicationUser getUserByKeyEvenWhenUnknown (String userKey)

Returns an ApplicationUser based on user key.

If you want to check if given user is known user - please use isUserExisting(com.atlassian.jira.user.ApplicationUser)

Parameters
userKey the key of the user
Returns
  • the ApplicationUser object, or proxy unknown immutable ApplicationUser object (null iff the key is null).

@Nullable public ApplicationUser getUserByName (String userName)

Returns an ApplicationUser based on user name.

Parameters
userName the user name of the user
Returns
  • the ApplicationUser object
Throws
IllegalStateException if the CrowdService is able to resolve userName to a User, but the UserKeyService does not have a key mapped for it. This is not a valid configuration.

@Nullable public ApplicationUser getUserByNameEvenWhenUnknown (String userName)

Returns an ApplicationUser based on user name.

If you want to check if given user is known user - please use isUserExisting(com.atlassian.jira.user.ApplicationUser)

Parameters
userName the user name of the user
Returns
  • the ApplicationUser object, or proxy unknown immutable ApplicationUser object (null iff the username is null).
Throws
IllegalStateException if the CrowdService is able to resolve userName to a User, but the UserKeyService does not have a key mapped for it. This is not a valid configuration.

@Nullable public ApplicationUser getUserEvenWhenUnknown (String userName)

This method is deprecated.
Use getUserByKeyEvenWhenUnknown(String) or getUserByNameEvenWhenUnknown(String) instead. Since v6.0.

Returns a User based on user name.

If a null username is passed, then a null User object is returned, but it is guaranteed to return a non-null User in all other cases.
If the username is not null, but the User is not found then a proxy unknown immutable User object is returned.

Parameters
userName the user name of the user
Returns
  • the User object, or proxy unknown immutable User object (null iff the username is null).

public Optional<UserIdentity> getUserIdentityById (Long id)

Returns an identity of the user with the specified id.

Parameters
id user id
Returns
  • user identity or none if no user with the specified key exists.

public Optional<UserIdentity> getUserIdentityByKey (String key)

Returns an identity of the user with the specified key.

Parameters
key user key
Returns
  • user identity or none if no user with the specified key exists.

public Optional<UserIdentity> getUserIdentityByUsername (String username)

Returns an identity of the user with the specified username.

Parameters
username user name
Returns
  • user identity or none if no user with the specified username exists.

public ApplicationUser getUserObject (String userName)

This method is deprecated.
Use getUserByKey(String) or getUserByName(String) instead. Since v6.0.

Returns a User based on user name.

Parameters
userName the user name of the user
Returns
  • the User object, or null if the user cannot be found including null userName.

@ExperimentalApi @Nonnull public UserManager.UserState getUserState (ApplicationUser user)

@ExperimentalApi

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

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

This convenience method is equivalent to getUserState(user.getUsername(), user.getDirectoryId()) except that a null user is permitted and returns INVALID_USER.

Parameters
user the user to check
Returns
  • the shadowing state of the specified user

@ExperimentalApi @Nonnull public UserManager.UserState getUserState (String username, long directoryId)

@ExperimentalApi

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

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

Checks for the existence of this user across all directories to determine whether or not the user exists in the specified directory and whether or not it is shadowing or shadowed by a user with the same username in another active user directory.

Parameters
username the username to check
directoryId the directory ID of the user directory that the user came from
Returns
  • the shadowing state of the specified user

@Nonnull @Deprecated public Collection<ApplicationUser> getUsers ()

This method is deprecated.
Since v7.0. Only retrieve the users you really need. See UserSearchService

Returns all users defined in JIRA, regardless of whether they are active or not.

Legacy synonym for getAllUsers().

Returns
  • the collection of all users
See Also

@Nonnull public List<Directory> getWritableDirectories ()

Returns an ordered list of directories that have "read-write" permission. ie those directories that we can add a user to.

Returns
  • an ordered list of directories that have "read-write" permission.
See Also

public boolean hasGroupWritableDirectory ()

Returns true if any of the directories have permission to update groups.

Note that this will not always return the same results as hasWritableDirectory() because you can set "Read-Only with Local Groups" to LDAP directories. These directories are generally read-only but you can create local gropus and assign users to them.

Returns
  • true if any of the directories have permission to update groups, false if otherwise.
See Also

public boolean hasPasswordWritableDirectory ()

Returns true if any of the directories have permission to update user passwords, false if otherwise.

Note that this is not quite the same as hasWritableDirectory() because of "Internal with LDAP Authentication" directories. These directories are generally read-write but passwords are read-only.

Returns
  • true if any of the directories have permission to update user passwords, false if otherwise.
See Also

public boolean hasWritableDirectory ()

Returns true if at least one User Directory has "read-write" permission.

This is equivalent to:
  getWritableDirectories().size() > 0

Returns
  • true if at least one User Directory has "read-write" permission.
See Also

public boolean isUserExisting (ApplicationUser user)

Checks if given user is existing user

Parameters
user possible existing user object - i.e. recieved from getUserByKeyEvenWhenUnknown(String) or getUserByNameEvenWhenUnknown(String)
Returns
  • true if given user is real user, false otherwise (also when given object is null)
See Also

public void updateUser (ApplicationUser user)

Updates the ApplicationUser. The user must have non-null names and email address. If the user's name does not match the name that is currently associated with the key, then this is implicitly treated as a request to rename the user.

Parameters
user The user to update.
Throws
UserNotFoundException If the supplied user does not exist in the directory.
OperationFailedException If the underlying directory implementation failed to execute the operation.
IllegalArgumentException If something is wrong with the provided user object

@ExperimentalApi public boolean userCanUpdateOwnDetails (ApplicationUser user)

@ExperimentalApi

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

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

Check if this user is allowed to update their own user details.

Returns true if the given user is in a read-write directory AND the "External user management" setting is off.

Parameters
user The user
Returns
  • true if the given user is in a read-write directory AND the "External user management" setting is off.