com.atlassian.jira.bc.user

Interface UserService

All Known Implementing Classes:

DefaultUserService, MockUserService

@PublicApi
public interface UserService

UserService provides User manipulation methods exposed for remote API and actions.

Since:

v4.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	UserService.AddUserToApplicationValidationResult
static class	UserService.CreateUsernameValidationResult
static class	UserService.CreateUserRequest This request contains all the instructions and user details that should be used during user validation and user creation.
static class	UserService.CreateUserValidationResult
static class	UserService.DeleteUserValidationResult
static class	UserService.FieldName
static class	UserService.RemoveUserFromApplicationValidationResult
static class	UserService.UpdateUserValidationResult

Method Summary

Modifier and Type	Method and Description
void	addUserToApplication(UserService.AddUserToApplicationValidationResult result) Given a valid validation result, this will associate a user with an application by adding that user to all the default groups assigned to that application (regardless of the license).
ApplicationUser	createUser(UserService.CreateUserValidationResult createUserValidationResult) Create a new application user if the provided ServiceResultImpl.isValid().
ApplicationUser	createUserFromSignup(UserService.CreateUserValidationResult result) Deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.
ApplicationUser	createUserNoNotification(UserService.CreateUserValidationResult result) Deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.
ApplicationUser	createUserWithNotification(UserService.CreateUserValidationResult result) Deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.
ApplicationUserBuilder	newUserBuilder(ApplicationUser user) Allows you to construct ApplicationUser for validateUpdateUser(ApplicationUser)
void	removeUser(ApplicationUser loggedInUser, UserService.DeleteUserValidationResult result) Deprecated. Use removeUser(ApplicationUser, DeleteUserValidationResult) instead. Since v6.0.
void	removeUserFromApplication(UserService.RemoveUserFromApplicationValidationResult result) Given a valid validation result, this will disassociate a user from an application by removing that user from all the groups assigned to that application.
void	updateUser(UserService.UpdateUserValidationResult updateUserValidationResult) Execute the update using the validation result from validateUpdateUser(ApplicationUser).
UserService.AddUserToApplicationValidationResult	validateAddUserToApplication(ApplicationUser user, com.atlassian.application.api.ApplicationKey applicationKey) Deprecated. Use validateAddUserToApplication(ApplicationUser, ApplicationUser, ApplicationKey) instead. Since v7.0
UserService.AddUserToApplicationValidationResult	validateAddUserToApplication(ApplicationUser loggedInUser, ApplicationUser user, com.atlassian.application.api.ApplicationKey applicationKey) Validates associating a user with an application.
UserService.CreateUserValidationResult	validateCreateUser(UserService.CreateUserRequest createUserRequest) Validate that a new user can be created.
UserService.CreateUserValidationResult	validateCreateUserForAdmin(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname) Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult	validateCreateUserForAdmin(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname, Long directoryId) Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult	validateCreateUserForSetup(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname) Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult	validateCreateUserForSignup(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname) Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult	validateCreateUserForSignupOrSetup(ApplicationUser user, String username, String password, String confirmPassword, String email, String fullname) Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUsernameValidationResult	validateCreateUsername(ApplicationUser loggedInUser, String username) Validates the username for a new user.
UserService.CreateUsernameValidationResult	validateCreateUsername(ApplicationUser loggedInUser, String username, Long directoryId) Validates the username for a new user.
UserService.DeleteUserValidationResult	validateDeleteUser(ApplicationUser loggedInUser, ApplicationUser userForDelete) Validates removing a user for the admin section.
UserService.DeleteUserValidationResult	validateDeleteUser(ApplicationUser loggedInUser, String username) Validates removing a user for the admin section.
UserService.RemoveUserFromApplicationValidationResult	validateRemoveUserFromApplication(ApplicationUser user, com.atlassian.application.api.ApplicationKey applicationKey) Deprecated. Use validateRemoveUserFromApplication(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.user.ApplicationUser, com.atlassian.application.api.ApplicationKey) instead. Since v 7.0.0.
UserService.RemoveUserFromApplicationValidationResult	validateRemoveUserFromApplication(ApplicationUser loggedInUser, ApplicationUser user, com.atlassian.application.api.ApplicationKey applicationKey) Validates disassociating a user from an application.
UserService.UpdateUserValidationResult	validateUpdateUser(ApplicationUser user) Validates updating a user's details.

Method Detail

validateCreateUser

UserService.CreateUserValidationResult validateCreateUser(UserService.CreateUserRequest createUserRequest)

Validate that a new user can be created. The validation instructions are specified in the UserService.CreateUserRequest.

Typical validations are:

• Validate that specified (or default) application(s) has a seat available for the new user and that the default group(s) has been configured.
• Validate that the specified logged in user is allowed to create a new user.
• Validate that the specified or default user directory exists and is writable.
• Validate that password conforms to password policy.
• Validate that confirm password matches password (optional).
• Validate that the new username is not currently in use.

createUser(CreateUserValidationResult) should only be called when the validationResult.isValid().

Usage example:

 final CreateUserRequest createUserRequest = CreateUserRequest.withUserDetails(currentApplicationUser,
               username, password, email, displayName)
 result = userService.validateCreateUser(createUserRequest);
 if(result.isValid())
 {
    userService.createUser(createUserRequest);
 }
 
 

This request indicates that the user should be created in the default user directory with access to the default applications.

Parameters:

createUserRequest - user creation request containing new user details and validation instructions.

Returns:

the result that would contain error messages when validation was not successful.

createUser

ApplicationUser createUser(UserService.CreateUserValidationResult createUserValidationResult)
                    throws PermissionException,
                           CreateException

Create a new application user if the provided ServiceResultImpl.isValid(). This is typically called after performing validateCreateUser(CreateUserRequest) and verifying that the ServiceResultImpl.isValid(). If the request is not valid or validateCreateUser(CreateUserRequest) was not called prior to this method an IllegalStateException would get thrown.

Parameters:

createUserValidationResult - create user validation result returned from validateCreateUser(CreateUserRequest), this contains the user details and instructions used to create new user.

Returns:

an application user representing the newly created user.

Throws:

PermissionException - when the logged in user does not have permissions to perform user creation or when the user directory is read-only.

CreateException - if the user could not be created for any reason, eg username already exists

See Also:

validateCreateUser(CreateUserRequest)

newUserBuilder

@Nonnull
 @ExperimentalApi
ApplicationUserBuilder newUserBuilder(@Nonnull
                                                                 ApplicationUser user)

Allows you to construct ApplicationUser for validateUpdateUser(ApplicationUser)

validateCreateUserForSignup

UserService.CreateUserValidationResult validateCreateUserForSignup(ApplicationUser loggedInUser,
                                                                   String username,
                                                                   String password,
                                                                   String confirmPassword,
                                                                   String email,
                                                                   String fullname)

Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user during public signup. This method checks that there is a writable User Directory available. It also validates that all parameters (username, email, fullname, password) have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForAdminPasswordRequired' and 'ForAdmin' validations as follows:

• Does not require global admin rights
• The password is required

Parameters:

loggedInUser - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

password - The password for the new user.

confirmPassword - The password confirmation. Needs to match password.

email - The email for the new user. Needs to be a valid email address.

fullname - The full name for the new user

Returns:

a validation result containing appropriate errors or the new user's details

Since:

5.0

validateCreateUserForSetup

UserService.CreateUserValidationResult validateCreateUserForSetup(ApplicationUser loggedInUser,
                                                                  String username,
                                                                  String password,
                                                                  String confirmPassword,
                                                                  String email,
                                                                  String fullname)

Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user during setup of JIRA. This method does not check for a writable User Directory because the embedded crowd subsystem will not be initialised, and we know we will just have an Internal Directory during Setup. It also validates that all parameters (username, email, fullname, password) have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForAdminPasswordRequired' and 'ForAdmin' validations as follows:

• Does not require global admin rights
• The password is required

Parameters:

loggedInUser - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

password - The password for the new user.

confirmPassword - The password confirmation. Needs to match password.

email - The email for the new user. Needs to be a valid email address.

fullname - The full name for the new user

Returns:

a validation result containing appropriate errors or the new user's details

Since:

5.0

validateCreateUserForSignupOrSetup

UserService.CreateUserValidationResult validateCreateUserForSignupOrSetup(ApplicationUser user,
                                                                          String username,
                                                                          String password,
                                                                          String confirmPassword,
                                                                          String email,
                                                                          String fullname)

Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user during setup of JIRA or during public signup. This method checks that there is a writable User Directory available. It also validates that all parameters (username, email, fullname, password) have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForAdminPasswordRequired' and 'ForAdmin' validations as follows:

• Does not require global admin rights
• The password is required

Parameters:

user - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

password - The password for the new user.

confirmPassword - The password confirmation. Needs to match password.

email - The email for the new user. Needs to be a valid email address.

fullname - The full name for the new user

Returns:

a validation result containing appropriate errors or the new user's details

Since:

4.0

validateCreateUserForAdmin

UserService.CreateUserValidationResult validateCreateUserForAdmin(ApplicationUser loggedInUser,
                                                                  String username,
                                                                  String password,
                                                                  String confirmPassword,
                                                                  String email,
                                                                  String fullname)

Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that all parameters (username, email, fullname) except for the password have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForSetup' and 'ForAdminPasswordRequired' validations as follows:

• Does require global admin rights
• The password is NOT required

Parameters:

loggedInUser - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

password - The password for the new user.

confirmPassword - The password confirmation. Needs to match password.

email - The email for the new user. Needs to be a valid email address.

fullname - The full name for the new user

Returns:

a validation result containing appropriate errors or the new user's details

Since:

4.3

validateCreateUserForAdmin

UserService.CreateUserValidationResult validateCreateUserForAdmin(ApplicationUser loggedInUser,
                                                                  String username,
                                                                  String password,
                                                                  String confirmPassword,
                                                                  String email,
                                                                  String fullname,
                                                                  @Nullable
                                                                  Long directoryId)

Deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that all parameters (username, email, fullname) except for the password have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This method allows the caller to name a directory to create the user in and the directoryId must be valid and represent a Directory with "create user" permission.

This validation differs from the 'ForSetup' and 'ForAdminPasswordRequired' validations as follows:

• Does require global admin rights
• The password is NOT required

Parameters:

loggedInUser - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

password - The password for the new user.

confirmPassword - The password confirmation. Needs to match password.

email - The email for the new user. Needs to be a valid email address.

fullname - The full name for the new user

directoryId - The User Directory

Returns:

a validation result containing appropriate errors or the new user's details

Since:

4.3.2

validateCreateUsername

UserService.CreateUsernameValidationResult validateCreateUsername(ApplicationUser loggedInUser,
                                                                  String username)

Validates the username for a new user. The username is required to be lowercase characters only and unique across all directories.

Parameters:

loggedInUser - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

Returns:

a validation result containing appropriate errors

Since:

5.0.4

validateCreateUsername

UserService.CreateUsernameValidationResult validateCreateUsername(ApplicationUser loggedInUser,
                                                                  String username,
                                                                  Long directoryId)

Validates the username for a new user. The username is required to be lowercase characters only and unique in the given directory.

Parameters:

loggedInUser - The remote user trying to add a new user

username - The username of the new user. Needs to be lowercase and unique.

directoryId - The directory which the new user is intended to be created in.

Returns:

a validation result containing appropriate errors

Since:

5.0.4

createUserFromSignup

ApplicationUser createUserFromSignup(UserService.CreateUserValidationResult result)
                              throws PermissionException,
                                     CreateException

Deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.

Given a valid validation result, this will create the user using the details provided in the validation result. Email notification will be send to created user - via UserEventType.USER_SIGNUP event.

Parameters:

result - The validation result

Returns:

The new user object that was created

Throws:

CreateException - if the user could not be created, eg username already exists

PermissionException - If you cannot create users in this directory (it is read-only).

Since:

4.3

createUserWithNotification

ApplicationUser createUserWithNotification(UserService.CreateUserValidationResult result)
                                    throws PermissionException,
                                           CreateException

Deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.

Given a valid validation result, this will create the user using the details provided in the validation result. Email notification will be send to created user - via UserEventType.USER_CREATED event.

Parameters:

result - The validation result

Returns:

The new user object that was created

Throws:

CreateException - if the user could not be created, eg username already exists

PermissionException - If you cannot create users in this directory (it is read-only).

Since:

4.3

createUserNoNotification

ApplicationUser createUserNoNotification(UserService.CreateUserValidationResult result)
                                  throws PermissionException,
                                         CreateException

Deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.

Given a valid validation result, this will create the user using the details provided in the validation result. No email notification will be send to created user.

Parameters:

result - The validation result

Returns:

The new user object that was created

Throws:

CreateException - if the user could not be created, eg username already exists

PermissionException - If you cannot create users in this directory (it is read-only).

Since:

4.3

validateUpdateUser

UserService.UpdateUserValidationResult validateUpdateUser(ApplicationUser user)

Validates updating a user's details.

Parameters:

user - The user details to update

Returns:

A validation result containing any errors and all user details

updateUser

void updateUser(UserService.UpdateUserValidationResult updateUserValidationResult)

Execute the update using the validation result from validateUpdateUser(ApplicationUser).

Parameters:

updateUserValidationResult - Result from the validation, which also contains all the user's details.

Throws:

IllegalStateException - if the validation result contains any errors.

validateDeleteUser

UserService.DeleteUserValidationResult validateDeleteUser(ApplicationUser loggedInUser,
                                                          String username)

Validates removing a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that username have been provided.

See validateDeleteUser(ApplicationUser, ApplicationUser) for restrictions.

Parameters:

loggedInUser - The remote user trying to remove a user

username - The username of the user to remove. Needs to be valid

Returns:

a validation result containing appropriate errors or the user object for delete

Since:

6.0

validateDeleteUser

UserService.DeleteUserValidationResult validateDeleteUser(ApplicationUser loggedInUser,
                                                          ApplicationUser userForDelete)

Validates removing a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that username have been provided.

Removing the user is not allowed if:

• Logged in user lacks global admin permissions
• Logged in user and target user are the same user
• Logged in user is not a system administrator but the target user is
• Target user is the assignee for any issue
• Target user is the reporter for any issue
• Target user is the project lead for any project
• A plugin that implements PreDeleteUserErrors rejects the request

Parameters:

loggedInUser - The remote user trying to remove a user

userForDelete - The user to remove. Needs to be valid

Returns:

a validation result containing appropriate errors or the user object for delete

Since:

6.0

removeUser

void removeUser(ApplicationUser loggedInUser,
                UserService.DeleteUserValidationResult result)

Deprecated. Use removeUser(ApplicationUser, DeleteUserValidationResult) instead. Since v6.0.

Given a valid validation result, 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

result - The validation result

validateAddUserToApplication

UserService.AddUserToApplicationValidationResult validateAddUserToApplication(ApplicationUser user,
                                                                              com.atlassian.application.api.ApplicationKey applicationKey)

Deprecated. Use validateAddUserToApplication(ApplicationUser, ApplicationUser, ApplicationKey) instead. Since v7.0

Validates associating a user with an application. This method checks there is an application specified by the application key. It also checks if there are any default groups assigned to that application. It validates if there are any spaces in the application license as well. This also validates if the directory where the user lives is not fully read-only.

Parameters:

user - the user to be associated with the application

applicationKey - the key of the application

Returns:

a validation result containing appropriate errors or the details used to associate a user with an application

Since:

7.0

validateAddUserToApplication

UserService.AddUserToApplicationValidationResult validateAddUserToApplication(ApplicationUser loggedInUser,
                                                                              ApplicationUser user,
                                                                              com.atlassian.application.api.ApplicationKey applicationKey)

Validates associating a user with an application. This method checks if the logged in user has the permission to add user to application. It then checks if there is an application specified by the application key. It also checks if there are any default groups assigned to that application. It validates if there are any spaces in the application license as well. This also validates if the directory where the user lives is not fully read-only.

Parameters:

loggedInUser - The logged in user

user - the user to be associated with the application

applicationKey - the key of the application

Returns:

a validation result containing appropriate errors or the details used to associate a user with an application

Since:

7.0

addUserToApplication

void addUserToApplication(UserService.AddUserToApplicationValidationResult result)
                   throws AddException,
                          PermissionException

Given a valid validation result, this will associate a user with an application by adding that user to all the default groups assigned to that application (regardless of the license).

If the user is already associated with the application but is not the member of all the default groups, that user will be added to the default groups which that user does not belong to yet.

If any of the default groups assigned to this application are also assigned to other application(s), the user will also be associated with those applications as well.

This method is not the exact opposite to removeUserFromApplication(com.atlassian.jira.bc.user.UserService.RemoveUserFromApplicationValidationResult). While this method only adds user to the default groups assigned to an application, removeUserFromApplication method removes user from all the group assigned to an application.

Parameters:

result - the validation result

Throws:

AddException - the underlying directory implementation failed to add user to group

PermissionException - the underlying directory has been configured to not allow user to be added to group, or the directory/group is read-only

Since:

v7.0

validateRemoveUserFromApplication

@Deprecated
 @Internal
UserService.RemoveUserFromApplicationValidationResult validateRemoveUserFromApplication(ApplicationUser user,
                                                                                                               com.atlassian.application.api.ApplicationKey applicationKey)

Deprecated. Use validateRemoveUserFromApplication(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.user.ApplicationUser, com.atlassian.application.api.ApplicationKey) instead. Since v 7.0.0.

Validates disassociating a user from an application. This method checks there is an application specified by the application key.

Method expects for loggedInUser to be available via JiraAuthenticationContext.getLoggedInUser().

Parameters:

user - the user to be disassociated with the application

applicationKey - the key of the application

Returns:

a validation result containing appropriate errors or the details used to disassociate a user from an application

Since:

7.0

validateRemoveUserFromApplication

UserService.RemoveUserFromApplicationValidationResult validateRemoveUserFromApplication(ApplicationUser loggedInUser,
                                                                                        ApplicationUser user,
                                                                                        com.atlassian.application.api.ApplicationKey applicationKey)

Validates disassociating a user from an application. This method checks there is an application specified by the application key.

Parameters:

loggedInUser - application user performing the application access removal

user - the user to be disassociated with the application

applicationKey - the key of the application

Returns:

a validation result containing appropriate errors or the details used to disassociate a user from an application

Since:

7.0

removeUserFromApplication

void removeUserFromApplication(UserService.RemoveUserFromApplicationValidationResult result)
                        throws RemoveException,
                               PermissionException

Given a valid validation result, this will disassociate a user from an application by removing that user from all the groups assigned to that application. This also validates if the directory where the user lives is not fully read-only.

If the group set assigned to this application is a superset of the group set assigned to other application(s), the user will also be disassociated with those applications as well.

This method is not the exact opposite to addUserToApplication(com.atlassian.jira.bc.user.UserService.AddUserToApplicationValidationResult). While this method removes user from all the group assigned to an application, addUserToApplication method only adds user to the default groups assigned to an application

Parameters:

result - The validation result

Throws:

RemoveException - the underlying directory implementation failed to remove user from group

PermissionException - the underlying directory has been configured to not allow user to be removed from group, or the directory/group is read-only

Since:

v7.0