Package com.atlassian.jira.user.util

Interface UserManager

All Known Implementing Classes:
DefaultUserManager, MockUserManager
@PublicApi public interface UserManager
Simple user utilities that do not require an implementation with too many dependencies.
Since:
v4.0

  • Method Details

    • getTotalUserCount

      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
      Since:
      v4.0

    • getAllApplicationUsers

      @Nonnull @Deprecated Collection<ApplicationUser> getAllApplicationUsers()
      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
      Since:
      v6.0

    • listApplicationUsers

      @Nonnull Collection<ApplicationUser> listApplicationUsers(long cursor, int limit)
      Returns a collection of users defined in JIRA, starting from, but not including, the given id. The given id does not have to be a valid user id. Ordering of users is to be treated as undefined. In order to start the pagination, the first call to this method should use a cursor value of 0. In order to continue the pagination, the next call to this method should use the last id of the user returned in the previous call.
      Parameters:
      cursor - the id of the user to start after. This id does not have to be a valid user id.
      limit - the maximum number of users to return.
      Returns:
      a collection of users defined in JIRA, starting from, but not including, the given id.

    • getUserById

      Optional<ApplicationUser> getUserById(Long id)
      Returns a user based in id.
      Parameters:
      id - user id
      Returns:
      user if found or none

    • getUserByKey

      @Nullable ApplicationUser getUserByKey(@Nullable String userKey)
      Returns an ApplicationUser based on user key.
      Parameters:
      userKey - the key of the user
      Returns:
      the ApplicationUser object
      Since:
      v5.1.1

    • bulkGetUsersByKeys

      Map<String,Optional<ApplicationUser>> bulkGetUsersByKeys(@Nonnull Set<String> keys)
      Returns a map of Optional ApplicationUser objects based on a set of user keys. Missing user keys are returned as empty Optionals. This performs better on large sets of keys than iterating one by one.
      Parameters:
      keys - the set of user keys to look up. Null keys are ignored.
      Returns:
      a map of user keys to ApplicationUser objects, where the value is an Optional that is empty if the user does not exist.
      Since:
      11.0.1

    • bulkGetUsersByKeysEvenWhenUnknown

      Map<String,ApplicationUser> bulkGetUsersByKeysEvenWhenUnknown(@Nonnull Set<String> keys)
      Returns a map of ApplicationUser objects based on a set of user keys. This performs better on large sets of keys than iterating one by one. For any unknown user keys, an immutable unknown user ApplicationUser object is returned.
      Parameters:
      keys - the set of user keys to look up. Null keys are ignored.
      Returns:
      a map of user keys to ApplicationUser objects or proxy unknown immutable ApplicationUser object

    • getUserByName

      @Nullable ApplicationUser getUserByName(@Nullable 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.
      Since:
      v5.1.1

    • getUserByKeyEvenWhenUnknown

      @Nullable ApplicationUser getUserByKeyEvenWhenUnknown(@Nullable 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 if the key is null).
      Since:
      v6.0

    • getUserByNameEvenWhenUnknown

      @Nullable ApplicationUser getUserByNameEvenWhenUnknown(@Nullable 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.
      Since:
      v6.0

    • findUserInDirectory

      @Nullable ApplicationUser findUserInDirectory(@Nullable 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.
      Since:
      v4.3.2

    • canUpdateUser

      boolean canUpdateUser(@Nonnull 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.

    • userCanUpdateOwnDetails

      @ExperimentalApi boolean userCanUpdateOwnDetails(@Nonnull ApplicationUser user)
      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.
      Since:
      6.4

    • canRenameUser

      boolean canRenameUser(@Nullable 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 APKeys.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.
      Since:
      v6.0

    • updateUser

      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:
      com.atlassian.crowd.exception.runtime.UserNotFoundException - If the supplied user does not exist in the directory.
      com.atlassian.crowd.exception.runtime.OperationFailedException - If the underlying directory implementation failed to execute the operation.
      IllegalArgumentException - If something is wrong with the provided user object
      Since:
      v6.0

    • updateUserStatusLocally

      void updateUserStatusLocally(ApplicationUser user)
      Updates the ApplicationUser status. The user must have non-null names and email address.
      Parameters:
      user - The user to update.
      Throws:
      com.atlassian.crowd.exception.runtime.UserNotFoundException - If the supplied user does not exist in the directory.
      com.atlassian.crowd.exception.runtime.OperationFailedException - If the underlying directory implementation failed to execute the operation.
      IllegalArgumentException - If something is wrong with the provided user object

    • canUpdateUserPassword

      boolean canUpdateUserPassword(@Nullable 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.

    • canUpdateGroupMembershipForUser

      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.

    • getGroup

      @IncompatibleReturnType(since="5.0", was="com.opensymphony.user.User") com.atlassian.crowd.embedded.api.Group getGroup(@Nullable 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.
      Since:
      v4.0

    • getGroupObject

      com.atlassian.crowd.embedded.api.Group getGroupObject(@Nullable 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.
      Since:
      v4.3
      See Also:

    • getWritableDirectories

      @Nonnull List<com.atlassian.crowd.embedded.api.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:

    • getDefaultCreateDirectory

      @Nonnull Optional<com.atlassian.crowd.embedded.api.Directory> getDefaultCreateDirectory()
      Get the Directory in which users will be created by default
      Returns:
      Directory or Option.none() in case there is no writable directories

    • hasWritableDirectory

      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:

    • hasPasswordWritableDirectory

      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:

    • hasGroupWritableDirectory

      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:

    • canDirectoryUpdateUserPassword

      boolean canDirectoryUpdateUserPassword(@Nullable com.atlassian.crowd.embedded.api.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.

    • getDirectory

      com.atlassian.crowd.embedded.api.Directory getDirectory(Long directoryId)

    • isUserExisting

      boolean isUserExisting(@Nullable ApplicationUser user)
      Checks if given user is existing user
      Parameters:
      user - possible existing user object - i.e. received from getUserByKeyEvenWhenUnknown(String) or getUserByNameEvenWhenUnknown(String)
      Returns:
      true if given user is real user, false otherwise (also when given object is null)
      See Also:

    • isUserDeleted

      @ExperimentalApi boolean isUserDeleted(@Nullable ApplicationUser user)
      Checks if given user is deleted user. Deleted user exists in jira app_users DB table (has user key and username) but does not exist in crowd (no user data eg. Full name, email etc.).
      Parameters:
      user - possible deleted user object - i.e. received from getUserByKeyEvenWhenUnknown(String) or getUserByNameEvenWhenUnknown(String)
      Returns:
      true if given user is user existing in app_users DB table but does not exist in crowd, false otherwise (also when given object is null)
      Since:
      8.10
      See Also:

    • generateRandomPassword

      @Nonnull 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.
      Since:
      6.4

    • getUserState

      @ExperimentalApi @Nonnull UserManager.UserState getUserState(@Nonnull 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.
      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

    • getUserState

      @ExperimentalApi @Nonnull UserManager.UserState getUserState(@Nullable ApplicationUser user)
      This convenience method is equivalent to getUserState(user.getUsername(), user.getDirectoryId()) except that a null user is permitted and returns UserManager.UserState.INVALID_USER.
      Parameters:
      user - the user to check
      Returns:
      the shadowing state of the specified user

    • getDuplicatedUserMapping

      @ExperimentalApi @Nonnull DuplicatedUsersToDirectoriesMapping getDuplicatedUserMapping()
      This method returns a mapping of duplicated users to the directories they have their accounts in together with information on whether the accounts are active. Duplicated means that the user has an account in more than one directory and either more than one account is active or the only active account does not belong to the directory with the highest priority.
      Returns:
      map of users who have duplicated accounts and their directories.
      Since:
      8.19

    • createUser

      @Nonnull @ExperimentalApi ApplicationUser createUser(@Nonnull UserDetails userData) throws CreateException, PermissionException
      Creates a user in the specified directory (userDirectoryId). If the directory is Option.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.
      Since:
      v7.0

    • getUserIdentityById

      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.

    • getUserIdentityByKey

      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.

    • getUserIdentityByUsername

      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.

    • isInternalUserStatusSupported

      boolean isInternalUserStatusSupported(long directoryId)
      Returns whether or not the directory with given id supports local status management.
      Parameters:
      directoryId - the directory id to check
      Returns:
      true if the specified directory exists and support local status management false otherwise
      Since:
      v10.4

    • isExternalUserRemovableInternally

      boolean isExternalUserRemovableInternally(ApplicationUser user)
      Returns whether or not the user can be removed internally based on deleted_externally flag. Requires com.atlassian.jira.user.allowDeleteExternallyDeletedUsers feature flag enabled.
      Parameters:
      user - the user to check
      Returns:
      true if the specified user is marked as deleted externally false otherwise
      Since:
      v10.5