com.atlassian.crowd.plugin.rest.service.controller

Class UsersController

java.lang.Object

com.atlassian.crowd.plugin.rest.service.controller.AbstractResourceController

com.atlassian.crowd.plugin.rest.service.controller.UsersController

@Named
public class UsersController
extends AbstractResourceController

Controller responsible for user management.

Constructor Summary

Constructors

Constructor and Description
UsersController(ApplicationService applicationService, ForgottenLoginManager forgottenLoginManager, AuthenticatedApplicationHolder authenticatedApplicationHolder)

Method Summary

Modifier and Type	Method and Description
UserEntity	addUser(UserEntity userEntity, com.atlassian.plugins.rest.common.Link userLink) Adds a new user.
void	addUserToGroup(String userName, String groupName) Adds a user to a group.
void	clearUserPassword(String username) Clears a user's password, so that the user cannot authenticate with any password.
void	expireAllPasswords() Expires all passwords for all directories which are part of this application, regardless of group mapping.
UserEntity	findUserByKey(String key, com.atlassian.plugins.rest.common.Link userLink, boolean expandAttributes)
UserEntity	findUserByName(String name, com.atlassian.plugins.rest.common.Link userLink, boolean expandAttributes) Returns a UserEntity specified by the name.
URI	getAvatarForUser(String username, int sizeHint)
GroupEntity	getDirectGroup(String userName, String groupName, URI baseUri) Returns the specified group that the user is a direct member of.
GroupEntityList	getDirectGroups(String userName, boolean expandGroups, boolean expandAttributes, int maxResults, int startIndex, URI baseUri) Returns the groups that the user is a direct member of.
GroupEntity	getNestedGroup(String userName, String groupName, URI baseUri) Returns the specified group that the user is a nested member of.
GroupEntityList	getNestedGroups(String userName, boolean expandGroups, int maxResults, int startIndex, URI baseUri) Returns the groups that the user is a nested member of.
void	removeUser(String username) Removes the user.
void	removeUserAttribute(String username, String attributeName) Removes the user attribute.
void	removeUserFromGroup(String userName, String groupName) Removes a user from a group.
UserEntity	renameUser(String oldUsername, com.atlassian.plugins.rest.common.Link userLink, String newUsername) Renames a user.
void	requestPasswordReset(String username) Requests a password reset.
boolean	requestUsernames(String email) Requests an email to be sent containing usernames associated with the given email address.
void	storeUserAttributes(String username, MultiValuedAttributeEntityList attributes) Stores (add/replace) the user attributes.
String	updateUser(UserEntity userEntity) Updates a user.
void	updateUserPassword(String username, String password) Updates a user's password.

Methods inherited from class com.atlassian.crowd.plugin.rest.service.controller.AbstractResourceController

getAuthenticatedApplication

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UsersController

@Inject
public UsersController(ApplicationService applicationService,
                               ForgottenLoginManager forgottenLoginManager,
                               AuthenticatedApplicationHolder authenticatedApplicationHolder)

Method Detail

findUserByName

public UserEntity findUserByName(String name,
                                 com.atlassian.plugins.rest.common.Link userLink,
                                 boolean expandAttributes)
                          throws UserNotFoundException

Returns a UserEntity specified by the name.

Parameters:

name - name of the user to retrieve

userLink - link to the user resource

expandAttributes - set to true if the attributes field should be expanded

Returns:

UserEntity

Throws:

UserNotFoundException - if the user could not be found

findUserByKey

public UserEntity findUserByKey(String key,
                                com.atlassian.plugins.rest.common.Link userLink,
                                boolean expandAttributes)
                         throws UserNotFoundException

Throws:

UserNotFoundException

addUser

public UserEntity addUser(UserEntity userEntity,
                          com.atlassian.plugins.rest.common.Link userLink)
                   throws ApplicationPermissionException,
                          InvalidUserException,
                          InvalidCredentialException,
                          OperationFailedException

Adds a new user.

Parameters:

userEntity - new user to add

userLink - preliminary link to the user resource

Returns:

the created UserWithAttributes represented within a UserEntity

Throws:

ApplicationPermissionException - if none of the application's underlying directories are allowed to perform this operation

OperationFailedException - if the operation failed for any other reason

InvalidCredentialException - if the password is not valid

InvalidUserException - if the user is not valid or already exists

updateUser

public String updateUser(UserEntity userEntity)
                  throws ApplicationPermissionException,
                         InvalidUserException,
                         UserNotFoundException,
                         OperationFailedException

Updates a user.

Parameters:

userEntity - updated user information

Returns:

canonical username

Throws:

ApplicationPermissionException - if none of the application's underlying directories are allowed to perform this operation

InvalidUserException - if the user template does not have the required properties populated.

UserNotFoundException - if the user was not found

OperationFailedException - if the operation failed for any other reason

storeUserAttributes

public void storeUserAttributes(String username,
                                MultiValuedAttributeEntityList attributes)
                         throws ApplicationPermissionException,
                                UserNotFoundException,
                                OperationFailedException

Stores (add/replace) the user attributes. Attribute values will not be overwritten if not specified in attributes.

Parameters:

username - name of the user

attributes - attributes of the user

Throws:

ApplicationPermissionException - if none of the application's underlying directories are allowed to perform this operation

OperationFailedException - if the operation failed for any other reason

UserNotFoundException - if the user could not be found

removeUserAttribute

public void removeUserAttribute(String username,
                                String attributeName)
                         throws ApplicationPermissionException,
                                UserNotFoundException,
                                OperationFailedException

Removes the user attribute.

Parameters:

username - name of the user

attributeName - name of attribute to remove

Throws:

ApplicationPermissionException - if none of the application's underlying directories have permission to perform the operation

OperationFailedException - if the operation failed for any other reason

UserNotFoundException - if the user could not be found

requestPasswordReset

public void requestPasswordReset(String username)
                          throws InvalidEmailAddressException,
                                 ApplicationPermissionException,
                                 UserNotFoundException

Requests a password reset.

Parameters:

username - name of the user

Throws:

UserNotFoundException - if the user could not be found

InvalidEmailAddressException - if the user does not have a valid email to send the reset password link to

ApplicationPermissionException - if none of the application's underlying directories can update the user's password

requestUsernames

public boolean requestUsernames(String email)
                         throws InvalidEmailAddressException

Requests an email to be sent containing usernames associated with the given email address.

Parameters:

email - email address of the user

Returns:

true if any users with that address were found.

Throws:

InvalidEmailAddressException - if the email is not valid

removeUser

public void removeUser(String username)
                throws ApplicationPermissionException,
                       UserNotFoundException,
                       OperationFailedException

Removes the user.

Parameters:

username - name of the user

Throws:

ApplicationPermissionException - if none of the application's underlying directories can update the user's password

OperationFailedException - if the operation failed for any other reason

UserNotFoundException - if the user could not be found

renameUser

public UserEntity renameUser(String oldUsername,
                             com.atlassian.plugins.rest.common.Link userLink,
                             String newUsername)
                      throws ApplicationPermissionException,
                             InvalidUserException,
                             UserNotFoundException,
                             OperationFailedException

Renames a user.

Parameters:

oldUsername - current name of the user to rename

newUsername - the intended new name of the user

Returns:

the renamed user

Throws:

ApplicationPermissionException - if none of the application's underlying directories are allowed to perform this operation

InvalidUserException - if the user template does not have the required properties populated.

UserNotFoundException - if the user was not found

OperationFailedException - if the operation failed for any other reason

updateUserPassword

public void updateUserPassword(String username,
                               String password)
                        throws ApplicationPermissionException,
                               UserNotFoundException,
                               InvalidCredentialException,
                               OperationFailedException

Updates a user's password.

Parameters:

username - name of the user

password - new password

Throws:

ApplicationPermissionException - if none of the application's underlying directories are allowed to perform this operation

UserNotFoundException - if the user was not found

OperationFailedException - if the operation failed for any other reason

InvalidCredentialException - if the new password is not valid

clearUserPassword

public void clearUserPassword(String username)
                       throws ApplicationPermissionException,
                              UserNotFoundException,
                              InvalidCredentialException,
                              OperationFailedException

Clears a user's password, so that the user cannot authenticate with any password.

Parameters:

username - name of the user

Throws:

ApplicationPermissionException - if none of the application's underlying directories are allowed to perform this operation

UserNotFoundException - if the user was not found

OperationFailedException - if the operation failed for any other reason

InvalidCredentialException - if the new password is not valid

expireAllPasswords

public void expireAllPasswords()
                        throws OperationFailedException

Expires all passwords for all directories which are part of this application, regardless of group mapping.

Throws:

OperationFailedException - if any of the directories fail to expire all passwords. This can lead to only some of the users having expired passwords.

getDirectGroups

public GroupEntityList getDirectGroups(String userName,
                                       boolean expandGroups,
                                       boolean expandAttributes,
                                       int maxResults,
                                       int startIndex,
                                       URI baseUri)
                                throws UserNotFoundException

Returns the groups that the user is a direct member of.

Parameters:

userName - name of the user

expandGroups - should groups be expanded

expandAttributes - should the attributes of the group be expanded

maxResults - maximum number of results returned. If -1, then all the results are returned.

startIndex - starting index of the results

baseUri - base URI of the REST service

Returns:

groups that the user is a direct member of

Throws:

UserNotFoundException

getDirectGroup

public GroupEntity getDirectGroup(String userName,
                                  String groupName,
                                  URI baseUri)
                           throws MembershipNotFoundException,
                                  UserNotFoundException

Returns the specified group that the user is a direct member of.

Parameters:

userName - name of the user

groupName - name of the group the user is a member of

baseUri - base URI of the REST service

Returns:

group that the user is a direct member of

Throws:

MembershipNotFoundException - if the membership was not found

UserNotFoundException

addUserToGroup

public void addUserToGroup(String userName,
                           String groupName)
                    throws ApplicationPermissionException,
                           UserNotFoundException,
                           GroupNotFoundException,
                           OperationFailedException,
                           MembershipAlreadyExistsException

Adds a user to a group.

Parameters:

userName - name of the user

groupName - name of the group

Throws:

ApplicationPermissionException - if none of the application's associated directories are allowed to perform operations of type OperationType.UPDATE_GROUP.

UserNotFoundException - if the user could not be found

GroupNotFoundException - if the group could not be found

MembershipAlreadyExistsException - if the user is already a member of the group

OperationFailedException - if the operation failed for any other reason

removeUserFromGroup

public void removeUserFromGroup(String userName,
                                String groupName)
                         throws ApplicationPermissionException,
                                MembershipNotFoundException,
                                UserNotFoundException,
                                GroupNotFoundException,
                                OperationFailedException

Removes a user from a group.

Parameters:

userName - name of the user

groupName - name of the group

Throws:

ApplicationPermissionException - if none of the application's associated directories are allowed to perform operations of type OperationType.UPDATE_GROUP.

GroupNotFoundException - if the group could not be found

MembershipNotFoundException - if the membership does not exist

UserNotFoundException - if the user could not be found

OperationFailedException - if the operation failed for any other reason

getNestedGroups

public GroupEntityList getNestedGroups(String userName,
                                       boolean expandGroups,
                                       int maxResults,
                                       int startIndex,
                                       URI baseUri)
                                throws UserNotFoundException

Returns the groups that the user is a nested member of.

Parameters:

userName - name of the user

expandGroups - should groups be expanded

maxResults - maximum number of results returned. If -1, then all the results are returned.

startIndex - starting index of the results

baseUri - base URI of the REST service

Returns:

groups that the user is a nested member of

Throws:

UserNotFoundException

getNestedGroup

public GroupEntity getNestedGroup(String userName,
                                  String groupName,
                                  URI baseUri)
                           throws MembershipNotFoundException,
                                  UserNotFoundException

Returns the specified group that the user is a nested member of.

Parameters:

userName - name of the user

groupName - name of the group the user is a member of

baseUri - base URI of the REST service

Returns:

group that the user is a nested member of

Throws:

MembershipNotFoundException - if the membership was not found

UserNotFoundException

getAvatarForUser

@Nullable
public URI getAvatarForUser(String username,
                                      int sizeHint)
                               throws UserNotFoundException,
                                      DirectoryNotFoundException,
                                      OperationFailedException

Throws:

UserNotFoundException

DirectoryNotFoundException

OperationFailedException