public interface

CrowdService

com.atlassian.crowd.embedded.api.CrowdService
Known Indirect Subclasses

Class Overview

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

Summary

Public Methods
Group addGroup(Group group)
Adds a group to the directory store.
void 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.
void 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.
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(String childGroupName, String parentGroupName)
Returns true if childGroupName is a direct or indirect (nested) member of parentGroupName.
boolean isGroupMemberOfGroup(Group childGroup, Group parentGroup)
Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup.
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.
<T> Iterable<T> search(Query<T> query)
Searches for entities (e.g.
Iterable<User> searchUsersAllowingDuplicateNames(Query<User> query)
Searches for User entities that match the supplied search query.
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, String attributeValue)
Adds or updates a user's attribute with the new attribute value.
void setUserAttribute(User user, String attributeName, Set<String> attributeValues)
Adds or updates a user's attribute with the new attribute values.
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.

Public Methods

public Group addGroup (Group group)

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.

public void addGroupToGroup (Group childGroup, Group parentGroup)

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
Throws
GroupNotFoundException if any of the group could not be found. Use 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.

public User addUser (User user, String credential)

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

public void addUserToGroup (User user, Group group)

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.
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.

public User authenticate (String name, String credential)

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.

public 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.

public 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.

public 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

public 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

public boolean isGroupDirectGroupMember (Group childGroup, Group parentGroup)

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.

public 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.

public 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.

public boolean isUserDirectGroupMember (User user, Group group)

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.

public 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.

public 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.

public void removeAllGroupAttributes (Group group)

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.

public void removeAllUserAttributes (User user)

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.

public boolean removeGroup (Group group)

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.

public void removeGroupAttribute (Group group, String attributeName)

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.

public boolean removeGroupFromGroup (Group childGroup, Group parentGroup)

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 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

public boolean removeUser (User user)

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.

public void removeUserAttribute (User user, String attributeName)

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.

public boolean removeUserFromGroup (User user, Group group)

Removes a user as a member of a group.

Parameters
user The user that will be removed from the group
group The group that will lose the member.
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

public 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.

public Iterable<User> searchUsersAllowingDuplicateNames (Query<User> query)

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.

public void setGroupAttribute (Group group, String attributeName, Set<String> attributeValues)

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.

public void setGroupAttribute (Group group, String attributeName, String attributeValue)

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.

public void setUserAttribute (User user, String attributeName, String attributeValue)

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.

public void setUserAttribute (User user, String attributeName, Set<String> attributeValues)

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.

public Group updateGroup (Group group)

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.

public User updateUser (User user)

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.

public void updateUserCredential (User user, String credential)

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.