Package com.atlassian.crowd.service.client

Interface CrowdClient

public interface CrowdClient

Atlassian Crowd client interface.

Method Summary

Modifier and Type	Method	Description
void	addGroup(Group group)	Adds a group to the remote Crowd server.
void	addGroupToGroup(String childGroup, String parentGroup)	Adds a group to a group.
UserWithAttributes	addUser(User user, PasswordCredential passwordCredential)	Deprecated. Use addUser(com.atlassian.crowd.model.user.UserWithAttributes, com.atlassian.crowd.embedded.api.PasswordCredential) instead.
UserWithAttributes	addUser(UserWithAttributes user, PasswordCredential passwordCredential)	Adds a new User to the remote Crowd server and will attempt to add the attributes atomically, but for Crowd servers < v2.9.0 atomic attribute adding may not be supported.
void	addUserToGroup(String username, String groupName)	Adds a user to a group.
String	authenticateSSOUser(UserAuthenticationContext userAuthenticationContext)	Authenticates a Single-Sign-On (SSO) User.
String	authenticateSSOUser(UserAuthenticationContext userAuthenticationContext, long duration)	Authenticates a Single-Sign-On (SSO) User.
String	authenticateSSOUserWithoutValidatingPassword(UserAuthenticationContext userAuthenticationContext)	Authenticates a Single-Sign-On (SSO) User without validating password.
User	authenticateUser(String username, String password)	Authenticates a user with the server.
void	expireAllPasswords()	Expires all passwords for all users in all directories for this application, regardless of group membership.
User	findUserFromSSOToken(String token)	Returns the user from the specified user token.
List<Group>	getChildGroupsOfGroup(String groupName, int startIndex, int maxResults)	Searches for groups who are direct members of a group.
CookieConfiguration	getCookieConfiguration()	Returns the cookie configuration.
String	getCurrentEventToken()	Returns a token that can be used for querying events that have happened after the token was generated.
Group	getGroup(String name)	Gets a group by name.
List<Group>	getGroupsForNestedUser(String userName, int startIndex, int maxResults)	Searches for groups that a user is a nested member of.
List<Group>	getGroupsForUser(String userName, int startIndex, int maxResults)	Searches for groups that a user is a direct member of.
List<GroupWithAttributes>	getGroupsWithAttributesForUser(String userName, int startIndex, int maxResults)	Searches for groups that a user is a member of, and returns those groups with all their attributes.
GroupWithAttributes	getGroupWithAttributes(String name)	Gets a group with attributes by name.
Iterable<Membership>	getMemberships()	Gets the full group membership details for all groups with all direct user members and child groups.
List<String>	getNamesOfChildGroupsOfGroup(String groupName, int startIndex, int maxResults)	Searches for groups who are direct members of a group, returning the group names.
List<String>	getNamesOfGroupsForNestedUser(String userName, int startIndex, int maxResults)	Searches for groups that a user is a nested member of, returning the group names.
List<String>	getNamesOfGroupsForUser(String userName, int startIndex, int maxResults)	Searches for groups that a user is a direct member of, returning the group names.
List<String>	getNamesOfNestedChildGroupsOfGroup(String groupName, int startIndex, int maxResults)	Searches for groups who are nested members of a group, returning the group names.
List<String>	getNamesOfNestedUsersOfGroup(String groupName, int startIndex, int maxResults)	Searches for users who are nested members of a group, returning the user names.
List<String>	getNamesOfParentGroupsForGroup(String groupName, int startIndex, int maxResults)	Searches for groups that a group is a direct member of, returning the group names.
List<String>	getNamesOfParentGroupsForNestedGroup(String groupName, int startIndex, int maxResults)	Searches for groups that a group is a nested member of, returning the group names.
List<String>	getNamesOfUsersOfGroup(String groupName, int startIndex, int maxResults)	Searches for users who are direct members of a group, returning the user names.
List<Group>	getNestedChildGroupsOfGroup(String groupName, int startIndex, int maxResults)	Searches for groups who are nested members of a group.
List<User>	getNestedUsersOfGroup(String groupName, int startIndex, int maxResults)	Searches for users who are nested members of a group.
Events	getNewEvents(String eventToken)	Returns an events object which contains a new eventToken and events that happened after the given eventToken was generated.
List<Group>	getParentGroupsForGroup(String groupName, int startIndex, int maxResults)	Searches for groups that a group is a direct member of.
List<Group>	getParentGroupsForNestedGroup(String groupName, int startIndex, int maxResults)	Searches for groups that a group is a nested member of.
User	getUser(String name)	Gets a User by user name.
User	getUserByKey(String key)	Gets a User by key.
List<User>	getUsersOfGroup(String groupName, int startIndex, int maxResults)	Searches for users who are direct members of a group.
UserWithAttributes	getUserWithAttributes(String name)	Gets a User with Attributes by user name.
String	getWebhook(long webhookId)	Retrieves a Webhook endpoint URL.
void	invalidateSSOToken(String token)	Invalidates a token.
void	invalidateSSOTokensForUser(String username)	Invalidates all tokens for a given user name
void	invalidateSSOTokensForUser(String username, String exclude)	Invalidates all tokens for a given user name, except for the given token.
boolean	isGroupDirectGroupMember(String childName, String parentName)	Tests if a group is a direct member of a group.
boolean	isUserDirectGroupMember(String username, String groupName)	Tests if a user is a direct member of a group.
boolean	isUserNestedGroupMember(String username, String groupName)	Tests if a user is a nested member of a group.
long	registerWebhook(String endpointUrl, String token)	Registers a new Webhook on the server.
void	removeGroup(String groupName)	Removes a group from the remote Crowd server
void	removeGroupAttributes(String groupName, String attributeName)	Removes a group attribute (set) from the server.
void	removeGroupFromGroup(String childGroup, String parentGroup)	Removes a group to a group.
void	removeUser(String username)	Removes a user from the remote Crowd server
void	removeUserAttributes(String username, String attributeName)	Removes a user attribute from the server.
void	removeUserFromGroup(String username, String groupName)	Removes a user from a group.
User	renameUser(String oldUsername, String newUsername)	Renames a user on the remote Crowd server, initially finding them by their current username.
void	requestPasswordReset(String username)	Requests a password reset.
void	requestUsernames(String email)	Sends the usernames associated with the given email address.
List<String>	searchGroupNames(SearchRestriction searchRestriction, int startIndex, int maxResults)	Searches for group names matching the searchRestriction criteria.
List<Group>	searchGroups(SearchRestriction searchRestriction, int startIndex, int maxResults)	Searches for groups matching the following criteria.
List<GroupWithAttributes>	searchGroupsWithAttributes(SearchRestriction searchRestriction, int startIndex, int maxResults)	Searches for groups (with their attributes) matching the following criteria.
List<String>	searchUserNames(SearchRestriction searchRestriction, int startIndex, int maxResults)	Searches for usernames matching the searchRestriction criteria.
List<User>	searchUsers(SearchRestriction searchRestriction, int startIndex, int maxResults)	Searches for users matching the following criteria.
List<UserWithAttributes>	searchUsersWithAttributes(SearchRestriction searchRestriction, int startIndex, int maxResults)	Searches for users (with their attributes) matching the following criteria.
void	shutdown()	Closes this Crowd Client and releases any system resources associated with the client.
void	storeGroupAttributes(String groupName, Map<String,Set<String>> attributes)	Stores the group's attributes on the remote Crowd server.
void	storeUserAttributes(String username, Map<String,Set<String>> attributes)	Stores the user's attributes on the remote Crowd server.
void	testConnection()	Tests if the connection is OK.
void	unregisterWebhook(long webhookId)	Unregisters a Webhook on the server.
void	updateGroup(Group group)	Updates a group on the remote Crowd server.
void	updateUser(User user)	Updates a user on the remote Crowd server.
void	updateUserCredential(String username, String password)	Updates the user's password on the remote Crowd server.
User	userAuthenticated(String username)
void	validateSSOAuthentication(String token, List<ValidationFactor> validationFactors)	Validates the SSO authentication.
Session	validateSSOAuthenticationAndGetSession(String token, List<ValidationFactor> validationFactors)	Validates the SSO authentication.

Method Details

getUser

User getUser(String name)
      throws UserNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Gets a User by user name.

Parameters:

name - Name of the user to retrieve

Returns:

A User.

Throws:

UserNotFoundException - if the user is not found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getUserWithAttributes

UserWithAttributes getUserWithAttributes(String name)
                                  throws UserNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Gets a User with Attributes by user name.

Parameters:

name - Name of the user to retrieve

Returns:

A User.

Throws:

UserNotFoundException - if the user is not found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getUserByKey

User getUserByKey(String key)
           throws UserNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Gets a User by key.

Parameters:

key - Name of the user to retrieve

Returns:

A User.

Throws:

UserNotFoundException - if the user is not found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

authenticateUser

User authenticateUser(String username,
 String password)
               throws UserNotFoundException,
InactiveAccountException,
ExpiredCredentialException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Authenticates a user with the server.

Parameters:

username - Name of the user to authenticate.

password - Password of the user to authenticate.

Returns:

user if the user is correctly authenticated

Throws:

UserNotFoundException - if the user could not be found

InactiveAccountException - if the user account is not active

ExpiredCredentialException - if the user credentials have expired

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

userAuthenticated

@ExperimentalApi
User userAuthenticated(String username)
                throws ApplicationPermissionException,
OperationFailedException,
InvalidAuthenticationException,
UnsupportedCrowdApiException,
UserNotFoundException,
InactiveAccountException

Throws:

ApplicationPermissionException

OperationFailedException

InvalidAuthenticationException

UnsupportedCrowdApiException

UserNotFoundException

InactiveAccountException

addUser

@Nullable
UserWithAttributes addUser(UserWithAttributes user,
 PasswordCredential passwordCredential)
                    throws InvalidUserException,
InvalidCredentialException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Adds a new User to the remote Crowd server and will attempt to add the attributes atomically, but for Crowd servers < v2.9.0 atomic attribute adding may not be supported. If adding attributes is not supported, NULL will be returned and it is the clients responsibility to call storeUserAttributes(String, Map) afterwards.

Parameters:

user - The user to add

passwordCredential - user password

Returns:

User the user created by the server, or null if the server does not support returning users.

Throws:

InvalidUserException - if the user is invalid. This may be because a user of the same name already exists, or does not pass the server side validation rules.

InvalidCredentialException - if the password is invalid. It must conform to the rules set on the server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

addUser

@Nullable
@Deprecated
UserWithAttributes addUser(User user,
 PasswordCredential passwordCredential)
                    throws InvalidUserException,
InvalidCredentialException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Deprecated.

Use addUser(com.atlassian.crowd.model.user.UserWithAttributes, com.atlassian.crowd.embedded.api.PasswordCredential) instead. Since v2.9

Adds a new User to the remote Crowd server. This may return NULL if the remote server is older than v2.8. This will not store the users attributes.

Parameters:

user - The user to add

passwordCredential - user password

Returns:

User the user created by the server, or null if the server does not support returning users.

Throws:

InvalidUserException - if the user is invalid. This may be because a user of the same name already exists, or does not pass the server side validation rules.

InvalidCredentialException - if the password is invalid. It must conform to the rules set on the server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

updateUser

void updateUser(User user)
         throws InvalidUserException,
UserNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Updates a user on the remote Crowd server.

Parameters:

user - The user to update

Throws:

InvalidUserException - the details of the user to be updated are invalid. This may be because the user details do not pass the server side validation rules.

UserNotFoundException - if the user does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

renameUser

User renameUser(String oldUsername,
 String newUsername)
         throws InvalidUserException,
UserNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Renames a user on the remote Crowd server, initially finding them by their current username.

Parameters:

oldUsername - current name of the user to rename

newUsername - the intended new name of the user; must not be the same as oldUsername

Returns:

the user with the new name

Throws:

InvalidUserException - the details of the user to be updated are invalid. This may be because the user details do not pass the server side validation rules.

UserNotFoundException - if the user does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

updateUserCredential

void updateUserCredential(String username,
 @Nullable
 String password)
                   throws UserNotFoundException,
InvalidCredentialException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Updates the user's password on the remote Crowd server.

Parameters:

username - Name of the user to update.

password - New password. A null value indicates that the user's password should be cleared.

Throws:

UserNotFoundException - if the user does not exist on the remote Crowd server

InvalidCredentialException - if the password is invalid. It must conform to the rules set on the server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

storeUserAttributes

void storeUserAttributes(String username,
 Map<String,Set<String>> attributes)
                  throws UserNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Stores the user's attributes on the remote Crowd server.

Parameters:

username - Name of the user.

attributes - Set of Attributes to store. Attributes will be added or if an attribute with the same key exists will be replaced.

Throws:

UserNotFoundException - if the user does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

removeUserAttributes

void removeUserAttributes(String username,
 String attributeName)
                   throws UserNotFoundException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Removes a user attribute from the server. If the attribute to be removed does not exist, no error is reported.

Parameters:

username - Name of the user

attributeName - Attribute key.

Throws:

UserNotFoundException - if the user does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

removeUser

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

Removes a user from the remote Crowd server

Parameters:

username - Name of the user to remove.

Throws:

UserNotFoundException - if the user does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

requestPasswordReset

void requestPasswordReset(String username)
                   throws UserNotFoundException,
InvalidEmailAddressException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Requests a password reset.

Parameters:

username - name of the user

Throws:

UserNotFoundException - if the user does not exist

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

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

requestUsernames

void requestUsernames(String email)
               throws InvalidEmailAddressException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Sends the usernames associated with the given email address. No email will be sent if there are no usernames associated with a given email.

Parameters:

email - email address of the user

Throws:

InvalidEmailAddressException - if the email is not valid

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getGroup

Group getGroup(String name)
        throws GroupNotFoundException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Gets a group by name.

Parameters:

name - name of the group to retrieve.

Returns:

A Group

Throws:

GroupNotFoundException - if the group does not exist on the remote server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getGroupWithAttributes

GroupWithAttributes getGroupWithAttributes(String name)
                                    throws GroupNotFoundException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Gets a group with attributes by name.

Parameters:

name - name of the group to retrieve.

Returns:

A Group with attributes.

Throws:

GroupNotFoundException - if the group does not exist on the remote server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

addGroup

void addGroup(Group group)
       throws InvalidGroupException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Adds a group to the remote Crowd server.

Parameters:

group - Group to add.

Throws:

InvalidGroupException - if the group is invalid. This may be because a group of the same name already exists, or does not pass the server side validation rules

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

updateGroup

void updateGroup(Group group)
          throws InvalidGroupException,
GroupNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Updates a group on the remote Crowd server.

Parameters:

group - Group to update.

Throws:

InvalidGroupException - The group is invalid. This may be because the group does not pass the server side validation rules.

GroupNotFoundException - if the group does not exist on the remote server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

storeGroupAttributes

void storeGroupAttributes(String groupName,
 Map<String,Set<String>> attributes)
                   throws GroupNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Stores the group's attributes on the remote Crowd server.

Parameters:

groupName - Name of the group.

attributes - Set of Attributes to store. Attributes will be added or if an attribute with the same key exists will be replaced.

Throws:

GroupNotFoundException - if the group does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

removeGroupAttributes

void removeGroupAttributes(String groupName,
 String attributeName)
                    throws GroupNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Removes a group attribute (set) from the server. If the attribute to be removed does not exist, no error is reported.

Parameters:

groupName - Name of the group

attributeName - Attribute key.

Throws:

GroupNotFoundException - the group does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

removeGroup

void removeGroup(String groupName)
          throws GroupNotFoundException,
OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Removes a group from the remote Crowd server

Parameters:

groupName - Name of the group to remove.

Throws:

GroupNotFoundException - the group does not exist on the remote Crowd server

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

isUserDirectGroupMember

boolean isUserDirectGroupMember(String username,
 String groupName)
                         throws OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

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

Parameters:

username - User name

groupName - Group Name

Returns:

true if the member is a direct member of the group.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

isUserNestedGroupMember

boolean isUserNestedGroupMember(String username,
 String groupName)
                         throws OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Tests if a user is a nested member of a group.

Parameters:

username - User name

groupName - Group Name

Returns:

true if the member is a nested member of the group.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

isGroupDirectGroupMember

boolean isGroupDirectGroupMember(String childName,
 String parentName)
                          throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Tests if a group is a direct member of a group.

Parameters:

childName - Name of the child group

parentName - Name of the Parent group

Returns:

true if the child group is a direct member of the parent group.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

addUserToGroup

void addUserToGroup(String username,
 String groupName)
             throws GroupNotFoundException,
UserNotFoundException,
OperationFailedException,
MembershipAlreadyExistsException,
InvalidAuthenticationException,
ApplicationPermissionException

Adds a user to a group.

Parameters:

username - Name of the user to add to the group.

groupName - Name of the group to be added to.

Throws:

GroupNotFoundException - if the group does not exist.

UserNotFoundException - if the user does not exist.

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

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

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

addGroupToGroup

void addGroupToGroup(String childGroup,
 String parentGroup)
              throws GroupNotFoundException,
UserNotFoundException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
MembershipAlreadyExistsException

Adds a group to a group.

Parameters:

childGroup - Name of the group to add to the parent group.

parentGroup - Name of the group the child will be added to.

Throws:

GroupNotFoundException - if either group does not exist

UserNotFoundException - if the user does not exist

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

MembershipAlreadyExistsException - if the child group is already a member of the parent group

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

removeUserFromGroup

void removeUserFromGroup(String username,
 String groupName)
                  throws MembershipNotFoundException,
GroupNotFoundException,
UserNotFoundException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Removes a user from a group.

Parameters:

username - Name of the user to add to the group.

groupName - Name of the group to be added to.

Throws:

MembershipNotFoundException - if the membership does not exist

GroupNotFoundException - if the group does not exist.

UserNotFoundException - if the user does not exist.

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

removeGroupFromGroup

void removeGroupFromGroup(String childGroup,
 String parentGroup)
                   throws MembershipNotFoundException,
GroupNotFoundException,
OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Removes a group to a group.

Parameters:

childGroup - Name of the group to be removed from the parent group.

parentGroup - Name of the group the child group will be removed from.

Throws:

GroupNotFoundException - if either group does not exist.

MembershipNotFoundException - if there is not parent-child relationship between the specified groups

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if for some reason the operation has failed

testConnection

void testConnection()
             throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Tests if the connection is OK. This test uses a user search to validate the connection. It will fail if the application does not have permission to perform this very basic operation.

Throws:

InvalidAuthenticationException - if the application and password are not valid

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

OperationFailedException - if the test fails

searchUsers

List<User> searchUsers(SearchRestriction searchRestriction,
 int startIndex,
 int maxResults)
                throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for users matching the following criteria.

Parameters:

searchRestriction - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of users satisfying the search restriction.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

searchUsersWithAttributes

List<UserWithAttributes> searchUsersWithAttributes(SearchRestriction searchRestriction,
 int startIndex,
 int maxResults)
                                            throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for users (with their attributes) matching the following criteria.

Parameters:

searchRestriction - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of users (with their attributes) satisfying the search restriction.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

searchUserNames

List<String> searchUserNames(SearchRestriction searchRestriction,
 int startIndex,
 int maxResults)
                      throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for usernames matching the searchRestriction criteria.

Parameters:

searchRestriction - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of usernames satisfying the search restriction.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

searchGroups

List<Group> searchGroups(SearchRestriction searchRestriction,
 int startIndex,
 int maxResults)
                  throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for groups matching the following criteria.

Parameters:

searchRestriction - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

searchGroupsWithAttributes

List<GroupWithAttributes> searchGroupsWithAttributes(SearchRestriction searchRestriction,
 int startIndex,
 int maxResults)
                                              throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for groups (with their attributes) matching the following criteria.

Parameters:

searchRestriction - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups (with their attributes) satisfying the search restriction.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

searchGroupNames

List<String> searchGroupNames(SearchRestriction searchRestriction,
 int startIndex,
 int maxResults)
                       throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for group names matching the searchRestriction criteria.

Parameters:

searchRestriction - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getUsersOfGroup

List<User> getUsersOfGroup(String groupName,
 int startIndex,
 int maxResults)
                    throws GroupNotFoundException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Searches for users who are direct members of a group.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of users satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfUsersOfGroup

List<String> getNamesOfUsersOfGroup(String groupName,
 int startIndex,
 int maxResults)
                             throws GroupNotFoundException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Searches for users who are direct members of a group, returning the user names.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of user names satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getChildGroupsOfGroup

List<Group> getChildGroupsOfGroup(String groupName,
 int startIndex,
 int maxResults)
                           throws GroupNotFoundException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Searches for groups who are direct members of a group.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restrictions

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfChildGroupsOfGroup

List<String> getNamesOfChildGroupsOfGroup(String groupName,
 int startIndex,
 int maxResults)
                                   throws OperationFailedException,
GroupNotFoundException,
InvalidAuthenticationException,
ApplicationPermissionException

Searches for groups who are direct members of a group, returning the group names.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getGroupsForUser

List<Group> getGroupsForUser(String userName,
 int startIndex,
 int maxResults)
                      throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
UserNotFoundException

Searches for groups that a user is a direct member of.

Parameters:

userName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

UserNotFoundException - if the user could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getGroupsWithAttributesForUser

List<GroupWithAttributes> getGroupsWithAttributesForUser(String userName,
 int startIndex,
 int maxResults)
                                                  throws UserNotFoundException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Searches for groups that a user is a member of, and returns those groups with all their attributes. This will only work for Crowd servers >= 2.9, otherwise attributes will not be returned and behaviour will be the same as getGroupsForUser(java.lang.String, int, int).

Parameters:

userName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

UserNotFoundException - if the user could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfGroupsForUser

List<String> getNamesOfGroupsForUser(String userName,
 int startIndex,
 int maxResults)
                              throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
UserNotFoundException

Searches for groups that a user is a direct member of, returning the group names.

Parameters:

userName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction.

Throws:

UserNotFoundException - if the user could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getParentGroupsForGroup

List<Group> getParentGroupsForGroup(String groupName,
 int startIndex,
 int maxResults)
                             throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for groups that a group is a direct member of.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfParentGroupsForGroup

List<String> getNamesOfParentGroupsForGroup(String groupName,
 int startIndex,
 int maxResults)
                                     throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for groups that a group is a direct member of, returning the group names.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNestedUsersOfGroup

List<User> getNestedUsersOfGroup(String groupName,
 int startIndex,
 int maxResults)
                          throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for users who are nested members of a group.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of users satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfNestedUsersOfGroup

List<String> getNamesOfNestedUsersOfGroup(String groupName,
 int startIndex,
 int maxResults)
                                   throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for users who are nested members of a group, returning the user names.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of user names satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNestedChildGroupsOfGroup

List<Group> getNestedChildGroupsOfGroup(String groupName,
 int startIndex,
 int maxResults)
                                 throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for groups who are nested members of a group.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfNestedChildGroupsOfGroup

List<String> getNamesOfNestedChildGroupsOfGroup(String groupName,
 int startIndex,
 int maxResults)
                                         throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for groups who are nested members of a group, returning the group names.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getGroupsForNestedUser

List<Group> getGroupsForNestedUser(String userName,
 int startIndex,
 int maxResults)
                            throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
UserNotFoundException

Searches for groups that a user is a nested member of.

Parameters:

userName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

UserNotFoundException - if the user could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfGroupsForNestedUser

List<String> getNamesOfGroupsForNestedUser(String userName,
 int startIndex,
 int maxResults)
                                    throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
UserNotFoundException

Searches for groups that a user is a nested member of, returning the group names.

Parameters:

userName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction.

Throws:

UserNotFoundException - if the user could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getParentGroupsForNestedGroup

List<Group> getParentGroupsForNestedGroup(String groupName,
 int startIndex,
 int maxResults)
                                   throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for groups that a group is a nested member of.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of groups satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getNamesOfParentGroupsForNestedGroup

List<String> getNamesOfParentGroupsForNestedGroup(String groupName,
 int startIndex,
 int maxResults)
                                           throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
GroupNotFoundException

Searches for groups that a group is a nested member of, returning the group names.

Parameters:

groupName - restriction on the search

startIndex - starting index of the search results

maxResults - maximum number of results returned from the search

Returns:

List of group names satisfying the search restriction.

Throws:

GroupNotFoundException - if the group could not be found

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getMemberships

Iterable<Membership> getMemberships()
                             throws OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException,
UnsupportedCrowdApiException

Gets the full group membership details for all groups with all direct user members and child groups. The result may be large and this operation may be slow.

This method is only supported when the server supports version 1.1 of the user management API. Clients should be ready to catch UnsupportedCrowdApiException and fall back to another technique if they need to remain backwards compatible.

Returns:

an Iterable of the memberships for all groups

Throws:

UnsupportedCrowdApiException - if the server does not support version 1.1 of the user management API

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

findUserFromSSOToken

User findUserFromSSOToken(String token)
                   throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
InvalidTokenException

Returns the user from the specified user token.

Parameters:

token - user token used to find the authenticated user.

Returns:

User associated with the token.

Throws:

InvalidTokenException - if the provided token is not valid

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

authenticateSSOUser

String authenticateSSOUser(UserAuthenticationContext userAuthenticationContext)
                    throws ApplicationAccessDeniedException,
InactiveAccountException,
ExpiredCredentialException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Authenticates a Single-Sign-On (SSO) User.

Parameters:

userAuthenticationContext - the user's authentication details.

Returns:

SSO token if successful.

Throws:

ApplicationAccessDeniedException - if the user does not have access to authenticate against the application

InactiveAccountException - if the user account is inactive

ExpiredCredentialException - if the user password has expired and the user is required to change their password

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

authenticateSSOUser

String authenticateSSOUser(UserAuthenticationContext userAuthenticationContext,
 long duration)
                    throws ApplicationAccessDeniedException,
InactiveAccountException,
ExpiredCredentialException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Authenticates a Single-Sign-On (SSO) User.

Parameters:

userAuthenticationContext - the user's authentication details.

duration - requested duration of the new token (in seconds)

Returns:

SSO token if successful.

Throws:

ApplicationAccessDeniedException - if the user does not have access to authenticate against the application

InactiveAccountException - if the user account is inactive

ExpiredCredentialException - if the user password has expired and the user is required to change their password

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

authenticateSSOUserWithoutValidatingPassword

String authenticateSSOUserWithoutValidatingPassword(UserAuthenticationContext userAuthenticationContext)
                                             throws ApplicationPermissionException,
InactiveAccountException,
ApplicationAccessDeniedException,
InvalidAuthenticationException,
OperationFailedException

Authenticates a Single-Sign-On (SSO) User without validating password.

Parameters:

userAuthenticationContext - the user's authentication details.

Returns:

SSO token if successful.

Throws:

ApplicationAccessDeniedException - if the user does not have access to authenticate against the application

InactiveAccountException - if the user account has expired

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

validateSSOAuthentication

void validateSSOAuthentication(String token,
 List<ValidationFactor> validationFactors)
                        throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException,
InvalidTokenException

Validates the SSO authentication. Throws InvalidAuthenticationException if the SSO authentication is not valid.

Parameters:

token - Crowd SSO token

validationFactors - Details of where the user's come from. If presented, must match those presented during authentication.

Throws:

InvalidTokenException - if the supplied token is not valid

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

validateSSOAuthenticationAndGetSession

Session validateSSOAuthenticationAndGetSession(String token,
 List<ValidationFactor> validationFactors)
                                        throws InvalidTokenException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Validates the SSO authentication. Throws InvalidAuthenticationException if the SSO authentication is not valid.

Parameters:

token - Crowd SSO token

validationFactors - Details of where the user's come from. If presented, must match those presented during authentication.

Returns:

the current session

Throws:

InvalidTokenException - if the supplied token is not valid

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

invalidateSSOToken

void invalidateSSOToken(String token)
                 throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Invalidates a token. If the token does not exist, the token should still return silently.

Parameters:

token - a non-empty token to invalidate

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

invalidateSSOTokensForUser

void invalidateSSOTokensForUser(String username)
                         throws OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Invalidates all tokens for a given user name

Parameters:

username - User whose sessions will be invalidated

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

UnsupportedCrowdApiException - if the remote server does not support this operation

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

invalidateSSOTokensForUser

void invalidateSSOTokensForUser(String username,
 String exclude)
                         throws OperationFailedException,
ApplicationPermissionException,
InvalidAuthenticationException

Invalidates all tokens for a given user name, except for the given token.

Parameters:

username - User whose sessions will be invalidated

exclude - Token to be saved

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server

InvalidAuthenticationException - if the application and password are not valid

UnsupportedCrowdApiException - if the remote server does not support this operation

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

getCookieConfiguration

CookieConfiguration getCookieConfiguration()
                                    throws OperationFailedException,
InvalidAuthenticationException,
ApplicationPermissionException

Returns the cookie configuration.

Returns:

cookie configuration

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

OperationFailedException - if the operation has failed for any other reason, including invalid arguments and the operation not being supported on the server.

shutdown

void shutdown()

Closes this Crowd Client and releases any system resources associated with the client.

The client can no longer be used once shutdown.

Calling this method more than once will have no effect.

getCurrentEventToken

String getCurrentEventToken()
                     throws ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException,
IncrementalSynchronisationNotAvailableException

Returns a token that can be used for querying events that have happened after the token was generated.

If the event token has not changed since the last call to this method, it is guaranteed that no new events have been received.

The format of event token is implementation specific and can change without a warning.

Returns:

token that can be used for querying events that have happened after the token was generated

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

UnsupportedCrowdApiException - if the remote server does not support this operation

OperationFailedException - if the operation has failed for any other reason, including invalid arguments

IncrementalSynchronisationNotAvailableException - if the application cannot provide incremental synchronisation

Since:

2.3

getNewEvents

Events getNewEvents(String eventToken)
             throws EventTokenExpiredException,
ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Returns an events object which contains a new eventToken and events that happened after the given eventToken was generated.

If for any reason event store is unable to retrieve events that happened after the event token was generated, an EventTokenExpiredException will be thrown. The caller is then expected to call getCurrentEventToken() again before asking for new events.

Parameters:

eventToken - event token that was retrieved by a call to getCurrentEventToken() or this method

Returns:

events object which contains a new eventToken and events that happened after the given eventToken was generated

Throws:

EventTokenExpiredException - if events that happened after the event token was generated can not be retrieved

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

UnsupportedCrowdApiException - if the remote server does not support this operation

OperationFailedException - if the operation has failed for any other reason, including invalid arguments

Since:

2.3

getWebhook

String getWebhook(long webhookId)
           throws InvalidAuthenticationException,
ApplicationPermissionException,
OperationFailedException,
WebhookNotFoundException

Retrieves a Webhook endpoint URL.

Parameters:

webhookId - a Webhook identifier, as returned by registerWebhook(String, String)

Returns:

the endpoint URL associated to the Webhook

Throws:

InvalidAuthenticationException - if the application and password are not valid.

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

WebhookNotFoundException - if the Webhook is not registered

OperationFailedException - if the operation has failed for any other reason.

registerWebhook

long registerWebhook(String endpointUrl,
 @Nullable
 String token)
              throws InvalidAuthenticationException,
ApplicationPermissionException,
OperationFailedException

Registers a new Webhook on the server. The Webhook will be called back when the Crowd server produces new events. Applications are expected to request a new event token getCurrentEventToken() after registering a Webhook, so then can obtain the new events using getNewEvents(String) in the Webhook callback.

This operation is idempotent, i.e., an attempt to register a callback with the same endpointUrl as an existing Webhook already registered by the same application will return the identifier of the existing Webhook.

If an application dies, or otherwise terminates without unregistering its Webhooks, Crowd reserves its rights to eventually unregister any Webhook that is no longer responding to the pings with an HTTP 2xx status code. Crowd may implement a fault-tolerant policy for Webhooks that are temporarily unreachable, but it is the application's responsibility to maintain the connection.

Parameters:

endpointUrl - URL of the HTTP endpoint provided by the application. Crowd will ping the Webhook by issuing a body-less POST request when new events are available. The Webhook must respond with an HTTP 2xx status code.

token - the token that Crowd will present when pinging the Webhook (optional).

Returns:

an identifier of the Webhook, that can be used to unregister it unregisterWebhook(long).

Throws:

InvalidAuthenticationException - if the application and password are not valid.

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

OperationFailedException - if the operation has failed for any other reason.

unregisterWebhook

void unregisterWebhook(long webhookId)
                throws ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException,
WebhookNotFoundException

Unregisters a Webhook on the server. Well-behaved applications are expected to unregister their Webhooks when they no longer need them to free resources on the server. Otherwise, Crowd may unilaterally unregister the non-responding Webhooks, as described in registerWebhook(String, String).

Parameters:

webhookId - The identifier of the Webhook returned by registerWebhook(String, String).

Throws:

ApplicationPermissionException - if the Webhook identifier does not match any of the Webhooks previously registered by the application.

InvalidAuthenticationException - if the application and password are not valid.

WebhookNotFoundException - if the Webhook is not found, or it not owned by the application, or the remote API does not support this operation

OperationFailedException - if the operation has failed for any other reason.

expireAllPasswords

void expireAllPasswords()
                 throws ApplicationPermissionException,
InvalidAuthenticationException,
OperationFailedException

Expires all passwords for all users in all directories for this application, regardless of group membership.

Throws:

ApplicationPermissionException - if the application credentials are not correct.

InvalidAuthenticationException - if the authentication is not correct.

OperationFailedException - if the operation fails for any of the directories. This would mean some passwords have expired while others have not.