com.atlassian.jira.user.util
Interface UserUtil

All Known Implementing Classes:
UserUtilImpl

public interface UserUtil

This is a back end service level interface that defines an API for user level operations.


Nested Class Summary
static interface UserUtil.PasswordResetToken
           
static interface UserUtil.PasswordResetTokenValidation
           
 
Field Summary
static String META_PROPERTY_PREFIX
           
 
Method Summary
 void addToJiraUsePermission(com.atlassian.crowd.embedded.api.User user)
          Takes the given user and adds him/her to all the groups that grant a user the global JIRA use permission.
 void addUserToGroup(com.atlassian.crowd.embedded.api.Group group, com.atlassian.crowd.embedded.api.User userToAdd)
          This is used to add a specified user to a specified group.
 void addUserToGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups, com.atlassian.crowd.embedded.api.User userToAdd)
          This is used to add a user to many groups at once.
 boolean canActivateNumberOfUsers(int numUsers)
          Returns true if, after adding the specified number of users, the number of active users in JIRA does not exceed the user limit allowed by the license.
 boolean canActivateUsers(Collection<String> userNames)
          Returns true if, after adding the specified users, the number of active users in JIRA does not exceed the user limit allowed by the license.
 void changePassword(com.atlassian.crowd.embedded.api.User user, String newPassword)
          Can be called to set the password for a user.
 void clearActiveUserCount()
          Clears the cache of the active user count so that it can be recalculated.
 com.atlassian.crowd.embedded.api.User createUserNoNotification(String username, String password, String emailAddress, String displayName)
          Creates a User from supplied details.
 com.atlassian.crowd.embedded.api.User createUserNoNotification(String username, String password, String emailAddress, String displayName, Long directoryId)
          Creates a User from supplied details.
 com.atlassian.crowd.embedded.api.User createUserWithNotification(String username, String password, String email, String fullname, int userEventType)
          Creates a User from supplied details.
 com.atlassian.crowd.embedded.api.User createUserWithNotification(String username, String password, String email, String fullname, Long directoryId, int userEventType)
          Creates a User from supplied details.
 UserUtil.PasswordResetToken generatePasswordResetToken(com.atlassian.crowd.embedded.api.User user)
          This is used to generate a reset password token that last a certain time and allows a person to access a page anonymously so they can reset their password.
 int getActiveUserCount()
          Returns the number of users that are currently 'active'.
 Collection<com.atlassian.crowd.embedded.api.User> getAdministrators()
          Deprecated. Since v4.3. Use getJiraAdministrators().
 Set<com.atlassian.crowd.embedded.api.User> getAllUsers()
          Deprecated. Since v4.3. Use getUsers().
 SortedSet<com.atlassian.crowd.embedded.api.User> getAllUsersInGroupNames(Collection<String> groupNames)
          Returns a collection of User objects that belong to any of the passed in collection of group names.
 Set<com.atlassian.crowd.embedded.api.User> getAllUsersInGroupNamesUnsorted(Collection<String> groupNames)
          Returns a collection of User objects that belong to any of the passed in collection of group names.
 SortedSet<com.atlassian.crowd.embedded.api.User> getAllUsersInGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups)
          Returns a collection of User objects that are found within the passed in collection of Group objects.
 Collection<ProjectComponent> getComponentsUserLeads(com.atlassian.crowd.embedded.api.User user)
          Retrieve a collection of ProjectComponents - where the lead of each component is the specified user.
 String getDisplayableNameSafely(com.atlassian.crowd.embedded.api.User user)
          Takes the given user and returns a "displayable name" by cautiously checking the different edge cases for users.
 com.atlassian.crowd.embedded.api.Group getGroup(String groupName)
          Deprecated. Since v4.3. Use getGroupObject(String).
 SortedSet<String> getGroupNamesForUser(String userName)
          Returns a collection of the names of the groups that the user belongs to.
 com.atlassian.crowd.embedded.api.Group getGroupObject(String groupName)
          Returns a Group based on user name.
 SortedSet<com.atlassian.crowd.embedded.api.Group> getGroupsForUser(String userName)
          Returns a collection of Group objects that the user belongs to.
 Collection<com.atlassian.crowd.embedded.api.User> getJiraAdministrators()
          Returns a list of JIRA admin Users.
 Collection<com.atlassian.crowd.embedded.api.User> getJiraSystemAdministrators()
          Returns a list of JIRA system admin Users.
 long getNumberOfAssignedIssuesIgnoreSecurity(com.atlassian.crowd.embedded.api.User loggedInUser, com.atlassian.crowd.embedded.api.User user)
          Returns number of issues assigned to user
 long getNumberOfReportedIssuesIgnoreSecurity(com.atlassian.crowd.embedded.api.User loggedInUser, com.atlassian.crowd.embedded.api.User user)
          Returns number of issues reported by user
 Collection<Project> getProjectsLeadBy(com.atlassian.crowd.embedded.api.User user)
          Returns all the projects that leadUser is the project lead for.
 Collection<com.atlassian.crowd.embedded.api.User> getSystemAdministrators()
          Deprecated. Since v4.3. Use getJiraSystemAdministrators() .
 int getTotalUserCount()
          Returns the total number of users defined in JIRA, regardless of whether they are active or not.
 com.atlassian.crowd.embedded.api.User getUser(String userName)
          Returns a user based on user name.
 com.atlassian.crowd.embedded.api.User getUserObject(String userName)
          Returns a user based on user name.
 Collection<com.atlassian.crowd.embedded.api.User> getUsers()
          Returns the all users defined in JIRA, regardless of whether they are active or not.
 SortedSet<com.atlassian.crowd.embedded.api.User> getUsersInGroupNames(Collection<String> groupNames)
          Deprecated. Use getAllUsersInGroupNames(java.util.Collection) instead. Since v4.3
 SortedSet<com.atlassian.crowd.embedded.api.User> getUsersInGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups)
          Deprecated. Use getAllUsersInGroups(java.util.Collection) instead. Since v4.3
 boolean hasExceededUserLimit()
          Returns true if this JIRA instance has more active users, than allowed by the license.
 boolean isNonSysAdminAttemptingToDeleteSysAdmin(com.atlassian.crowd.embedded.api.User loggedInUser, com.atlassian.crowd.embedded.api.User user)
          Checking if user without SYSTEM_ADMIN rights tries to remove user with SYSTEM_ADMIN rights.
 void removeUser(com.atlassian.crowd.embedded.api.User loggedInUser, com.atlassian.crowd.embedded.api.User user)
          This will remove the user and removes the user from all the groups.
 void removeUserFromGroup(com.atlassian.crowd.embedded.api.Group group, com.atlassian.crowd.embedded.api.User userToRemove)
          This is used to remove a specified user from a specified group.
 void removeUserFromGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups, com.atlassian.crowd.embedded.api.User userToRemove)
          This is used to remove a user from many groups at once.
 boolean userExists(String userName)
          Returns true if the a user exists with the specified userName
 UserUtil.PasswordResetTokenValidation validatePasswordResetToken(com.atlassian.crowd.embedded.api.User user, String token)
          This can be called to validate a token against the user.
 

Field Detail

META_PROPERTY_PREFIX

static final String META_PROPERTY_PREFIX
See Also:
Constant Field Values
Method Detail

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

getAllUsers

@NotNull
Set<com.atlassian.crowd.embedded.api.User> getAllUsers()
Deprecated. Since v4.3. Use getUsers().

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

WARNING: This method will be changed in the future to return a set of Crowd User objects. Since v4.3.

Returns:
the set of all users defined in JIRA
Since:
v4.0

getUsers

@NotNull
Collection<com.atlassian.crowd.embedded.api.User> getUsers()
Returns the all users defined in JIRA, regardless of whether they are active or not.

WARNING: This method will be changed in the future to return a set of Crowd User objects. Since v4.3.

Returns:
the set of all users defined in JIRA
Since:
v4.3

getGroup

com.atlassian.crowd.embedded.api.Group getGroup(@Nullable
                                                String groupName)
Deprecated. Since v4.3. Use getGroupObject(String).

Returns a Group based on user name.

WARNING: This method will be changed in the future to return a Crowd Group object. Since v4.3.

Parameters:
groupName - the user name of the group
Returns:
the Group object, or null if the user 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.

WARNING: This method will be changed in the future to return a Crowd Group object. Since v4.3.

Parameters:
groupName - the user name of the group
Returns:
the Group object, or null if the user cannot be found including null groupName.
Since:
v4.3

createUserWithNotification

com.atlassian.crowd.embedded.api.User createUserWithNotification(String username,
                                                                 String password,
                                                                 String email,
                                                                 String fullname,
                                                                 int userEventType)
                                                                 throws PermissionException,
                                                                        CreateException
Creates a User from supplied details.

Email notification will be send to created user.

Parameters:
username - The username of the new user. Needs to be lowercase and unique.
password - The password for the new user.
email - The email for the new user. Needs to be a valid email address.
fullname - The full name for the new user
userEventType - The event type dispatched on user creation
Returns:
The new user object that was created
Throws:
PermissionException - If the operation was not permitted.
CreateException
Since:
4.3

createUserWithNotification

com.atlassian.crowd.embedded.api.User createUserWithNotification(String username,
                                                                 String password,
                                                                 String email,
                                                                 String fullname,
                                                                 Long directoryId,
                                                                 int userEventType)
                                                                 throws PermissionException,
                                                                        CreateException
Creates a User from supplied details.

Email notification will be send to created user.

Parameters:
username - The username of the new user. Needs to be lowercase and unique.
password - The password for the new user.
email - The email for the new user. Needs to be a valid email address.
fullname - The full name for the new user
directoryId - The directory to create the user in. Null means "first writable directory".
userEventType - The event type dispatched on user creation
Returns:
The new user object that was created
Throws:
PermissionException - If the operation was not permitted.
CreateException
Since:
4.3.2

createUserNoNotification

com.atlassian.crowd.embedded.api.User createUserNoNotification(String username,
                                                               String password,
                                                               String emailAddress,
                                                               String displayName)
                                                               throws PermissionException,
                                                                      CreateException
Creates a User from supplied details.

No email notification will be send to created user.

Parameters:
username - The username of the new user. Needs to be lowercase and unique.
password - The password for the new user.
emailAddress - The email for the new user. Needs to be a valid email address.
displayName - The display name for the new user
Returns:
The new user object that was created
Throws:
PermissionException - If the operation was not permitted.
CreateException
Since:
4.3

createUserNoNotification

com.atlassian.crowd.embedded.api.User createUserNoNotification(String username,
                                                               String password,
                                                               String emailAddress,
                                                               String displayName,
                                                               Long directoryId)
                                                               throws PermissionException,
                                                                      CreateException
Creates a User from supplied details.

No email notification will be send to created user.

Parameters:
username - The username of the new user. Needs to be lowercase and unique.
password - The password for the new user.
emailAddress - The email for the new user. Needs to be a valid email address.
displayName - The display name for the new user
directoryId - The directory to create the user in. Null means "first writable directory".
Returns:
The new user object that was created
Throws:
PermissionException - If the operation was not permitted.
CreateException
Since:
4.3.2

removeUser

void removeUser(com.atlassian.crowd.embedded.api.User loggedInUser,
                com.atlassian.crowd.embedded.api.User user)
This will remove the user and removes the user from all the groups. All components lead by user will have lead cleared.

Parameters:
loggedInUser - the user performing operation
user - the user to delete

addUserToGroup

void addUserToGroup(com.atlassian.crowd.embedded.api.Group group,
                    com.atlassian.crowd.embedded.api.User userToAdd)
                    throws PermissionException,
                           AddException
This is used to add a specified user to a specified group. The user will be added to the group if the user is not already a member of the group.

Parameters:
group - the group to add the user to.
userToAdd - the user to add to the group.
Throws:
PermissionException
AddException

addUserToGroups

void addUserToGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups,
                     com.atlassian.crowd.embedded.api.User userToAdd)
                     throws PermissionException,
                            AddException
This is used to add a user to many groups at once.

Parameters:
groups - a list containing the groups to add the user to.
userToAdd - the user to add to the group.
Throws:
PermissionException
AddException

removeUserFromGroup

void removeUserFromGroup(com.atlassian.crowd.embedded.api.Group group,
                         com.atlassian.crowd.embedded.api.User userToRemove)
                         throws PermissionException,
                                RemoveException
This is used to remove a specified user from a specified group. The user will be removed from the group only if the user is already a member of the group.

Parameters:
group - the group to add the user to.
userToRemove - the user to add to the group.
Throws:
PermissionException
RemoveException

removeUserFromGroups

void removeUserFromGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups,
                          com.atlassian.crowd.embedded.api.User userToRemove)
                          throws PermissionException,
                                 RemoveException
This is used to remove a user from many groups at once.

Parameters:
groups - a list containing the groups to add the user to.
userToRemove - the user to add to the group.
Throws:
PermissionException
RemoveException

generatePasswordResetToken

UserUtil.PasswordResetToken generatePasswordResetToken(com.atlassian.crowd.embedded.api.User user)
This is used to generate a reset password token that last a certain time and allows a person to access a page anonymously so they can reset their password.

The generated token will be associated with the named user so that that this information can be verified at a later time.

Parameters:
user - the user in question. This MUST not be null
Returns:
a newly generated token that will live for a certain time

validatePasswordResetToken

UserUtil.PasswordResetTokenValidation validatePasswordResetToken(com.atlassian.crowd.embedded.api.User user,
                                                                 String token)
This can be called to validate a token against the user.

Parameters:
user - the user in play
token - the token they provided
Returns:
a Validation object that describes how the option went

changePassword

void changePassword(com.atlassian.crowd.embedded.api.User user,
                    String newPassword)
                    throws com.atlassian.crowd.exception.UserNotFoundException,
                           com.atlassian.crowd.exception.InvalidCredentialException,
                           com.atlassian.crowd.exception.OperationNotPermittedException,
                           PermissionException
Can be called to set the password for a user. This will delete any password request tokens associated with that user

Parameters:
user - the user in play
newPassword - their new password
Throws:
com.atlassian.crowd.exception.UserNotFoundException - if the user does not exist
com.atlassian.crowd.exception.InvalidCredentialException - if the password is invalid
com.atlassian.crowd.exception.OperationNotPermittedException - if the underlying User Directory is read-only
PermissionException

getActiveUserCount

int getActiveUserCount()
Returns the number of users that are currently 'active'. For a user to be active, means that it must belong to a group that has either the JIRA-users, JIRA-administrators or JIRA-Systemadministartors global permission. Implementations of this method should take performance into consideration, and ensure that the value is cached. Use clearActiveUserCount() to clear the cache.

Please note that the calculation will be run if the license does not specify a user limit.

Returns:
the active user count
Since:
v3.13
See Also:
Permissions

clearActiveUserCount

void clearActiveUserCount()
Clears the cache of the active user count so that it can be recalculated. This method should be used when performing operations that will modify the number of active users in the system.

Since:
v3.13

hasExceededUserLimit

boolean hasExceededUserLimit()
Returns true if this JIRA instance has more active users, than allowed by the license. If the license does not require a user limit, this method will return false immediately.

Returns:
True if the number of active users is greater than the limit enforced by the license. False otherwise.
Since:
v3.13

canActivateNumberOfUsers

boolean canActivateNumberOfUsers(int numUsers)
Returns true if, after adding the specified number of users, the number of active users in JIRA does not exceed the user limit allowed by the license. If the license does not require a user limit, this method will return true immediately.

Parameters:
numUsers - the number of users to add to the JIRA instance. If 0, all things being equal, this method will return true. Must not be negative!
Returns:
False if the number of active users + the number of users to add is greater than the limit enforced by the license. True otherwise.
Since:
v3.13

canActivateUsers

boolean canActivateUsers(Collection<String> userNames)
Returns true if, after adding the specified users, the number of active users in JIRA does not exceed the user limit allowed by the license. If a user specified is already active, or cannot be found, they are not counted towards the user limit. If the limit has already been exceeded, but none of the users specified are inactive, the result will still be true, as these users are already active and thus nothing changes. If the license does not require a user limit, this method will return true immediately.

Parameters:
userNames - the names of the users to add to the JIRA instance. Must not be null!
Returns:
False if the number of active users + the number of users to add is greater than the limit enforced by the license. True otherwise.
Since:
v3.13

getUser

com.atlassian.crowd.embedded.api.User getUser(String userName)
Returns a user based on user name.

WARNING: This method will be changed in the future to return a Crowd User object. Since v4.3.

Parameters:
userName - the user name of the user
Returns:
the User object, or null if the user cannot be found including null userName.
Since:
v3.13

getUserObject

com.atlassian.crowd.embedded.api.User getUserObject(String userName)
Returns a user based on user name.

WARNING: This method will be changed in the future to return a Crowd User object. Since v4.3.

Parameters:
userName - the user name of the user
Returns:
the User object, or null if the user cannot be found including null userName.
Since:
v4.3

userExists

boolean userExists(String userName)
Returns true if the a user exists with the specified userName

Parameters:
userName - the name of the user
Returns:
true if t a user exists with the specified name or false if not

getAdministrators

Collection<com.atlassian.crowd.embedded.api.User> getAdministrators()
Deprecated. Since v4.3. Use getJiraAdministrators().

Returns a list of JIRA admin Users.

WARNING: This method will be changed in the future to return a Collection of Crowd User objects. Since v4.3.

Returns:
a list of JIRA admin Users.
Since:
v3.13

getJiraAdministrators

Collection<com.atlassian.crowd.embedded.api.User> getJiraAdministrators()
Returns a list of JIRA admin Users.

WARNING: This method will be changed in the future to return a Collection of Crowd User objects. Since v4.3.

Returns:
a list of JIRA admin Users.
Since:
v4.3

getSystemAdministrators

Collection<com.atlassian.crowd.embedded.api.User> getSystemAdministrators()
Deprecated. Since v4.3. Use getJiraSystemAdministrators() .

Returns a list of JIRA system admin Users.

WARNING: This method will be changed in the future to return a Collection of Crowd User objects. Since v4.3.

Returns:
a collection of User's that are associated with the Permissions.SYSTEM_ADMIN permission.
Since:
v3.13

getJiraSystemAdministrators

Collection<com.atlassian.crowd.embedded.api.User> getJiraSystemAdministrators()
Returns a list of JIRA system admin Users.

WARNING: This method will be changed in the future to return a Collection of Crowd User objects. Since v4.3.

Returns:
a collection of User's that are associated with the Permissions.SYSTEM_ADMIN permission.
Since:
v4.3

addToJiraUsePermission

void addToJiraUsePermission(com.atlassian.crowd.embedded.api.User user)
                            throws PermissionException
Takes the given user and adds him/her to all the groups that grant a user the global JIRA use permission. (see Permissions.USE) Note: operation is only performed if by doing so we will not exceed the user limit (if the current license happens to specify a limit)

Parameters:
user - The user to be added to the USE permission
Throws:
PermissionException
Since:
v3.13

getComponentsUserLeads

Collection<ProjectComponent> getComponentsUserLeads(com.atlassian.crowd.embedded.api.User user)
Retrieve a collection of ProjectComponents - where the lead of each component is the specified user.

Parameters:
user - User leading components
Returns:
Collection of project components

getProjectsLeadBy

Collection<Project> getProjectsLeadBy(com.atlassian.crowd.embedded.api.User user)
Returns all the projects that leadUser is the project lead for.

Parameters:
user - the user in play
Returns:
A collection of project GenericValues

isNonSysAdminAttemptingToDeleteSysAdmin

boolean isNonSysAdminAttemptingToDeleteSysAdmin(com.atlassian.crowd.embedded.api.User loggedInUser,
                                                com.atlassian.crowd.embedded.api.User user)
Checking if user without SYSTEM_ADMIN rights tries to remove user with SYSTEM_ADMIN rights.

Parameters:
loggedInUser - User performing operation
user - User for remove
Returns:
true if user without SYSTEM_ADMIN rights tries to remove user with SYSTEM_ADMIN rights

getNumberOfReportedIssuesIgnoreSecurity

long getNumberOfReportedIssuesIgnoreSecurity(com.atlassian.crowd.embedded.api.User loggedInUser,
                                             com.atlassian.crowd.embedded.api.User user)
                                             throws SearchException
Returns number of issues reported by user

Parameters:
loggedInUser - the logged in user
user - the user to find the issue count for
Returns:
number of issues reported by user
Throws:
SearchException - if something goes wrong

getNumberOfAssignedIssuesIgnoreSecurity

long getNumberOfAssignedIssuesIgnoreSecurity(com.atlassian.crowd.embedded.api.User loggedInUser,
                                             com.atlassian.crowd.embedded.api.User user)
                                             throws SearchException
Returns number of issues assigned to user

Parameters:
loggedInUser - the logged in user
user - the user to find the issue count for
Returns:
number of issues assigned to user
Throws:
SearchException - if something goes wrong

getDisplayableNameSafely

String getDisplayableNameSafely(com.atlassian.crowd.embedded.api.User user)
Takes the given user and returns a "displayable name" by cautiously checking the different edge cases for users.

Parameters:
user - the user. May be null.
Returns:
The user's full name if present and not blank, the username if present, or null otherwise.

getGroupsForUser

SortedSet<com.atlassian.crowd.embedded.api.Group> getGroupsForUser(String userName)
Returns a collection of Group objects that the user belongs to.

Parameters:
userName - A User name
Returns:
the set of groups that the user belongs to
Since:
v4.3

getGroupNamesForUser

SortedSet<String> getGroupNamesForUser(String userName)
Returns a collection of the names of the groups that the user belongs to.

Parameters:
userName - A User name
Returns:
the set of groups that the user belongs to
Since:
v4.3

getAllUsersInGroupNames

SortedSet<com.atlassian.crowd.embedded.api.User> getAllUsersInGroupNames(Collection<String> groupNames)
Returns a collection of User objects that belong to any of the passed in collection of group names. Prefer using getAllUsersInGroupNamesUnsorted(java.util.Collection) and sorting the list of users only if absolutely necessary rather than relying on this method to perform the sort.

Parameters:
groupNames - a collection of group name strings
Returns:
the set of users that are in the named groups, sorted in UserBestNameComparator order

getAllUsersInGroupNamesUnsorted

Set<com.atlassian.crowd.embedded.api.User> getAllUsersInGroupNamesUnsorted(Collection<String> groupNames)
Returns a collection of User objects that belong to any of the passed in collection of group names.

Parameters:
groupNames - a collection of group name strings
Returns:
the set of users that are in the named groups
Since:
5.1

getUsersInGroupNames

SortedSet<com.atlassian.crowd.embedded.api.User> getUsersInGroupNames(Collection<String> groupNames)
Deprecated. Use getAllUsersInGroupNames(java.util.Collection) instead. Since v4.3

Returns a collection of User objects that are found within the passed in collection of group names. Null users are excluded even if they exist in the underlying data.

Parameters:
groupNames - a collection of group name strings
Returns:
the set of users that are in the named groups.

getAllUsersInGroups

SortedSet<com.atlassian.crowd.embedded.api.User> getAllUsersInGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups)
Returns a collection of User objects that are found within the passed in collection of Group objects.

Parameters:
groups - a collection of Group objects
Returns:
the set of users that are in the groups, sorted in UserBestNameComparator order

getUsersInGroups

SortedSet<com.atlassian.crowd.embedded.api.User> getUsersInGroups(Collection<com.atlassian.crowd.embedded.api.Group> groups)
Deprecated. Use getAllUsersInGroups(java.util.Collection) instead. Since v4.3

Returns a collection of User objects that are found within the passed in collection of Group objects. Null users are excluded even if they exist in the underlying data.

Parameters:
groups - a collection of Group objects
Returns:
the set of users that are in the groups, sorted in UserBestNameComparator order


Copyright © 2002-2013 Atlassian. All Rights Reserved.