com.atlassian.crowd.embedded.api

Interface CrowdService

All Known Subinterfaces:

UnfilteredCrowdService

public interface CrowdService

Provides the interface for performing User and Group operations in Crowd for applications embedding Crowd. User.getDirectoryId() is ignored in all methods having User in the parameter list. Null parameters for methods may throw NullPointerException or IllegalArgumentException.

See Also:

CrowdDirectoryService

Method Summary

Methods

Modifier and Type	Method and Description
Group	addGroup(Group group) Adds a group to the directory store.
boolean	addGroupToGroup(Group childGroup, Group parentGroup) Adds a group as a member of a parent group.
User	addUser(User user, String credential) Adds a user to the directory store.
boolean	addUserToGroup(User user, Group group) Adds a user as a member of a group.
User	authenticate(String name, String credential) Authenticates a user with the given credential.
UserCapabilities	getCapabilitiesForNewUsers() Gets details of the possible operations that can be performed on new users.
Group	getGroup(String name) Finds the group that matches the supplied name.
GroupWithAttributes	getGroupWithAttributes(String name) Finds the group that matches the supplied name.
User	getUser(String name) Returns the user that matches the supplied name.
UserWithAttributes	getUserWithAttributes(String name) Returns the user that matches the supplied name.
boolean	isGroupDirectGroupMember(Group childGroup, Group parentGroup) Determines if a group is a direct member of another group.
boolean	isGroupMemberOfGroup(Group childGroup, Group parentGroup) Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup.
boolean	isGroupMemberOfGroup(String childGroupName, String parentGroupName) Returns true if childGroupName is a direct or indirect (nested) member of parentGroupName.
boolean	isUserDirectGroupMember(User user, Group group) Determines if a user is a direct member of a group.
boolean	isUserMemberOfGroup(String userName, String groupName) Returns true if the user is a direct or indirect (nested) member of the group.
boolean	isUserMemberOfGroup(User user, Group group) Returns true if the user is a direct or indirect (nested) member of the group.
void	removeAllGroupAttributes(Group group) Removes all group attributes.
void	removeAllUserAttributes(User user) Remove all attributes for a user.
boolean	removeGroup(Group group) Removes the group that matches the supplied name.
void	removeGroupAttribute(Group group, String attributeName) Removes all the values for a single attribute key for a group.
boolean	removeGroupFromGroup(Group childGroup, Group parentGroup) Removes a group as a member of a parent group.
boolean	removeUser(User user) Removes the user that matches the supplied name.
void	removeUserAttribute(User user, String attributeName) Removes all the values for a single attribute key for a user.
boolean	removeUserFromGroup(User user, Group group) Removes a user as a member of a group.
User	renameUser(User user, String newUsername) Renames the User.
<T> Iterable<T>	search(Query<T> query) Searches for entities (e.g.
Iterable<User>	searchUsersAllowingDuplicateNames(Query<User> query) Deprecated. this method violates the directory encapsulation of CrowdService and will be removed in the future. Consumers of this method should move to a different service.
void	setGroupAttribute(Group group, String attributeName, Set<String> attributeValues) Adds or updates a group's attributes with the new attributes.
void	setGroupAttribute(Group group, String attributeName, String attributeValue) Adds or updates a group's attributes with the new attributes.
void	setUserAttribute(User user, String attributeName, Set<String> attributeValues) Adds or updates a user's attribute with the new attribute values.
void	setUserAttribute(User user, String attributeName, String attributeValue) Adds or updates a user's attribute with the new attribute value.
Group	updateGroup(Group group) Updates the group.
User	updateUser(User user) Updates the User.
void	updateUserCredential(User user, String credential) Updates the password for a user.

Method Detail

authenticate

User authenticate(String name,
                String credential)
                  throws FailedAuthenticationException,
                         OperationFailedException

Authenticates a user with the given credential.

Parameters:

name - The name of the user (username).

credential - The supplied credential to authenticate with

Returns:

The populated user if the authentication is valid.

Throws:

FailedAuthenticationException - Authentication with the provided credentials failed. It may indicate that the user does not exist or the user's account is inactive or the credentials are incorrect

InactiveAccountException - The supplied user is inactive.

ExpiredCredentialException - The user's credentials have expired. The user must change their credentials in order to successfully authenticate.

AccountNotFoundException - User with the given name could not be found

OperationFailedException - underlying directory implementation failed to execute the operation.

getUser

User getUser(String name)

Returns the user that matches the supplied name.

Parameters:

name - the name of the user (username). Does not allow null, blank or empty strings.

Returns:

user entity or null if the user is not found

getUserWithAttributes

UserWithAttributes getUserWithAttributes(String name)

Returns the user that matches the supplied name.

Parameters:

name - the name of the user (username).

Returns:

user entity with attributes or null if the user is not found

getGroup

Group getGroup(String name)

Finds the group that matches the supplied name.

Parameters:

name - the name of the group.

Returns:

group entity, null if not found.

getGroupWithAttributes

GroupWithAttributes getGroupWithAttributes(String name)

Finds the group that matches the supplied name.

Parameters:

name - the name of the group.

Returns:

group entity with attributes, null if not found.

search

<T> Iterable<T> search(Query<T> query)

Searches for entities (e.g. Group or User) of type <T> that match the supplied search query. Search return types must be either String, User or Group.

Parameters:

query - Query for a given entity (e.g. Group or User)

Returns:

entities of type T matching the search query. An Iterable containing no results will be returned if there are no matches for the query.

isUserMemberOfGroup

boolean isUserMemberOfGroup(String userName,
                          String groupName)

Returns true if the user is a direct or indirect (nested) member of the group.

Parameters:

userName - user to inspect.

groupName - group to inspect.

Returns:

true if and only if the user is a direct or indirect (nested) member of the group. If the user or group cannot found, then false is returned.

See Also:

isUserMemberOfGroup(User, Group)

isUserMemberOfGroup

boolean isUserMemberOfGroup(User user,
                          Group group)

Returns true if the user is a direct or indirect (nested) member of the group.

Parameters:

user - user to inspect.

group - group to inspect.

Returns:

true if and only if the user is a direct or indirect (nested) member of the group, otherwise false. If the user or group cannot found, then false is returned.

See Also:

isUserMemberOfGroup(String, String)

isGroupMemberOfGroup

boolean isGroupMemberOfGroup(String childGroupName,
                           String parentGroupName)

Returns true if childGroupName is a direct or indirect (nested) member of parentGroupName.

Parameters:

childGroupName - name of child group to inspect.

parentGroupName - name of parent group to inspect.

Returns:

true if and only if the childGroupName is a direct or indirect (nested) member of the parentGroupName. If any of the groups cannot found, then false is returned.

isGroupMemberOfGroup

boolean isGroupMemberOfGroup(Group childGroup,
                           Group parentGroup)

Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup.

Parameters:

childGroup - group to inspect.

parentGroup - group to inspect.

Returns:

true if and only if the childGroup is a direct or indirect (nested) member of the parentGroup. If any of the groups cannot found, then false is returned.

addUser

User addUser(User user,
           String credential)
             throws InvalidUserException,
                    InvalidCredentialException,
                    OperationNotPermittedException,
                    OperationFailedException

Adds a user to the directory store. The user must have non-null names and email address.

Parameters:

user - template of the user to add.

credential - password. May not be null or blank.

Returns:

the added user retrieved from the underlying store.

Throws:

InvalidUserException - The supplied user's details are invalid and/or incomplete.

InvalidCredentialException - The supplied credential is invalid, this may be due the credential not matching required directory constraints.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - if the operation failed for any other reason

updateUser

User updateUser(User user)
                throws UserNotFoundException,
                       InvalidUserException,
                       OperationNotPermittedException,
                       OperationFailedException

Updates the User. The user must have non-null names and email address.

Parameters:

user - The user to update.

Returns:

the updated user retrieved from the underlying store. This might be a new object instance, depending on the underlying Directory

Throws:

UserNotFoundException - if the supplied user does not exist in the directory.

InvalidUserException - The supplied user's details are invalid and/or incomplete.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

renameUser

User renameUser(User user,
              String newUsername)
                throws UserNotFoundException,
                       InvalidUserException,
                       OperationNotPermittedException,
                       OperationFailedException

Renames the User.

Parameters:

user - user to rename.

newUsername - new username of the renamed user.

Returns:

the renamed User.

Throws:

UserNotFoundException - if the supplied user does not exist.

InvalidUserException - if the new username does not meet the username requirements for an associated directory.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed.

OperationFailedException - underlying directory implementation failed to execute the operation.

UnsupportedOperationException - underlying directory implementation does not support user renaming.

updateUserCredential

void updateUserCredential(User user,
                        String credential)
                          throws UserNotFoundException,
                                 InvalidCredentialException,
                                 OperationNotPermittedException,
                                 OperationFailedException

Updates the password for a user.

Parameters:

user - The name of the user (username).

credential - The new credential (password). May not be null or blank.

Throws:

InvalidCredentialException - The supplied credential is invalid, this may be due the credential not matching required directory constraints.

UserNotFoundException - if the supplied user does not exist in the directory.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

setUserAttribute

void setUserAttribute(User user,
                    String attributeName,
                    String attributeValue)
                      throws UserNotFoundException,
                             OperationNotPermittedException,
                             OperationFailedException

Adds or updates a user's attribute with the new attribute value. The attributes represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing attribute. This will not remove any attributes.

Parameters:

user - user to update.

attributeName - the name of the attribute

attributeValue - the new value of the attribute; any existing values will be replaced

Throws:

UserNotFoundException - the supplied user does not exist.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

setUserAttribute

void setUserAttribute(User user,
                    String attributeName,
                    Set<String> attributeValues)
                      throws UserNotFoundException,
                             OperationNotPermittedException,
                             OperationFailedException

Adds or updates a user's attribute with the new attribute values. The attributes represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing. This will not remove any attributes.

Parameters:

user - user to update.

attributeName - the name of the attribute

attributeValues - the new set of values; any existing values will be replaced

Throws:

UserNotFoundException - the supplied user does not exist.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

removeUserAttribute

void removeUserAttribute(User user,
                       String attributeName)
                         throws UserNotFoundException,
                                OperationNotPermittedException,
                                OperationFailedException

Removes all the values for a single attribute key for a user.

Parameters:

user - user to update.

attributeName - name of attribute to remove.

Throws:

UserNotFoundException - user with supplied username does not exist.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

removeAllUserAttributes

void removeAllUserAttributes(User user)
                             throws UserNotFoundException,
                                    OperationNotPermittedException,
                                    OperationFailedException

Remove all attributes for a user.

Parameters:

user - user to update.

Throws:

UserNotFoundException - user with supplied username does not exist.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

removeUser

boolean removeUser(User user)
                   throws OperationNotPermittedException,
                          OperationFailedException

Removes the user that matches the supplied name.

Parameters:

user - user to remove.

Returns:

true if the user was removed as a result of this call, false if the user does not exist.

Throws:

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

addGroup

Group addGroup(Group group)
               throws InvalidGroupException,
                      OperationNotPermittedException,
                      OperationFailedException

Adds a group to the directory store.

Parameters:

group - template of the group to add.

Returns:

the added group retrieved from the underlying store.

Throws:

InvalidGroupException - if the group already exists in ANY associated directory or the group template does not have the required properties populated.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

updateGroup

Group updateGroup(Group group)
                  throws GroupNotFoundException,
                         InvalidGroupException,
                         OperationNotPermittedException,
                         OperationFailedException

Updates the group.

Parameters:

group - The group to update.

Returns:

the updated group retrieved from the underlying store.

Throws:

GroupNotFoundException - if group with given name does not exist in ANY assigned directory.

InvalidGroupException - the supplied group is invalid.

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

setGroupAttribute

void setGroupAttribute(Group group,
                     String attributeName,
                     String attributeValue)
                       throws GroupNotFoundException,
                              OperationNotPermittedException,
                              OperationFailedException

Adds or updates a group's attributes with the new attributes. The attributes represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing. This will not remove any attributes.

Parameters:

group - name of group to update.

attributeName - the name up the attribute to add or update

attributeValue - the value of the attribute

Throws:

GroupNotFoundException - if the group could not be found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

setGroupAttribute

void setGroupAttribute(Group group,
                     String attributeName,
                     Set<String> attributeValues)
                       throws GroupNotFoundException,
                              OperationNotPermittedException,
                              OperationFailedException

Adds or updates a group's attributes with the new attributes. The attributes represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing. This will not remove any attributes.

Parameters:

group - name of group to update.

attributeName - the name up the attribute to add or update

attributeValues - a set of values to update

Throws:

GroupNotFoundException - if the group could not be found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

removeGroupAttribute

void removeGroupAttribute(Group group,
                        String attributeName)
                          throws GroupNotFoundException,
                                 OperationNotPermittedException,
                                 OperationFailedException

Removes all the values for a single attribute key for a group.

Parameters:

group - to update.

attributeName - name of attribute to remove.

Throws:

GroupNotFoundException - if the group could not be found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

removeAllGroupAttributes

void removeAllGroupAttributes(Group group)
                              throws GroupNotFoundException,
                                     OperationNotPermittedException,
                                     OperationFailedException

Removes all group attributes.

Parameters:

group - to update.

Throws:

GroupNotFoundException - if the group could not be found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

removeGroup

boolean removeGroup(Group group)
                    throws OperationNotPermittedException,
                           OperationFailedException

Removes the group that matches the supplied name.

Parameters:

group - to remove

Returns:

true if the group was removed as a result of this call, false if the group does not exist.

Throws:

OperationNotPermittedException - if the directory does not allow removal of this group

OperationFailedException - underlying directory implementation failed to execute the operation.

addUserToGroup

boolean addUserToGroup(User user,
                     Group group)
                       throws GroupNotFoundException,
                              UserNotFoundException,
                              OperationNotPermittedException,
                              OperationFailedException

Adds a user as a member of a group. This means that all user members of childGroup will appear as members of parentGroup to querying applications.

Parameters:

user - The user that will become a member of the group

group - The group that will gain a new member.

Returns:

true if the user was added to the group as a result of this call, false if the user is already a member of the group.

Throws:

UserNotFoundException - if the user could not be found

GroupNotFoundException - if the group could not be found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - underlying directory implementation failed to execute the operation.

addGroupToGroup

boolean addGroupToGroup(Group childGroup,
                      Group parentGroup)
                        throws GroupNotFoundException,
                               OperationNotPermittedException,
                               InvalidMembershipException,
                               OperationFailedException

Adds a group as a member of a parent group. Cyclic group membership are allowed (mainly because LDAP allows it) but not recommended. I.e. group A can have group B as its member and group B can have group A as its member at the same time.

Parameters:

childGroup - The group that will become a member of parentGroup

parentGroup - The group that will gain a new member

Returns:

true if the child group was added to the parent group as a result of this call, false if the group is already a member of the group.

Throws:

GroupNotFoundException - if any of the group could not be found. Use GroupNotFoundException.getGroupName() to find out which group wasn't found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

InvalidMembershipException - If the relationship would cause a circular reference.

OperationFailedException - underlying directory implementation failed to execute the operation.

removeUserFromGroup

boolean removeUserFromGroup(User user,
                          Group group)
                            throws GroupNotFoundException,
                                   UserNotFoundException,
                                   OperationNotPermittedException,
                                   OperationFailedException

Removes a user as a member of a group.

Parameters:

group - The group that will lose the member.

user - The user that will be removed from the group

Returns:

true if the user was removed from the group as a result of this call, false if the user is not a member of the group.

Throws:

UserNotFoundException - if the user could not be found

GroupNotFoundException - if the group could not be found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - if the operation failed for any other reason

removeGroupFromGroup

boolean removeGroupFromGroup(Group childGroup,
                           Group parentGroup)
                             throws GroupNotFoundException,
                                    OperationNotPermittedException,
                                    OperationFailedException

Removes a group as a member of a parent group.

Parameters:

childGroup - The group that will be removed from parentGroup

parentGroup - The group that will lose the member.

Returns:

true if childGroup was removed from parentGroup as a result of this call, false if childGroup is not a member of the parentGroup.

Throws:

GroupNotFoundException - if any of the groups could not be found. Use GroupNotFoundException.getGroupName() to find out which group wasn't found

OperationNotPermittedException - if the directory has been configured to not allow the operation to be performed

OperationFailedException - if the operation failed for any other reason

isUserDirectGroupMember

boolean isUserDirectGroupMember(User user,
                              Group group)
                                throws OperationFailedException

Determines if a user is a direct member of a group.

Parameters:

user - the user for whom to check the group membership

group - the group the user is believed to belong to

Returns:

true if the user is a direct member of the group, false otherwise (including if the user and/or group could not be found)

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

isGroupDirectGroupMember

boolean isGroupDirectGroupMember(Group childGroup,
                               Group parentGroup)
                                 throws OperationFailedException

Determines if a group is a direct member of another group.

Parameters:

childGroup - the group for which to check the parentGroup membership

parentGroup - the group the childGroup is believed to belong to

Returns:

true if the childGroup is a direct member of the parentGroup, false otherwise (including if neither group could be found)

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

searchUsersAllowingDuplicateNames

@Deprecated
Iterable<User> searchUsersAllowingDuplicateNames(Query<User> query)

Deprecated. this method violates the directory encapsulation of CrowdService and will be removed in the future. Consumers of this method should move to a different service.

Searches for User entities that match the supplied search query. Users with duplicate user names can be returned.

Parameters:

query - the search query.

Returns:

User entities matching the search query. An Iterable containing no results will be returned if there are no matches for the query.

getCapabilitiesForNewUsers

UserCapabilities getCapabilitiesForNewUsers()

Gets details of the possible operations that can be performed on new users.

Those capabilities reflects a specific moment in time and are subject to change if any user directory is added, removed or re-ordered.

Returns:

the capabilities a new user will have

See Also:

addUser(User, String)