com.atlassian.crowd.manager.directory

Interface DirectoryManager

All Known Implementing Classes:

DirectoryManagerGeneric, RecoveryModeAwareDirectoryManager

public interface DirectoryManager

A service interface providing:

1. Directory CRUD Operations
2. Token Operations
3. RemoteDirectory User Operations
4. RemoteDirectory Group Operations
5. RemoteDirectory Membership Operations
6. RemoteDirectory Bulk Operations

Methods on this interface operate on a single directory whereas methods on the ApplicationService interface amalgamate results from multiple directories.

In the future, it is likely that we will break up the DirectoryManager into a DirectoryManager (directory CRUD), RemoteDirectoryManager (remote directory delegater) and a TokenManager (token ops) for better functional decomposition.

Method Summary

Modifier and Type	Method and Description
BulkAddResult<Group>	addAllGroups(long directoryId, Collection<GroupTemplate> groups, boolean overwrite) Will add a collection of Group to the directory specified by the passed in directoryId param.
BulkAddResult<User>	addAllUsers(long directoryId, Collection<UserTemplateWithCredentialAndAttributes> users, boolean overwrite) Will add a collection of users to the directory specified by the passed in directoryId param.
BulkAddResult<String>	addAllUsersToGroup(long directoryID, Collection<String> userNames, String groupName) A bulk version of addUserToGroup(long, String, String).
Directory	addDirectory(Directory directory) Adds the given directory.
Group	addGroup(long directoryId, GroupTemplate group) Adds a Group to the directory specified by the passed in directoryId.
void	addGroupToGroup(long directoryId, String childGroup, String parentGroup) Adds an existing child group as direct member of an existing parent group in the directory specified by the passed in directoryId.
User	addUser(long directoryId, UserTemplate user, PasswordCredential credential) Deprecated. Use addUser(long, com.atlassian.crowd.model.user.UserTemplateWithAttributes, com.atlassian.crowd.embedded.api.PasswordCredential) instead. Since v2.9
UserWithAttributes	addUser(long directoryId, UserTemplateWithAttributes user, PasswordCredential credential) Adds a UserWithAttributes to the directory specified by the passed in directoryId.
void	addUserToGroup(long directoryId, String username, String groupName) Adds an existing user as a direct member of an existing group in the directory specified by the passed in directoryId.
User	authenticateUser(long directoryId, String username, PasswordCredential passwordCredential)
BoundedCount	countDirectMembersOfGroup(long directoryId, String groupName, int querySizeHint) Count the direct members of a group in the provided directory with an upper bound.
void	expireAllPasswords(long directoryId) Sets the UserConstants.REQUIRES_PASSWORD_CHANGE attribute to true for all users in the directory
Set<String>	filterNestedUserMembersOfGroups(long directoryId, Set<String> userNames, Set<String> groupNames) Returns names of users who are (nested) members of any of the specified groups.
List<Directory>	findAllDirectories() Deprecated. Use searchDirectories(EntityQuery) instead. Since v3.2.0
List<Application>	findAuthorisedApplications(long directoryId, List<String> groupNames) Finds all applications that a user from a given directory belonging to the specified groups can authenticate to.
Directory	findDirectoryById(long directoryID) Returns a Directory based on the passed in directoryId.
Directory	findDirectoryByName(String name) Finds a directory given the supplied name.
Group	findGroupByName(long directoryId, String groupName) Returns the group matching the supplied groupName in the directory specified by the passed in directoryId..
GroupWithAttributes	findGroupWithAttributesByName(long directoryId, String groupName) Returns the group with all attributes matching the supplied groupName in the directory specified by the passed in directoryId..
User	findRemoteUserByName(Long id, String username) Returns the user matching the supplied username in the authoritative remote directory specified by the passed in directoryId
User	findUserByExternalId(long directoryId, String externalId) Returns the user matching the supplied external ID in the directory specified by the passed in directoryId.
User	findUserByName(long directoryId, String username) Returns the user matching the supplied username in the directory specified by the passed in directoryId..
UserWithAttributes	findUserWithAttributesByExternalId(long directoryId, String externalId) Returns the user (with attributes) matching the supplied external ID in the directory specified by the passed in directoryId.
UserWithAttributes	findUserWithAttributesByName(long directoryId, String username) Returns the user with all attributes matching the supplied username in the directory specified by the passed in directoryId..
DirectorySynchronisationInformation	getDirectorySynchronisationInformation(long directoryId) Retrieves the sync info for the directory - last sync start time & duration, current sync start time (if directory is currently synchronising)
SynchronisationMode	getSynchronisationMode(long directoryId) Returns the preferred synchronisation mode defined for the directory if synchronisable, else null
AvatarReference	getUserAvatarByName(long directoryId, String username, int sizeHint) Return an avatar, if available, for the named user in the specified directory.
boolean	isGroupDirectGroupMember(long directoryId, String childGroup, String parentGroup) Returns true if the childGroup is a direct member of the parentGroup in the directory specified by the passed in directoryId.
boolean	isGroupNestedGroupMember(long directoryId, String childGroup, String parentGroup) Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup in the directory specified by the passed in directoryId.
boolean	isSynchronisable(long directoryId) Returns true if the underlying directory implementation supports manual synchronisation of the directory's local cache.
boolean	isSynchronising(long directoryId) Returns true if the given Directory is currently synchronising.
boolean	isUserDirectGroupMember(long directoryId, String username, String groupName) Returns true if the user is a direct member of the group in the directory specified by the passed in directoryId.
boolean	isUserNestedGroupMember(long directoryId, String username, Set<String> groupNames) Returns true if the user is a direct or indirect (nested) member of any of the specified groups in the directory specified by the passed in directoryId.
boolean	isUserNestedGroupMember(long directoryId, String username, String groupName) Returns true if the user is a direct or indirect (nested) member of the group in the directory specified by the passed in directoryId.
void	removeDirectory(Directory directory) Removes a given directory and all its associated entities and mappings.
void	removeGroup(long directoryId, String groupName) Removes a group matching the supplied groupName in the directory specified by the passed in directoryId.
void	removeGroupAttributes(long directoryId, String groupName, String attributeName) Removes a group's attribute values in the directory specified by the passed in directoryId.
void	removeGroupFromGroup(long directoryId, String childGroup, String parentGroup) Removes an existing child group from being a direct member of an existing parent group in the directory specified by the passed in directoryId.
void	removeUser(long directoryId, String username) Removes a user matching the supplied username in the directory specified by the passed in directoryId.
void	removeUserAttributes(long directoryId, String username, String attributeName) Removes a user's attribute values in the directory specified by the passed in directoryId.
void	removeUserFromGroup(long directoryId, String username, String groupName) Removes an existing user from being a direct member of an existing group in the directory specified by the passed in directoryId.
Group	renameGroup(long directoryId, String oldGroupname, String newGroupname) Renames a group in the directory specified by the passed in directoryId.
User	renameUser(long directoryId, String oldUsername, String newUsername) Renames a user in the directory specified by the passed in directoryId.
<T> List<T>	searchDirectGroupRelationships(long directoryId, MembershipQuery<T> query) Searches for direct group relationships in the directory specified by the passed in directoryId.
<T> com.google.common.collect.ListMultimap<String,T>	searchDirectGroupRelationshipsGroupedByName(long directoryId, MembershipQuery<T> query) Searches for direct group relationships in the directory specified by the passed in directoryId.
List<Directory>	searchDirectories(EntityQuery<Directory> query) Returns a List of Directories matching the search query.
<T> List<T>	searchGroups(long directoryId, EntityQuery<T> query) Returns a list of groups matching the given query in the directory specified by the passed in directoryId.
<T> List<T>	searchNestedGroupRelationships(long directoryId, MembershipQuery<T> query) Searches for direct and indirect (nested) group relationships in the directory specified by the passed in directoryId.
<T> List<T>	searchUsers(long directoryId, EntityQuery<T> query) Returns a list of users matching the given query in the directory specified by the passed in directoryId.
void	storeGroupAttributes(long directoryId, String groupName, Map<String,Set<String>> attributes) Adds or updates a group's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.
void	storeUserAttributes(long directoryId, String username, Map<String,Set<String>> attributes) Adds or updates a user's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.
boolean	supportsExpireAllPasswords(long directoryId) Returns true if the underlying directory implementation supports expiring passwords
boolean	supportsNestedGroups(long directoryId) Returns true if the underlying directory implementation supports nested groups.
void	synchroniseCache(long directoryId, SynchronisationMode mode) Requests that this directory should update its cache by synchronising with the remote User data.
void	synchroniseCache(long directoryId, SynchronisationMode mode, boolean runInBackground) Requests that this directory should update its cache by synchronising with the remote User data.
Directory	updateDirectory(Directory directory) Updates the passed in directory.
Group	updateGroup(long directoryId, GroupTemplate group) Updates a group with the supplied template and returns the updated group retrieved from the directory specified by the passed in directoryId.
User	updateUser(long directoryId, UserTemplate user) Updates a user with the supplied template and returns the updated user retrieved from the directory specified by the passed in directoryId.
void	updateUserCredential(long directoryId, String username, PasswordCredential credential) This will update the user's credential in the given directory specified by the passed in directoryId.
User	updateUserFromRemoteDirectory(User remoteUser) Updates the user details for the specified user based on the details in the remote directory.
User	userAuthenticated(long directoryId, String username)

Method Detail

addDirectory

Directory addDirectory(Directory directory)
                throws DirectoryInstantiationException

Adds the given directory.

Parameters:

directory - the Directory to add

Returns:

the added Directory

Throws:

DirectoryInstantiationException - if there was an error instantiating the directory

findDirectoryById

Directory findDirectoryById(long directoryID)
                     throws DirectoryNotFoundException

Returns a Directory based on the passed in directoryId.

Parameters:

directoryID - the id of the directory to find

Returns:

the directory

Throws:

DirectoryNotFoundException - is thrown if the Directory cannot be found.

findAllDirectories

@Deprecated
List<Directory> findAllDirectories()

Deprecated. Use searchDirectories(EntityQuery) instead. Since v3.2.0

Returns a List of all directories in the system.

Returns:

List of all Directories.

searchDirectories

List<Directory> searchDirectories(EntityQuery<Directory> query)

Returns a List of Directories matching the search query.

Parameters:

query - the context to search on

Returns:

a List of directories, or an Empty List of none are found

findDirectoryByName

Directory findDirectoryByName(String name)
                       throws DirectoryNotFoundException

Finds a directory given the supplied name.

Parameters:

name - the name of the directory

Returns:

the directory with the given name

Throws:

DirectoryNotFoundException - if no Directory is found

updateDirectory

Directory updateDirectory(Directory directory)
                   throws DirectoryNotFoundException

Updates the passed in directory.

Parameters:

directory - the directory with updated attributes

Returns:

the updated directory

Throws:

DirectoryNotFoundException - if no Directory is found

removeDirectory

void removeDirectory(Directory directory)
              throws DirectoryNotFoundException,
                     DirectoryCurrentlySynchronisingException

Removes a given directory and all its associated entities and mappings.

Parameters:

directory - the directory to remove

Throws:

DirectoryNotFoundException - if the directory cannot be found

DirectoryCurrentlySynchronisingException - if the directory is currently synchronising

authenticateUser

User authenticateUser(long directoryId,
                      String username,
                      PasswordCredential passwordCredential)
               throws OperationFailedException,
                      InactiveAccountException,
                      InvalidAuthenticationException,
                      ExpiredCredentialException,
                      DirectoryNotFoundException,
                      UserNotFoundException

Parameters:

directoryId - the id of the directory to authenticate against

username - the username to use for authentication

passwordCredential - the credential to use for authentication

Returns:

will return the user if authentication is successful

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

InactiveAccountException - if the user account is inactive

InvalidAuthenticationException - if authentication with the provided credentials failed

ExpiredCredentialException - if the credentials of the user have expired.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

findUserByName

User findUserByName(long directoryId,
                    String username)
             throws DirectoryNotFoundException,
                    UserNotFoundException,
                    OperationFailedException

Returns the user matching the supplied username in the directory specified by the passed in directoryId..

Parameters:

directoryId - ID of the directory to search.

username - username of the user to retrieve.

Returns:

user matching the supplied username.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

See Also:

findUserWithAttributesByName(long, String)

findRemoteUserByName

@Nonnull
User findRemoteUserByName(Long id,
                                   String username)
                            throws OperationFailedException,
                                   DirectoryNotFoundException,
                                   UserNotFoundException

Returns the user matching the supplied username in the authoritative remote directory specified by the passed in directoryId

Parameters:

id - ID of the directory to search its remote authoriative directory

username - username of the user to retrieve.

Returns:

user matching the supplied username.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

See Also:

findUserWithAttributesByName(long, String)

findUserWithAttributesByName

UserWithAttributes findUserWithAttributesByName(long directoryId,
                                                String username)
                                         throws DirectoryNotFoundException,
                                                UserNotFoundException,
                                                OperationFailedException

Returns the user with all attributes matching the supplied username in the directory specified by the passed in directoryId..

Parameters:

directoryId - ID of the directory to search.

username - username of the user to retrieve.

Returns:

user (with all attributes) matching the supplied username.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

See Also:

findUserByName(long, String)

findUserByExternalId

User findUserByExternalId(long directoryId,
                          String externalId)
                   throws DirectoryNotFoundException,
                          UserNotFoundException,
                          OperationFailedException

Returns the user matching the supplied external ID in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to search.

externalId - external Id of the user to retrieve.

Returns:

user matching the supplied external ID.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied external ID exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

findUserWithAttributesByExternalId

UserWithAttributes findUserWithAttributesByExternalId(long directoryId,
                                                      String externalId)
                                               throws DirectoryNotFoundException,
                                                      UserNotFoundException,
                                                      OperationFailedException

Returns the user (with attributes) matching the supplied external ID in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to search.

externalId - external Id of the user to retrieve.

Returns:

user (with attributes) matching the supplied external ID.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied external ID exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

searchUsers

<T> List<T> searchUsers(long directoryId,
                        EntityQuery<T> query)
                 throws DirectoryNotFoundException,
                        OperationFailedException

Returns a list of users matching the given query in the directory specified by the passed in directoryId.

The users will be returned in a stable order including across pagination boundaries (excluding modification).

Parameters:

directoryId - ID of the directory to search.

query - query to exectute.

Returns:

List of User entities or String usernames matching the query criteria.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

addUser

UserWithAttributes addUser(long directoryId,
                           UserTemplateWithAttributes user,
                           PasswordCredential credential)
                    throws InvalidCredentialException,
                           InvalidUserException,
                           DirectoryPermissionException,
                           DirectoryNotFoundException,
                           OperationFailedException,
                           UserAlreadyExistsException

Adds a UserWithAttributes to the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add the user to.

user - a UserTemplateWithAttributes of the user to be added.

credential - the password credential of the user (unencrypted).

Returns:

the added user returned from the directory.

Throws:

InvalidCredentialException - if the user's credential does not meet the validation requirements for the given directory.

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

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.CREATE_USER.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserAlreadyExistsException - if the user already exists in the given directory

addUser

@Deprecated
User addUser(long directoryId,
                         UserTemplate user,
                         PasswordCredential credential)
                  throws InvalidCredentialException,
                         InvalidUserException,
                         DirectoryPermissionException,
                         DirectoryNotFoundException,
                         OperationFailedException,
                         UserAlreadyExistsException

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

Adds a User to the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add the user to.

user - a UserTemplate of the user to be added.

credential - the password credential of the user (unencrypted).

Returns:

the added user returned from the directory.

Throws:

InvalidCredentialException - if the user's credential does not meet the validation requirements for the given directory.

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

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.CREATE_USER.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserAlreadyExistsException - if the user already exists in the given directory

updateUser

User updateUser(long directoryId,
                UserTemplate user)
         throws DirectoryNotFoundException,
                UserNotFoundException,
                DirectoryPermissionException,
                InvalidUserException,
                OperationFailedException

Updates a user with the supplied template and returns the updated user retrieved from the directory specified by the passed in directoryId.

This method cannot be used to rename the user, update the user's credentials or update the user's custom attributes.

Parameters:

directoryId - ID of the directory to find and update the user.

user - template of the user to update.

Returns:

the updated user returned from the directory.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_USER.

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

See Also:

renameUser(long, String, String), updateUserCredential(long, String, com.atlassian.crowd.embedded.api.PasswordCredential), storeUserAttributes(long, String, java.util.Map), removeUserAttributes(long, String, String)

renameUser

User renameUser(long directoryId,
                String oldUsername,
                String newUsername)
         throws DirectoryNotFoundException,
                UserNotFoundException,
                OperationFailedException,
                DirectoryPermissionException,
                InvalidUserException,
                UserAlreadyExistsException

Renames a user in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to find and update the user.

oldUsername - current username of the user.

newUsername - desired username of the user.

Returns:

updated user returned from the directory.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_USER.

InvalidUserException - if the new username does not meet the username requirements of the directory

UserAlreadyExistsException - if the newUsername user already exists in the given directory

UnsupportedOperationException - if the directory does not support user renaming

storeUserAttributes

void storeUserAttributes(long directoryId,
                         String username,
                         Map<String,Set<String>> attributes)
                  throws DirectoryPermissionException,
                         DirectoryNotFoundException,
                         UserNotFoundException,
                         OperationFailedException

Adds or updates a user's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.

The attributes map represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing attribute on the user.

This method does not update primary field attributes like firstName, lastName, etc.

Parameters:

directoryId - ID of the directory to find and update the user.

username - username of the user to update.

attributes - map of one-to-many attribute-values. All attribute keys are treated as new or updated attributes.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_USER_ATTRIBUTE.

See Also:

updateUser(long, com.atlassian.crowd.model.user.UserTemplate)

removeUserAttributes

void removeUserAttributes(long directoryId,
                          String username,
                          String attributeName)
                   throws DirectoryPermissionException,
                          DirectoryNotFoundException,
                          UserNotFoundException,
                          OperationFailedException

Removes a user's attribute values in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to find and update the user.

username - username of the user to update.

attributeName - all attribute values for this key will be removed from the user.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_USER_ATTRIBUTE.

See Also:

updateUser(long, com.atlassian.crowd.model.user.UserTemplate)

updateUserCredential

void updateUserCredential(long directoryId,
                          String username,
                          PasswordCredential credential)
                   throws DirectoryPermissionException,
                          InvalidCredentialException,
                          DirectoryNotFoundException,
                          UserNotFoundException,
                          OperationFailedException

This will update the user's credential in the given directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to find and update the user.

username - username of the user to update.

credential - the new password credential for the user (unencrypted).

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_USER.

InvalidCredentialException - if the new credential does not meet the requirements for the given directory.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

removeUser

void removeUser(long directoryId,
                String username)
         throws DirectoryNotFoundException,
                UserNotFoundException,
                DirectoryPermissionException,
                OperationFailedException

Removes a user matching the supplied username in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to remove the user from.

username - username of the user to remove.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if no user with the supplied username exists in the directory

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.DELETE_USER.

OperationFailedException - underlying directory implementation failed to execute the operation.

findGroupByName

Group findGroupByName(long directoryId,
                      String groupName)
               throws GroupNotFoundException,
                      DirectoryNotFoundException,
                      OperationFailedException

Returns the group matching the supplied groupName in the directory specified by the passed in directoryId..

Parameters:

directoryId - ID of the directory to search.

groupName - groupName of the group to retrieve.

Returns:

group matching the supplied groupName.

Throws:

GroupNotFoundException - if no group with the supplied groupName exists in the directory

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

OperationFailedException - underlying directory implementation failed to execute the operation.

See Also:

findGroupWithAttributesByName(long, String)

findGroupWithAttributesByName

GroupWithAttributes findGroupWithAttributesByName(long directoryId,
                                                  String groupName)
                                           throws GroupNotFoundException,
                                                  DirectoryNotFoundException,
                                                  OperationFailedException

Returns the group with all attributes matching the supplied groupName in the directory specified by the passed in directoryId..

Parameters:

directoryId - ID of the directory to search.

groupName - groupName of the group to retrieve.

Returns:

group (with all attributes) matching the supplied groupName.

Throws:

GroupNotFoundException - if no group with the supplied groupName exists in the directory

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

OperationFailedException - underlying directory implementation failed to execute the operation.

See Also:

findGroupByName(long, String)

searchGroups

<T> List<T> searchGroups(long directoryId,
                         EntityQuery<T> query)
                  throws DirectoryNotFoundException,
                         OperationFailedException

Returns a list of groups matching the given query in the directory specified by the passed in directoryId.

The groups will be returned in a stable order including across pagination boundaries (excluding modification).

Parameters:

directoryId - ID of the directory to search.

query - query to exectute.

Returns:

List of Group entities or String groupNames matching the query criteria.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

addGroup

Group addGroup(long directoryId,
               GroupTemplate group)
        throws InvalidGroupException,
               DirectoryPermissionException,
               DirectoryNotFoundException,
               OperationFailedException

Adds a Group to the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add the group to.

group - a template of the group to be added.

Returns:

the added group returned from the directory.

Throws:

InvalidGroupException - if the group already exists in the given directory.

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.CREATE_GROUP.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found after the add operation.

updateGroup

Group updateGroup(long directoryId,
                  GroupTemplate group)
           throws GroupNotFoundException,
                  DirectoryNotFoundException,
                  DirectoryPermissionException,
                  InvalidGroupException,
                  OperationFailedException,
                  ReadOnlyGroupException

Updates a group with the supplied template and returns the updated group retrieved from the directory specified by the passed in directoryId.

This method cannot be used to rename the group, update the group's credentials or update the group's custom attributes.

Parameters:

directoryId - ID of the directory to find and update the group.

group - template of the group to update.

Returns:

the updated group returned from the directory.

Throws:

GroupNotFoundException - if no group with the supplied groupName exists in the directory

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

InvalidGroupException - if the group template does not have the required properties populated.

ReadOnlyGroupException - if the group is read-only

See Also:

renameGroup(long, String, String), storeGroupAttributes(long, String, java.util.Map), removeGroupAttributes(long, String, String)

renameGroup

Group renameGroup(long directoryId,
                  String oldGroupname,
                  String newGroupname)
           throws GroupNotFoundException,
                  DirectoryNotFoundException,
                  DirectoryPermissionException,
                  InvalidGroupException,
                  OperationFailedException

Renames a group in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to find and update the group.

oldGroupname - current groupName of the group.

newGroupname - desired groupName of the group.

Returns:

updated group returned from the directory.

Throws:

GroupNotFoundException - if the group with the oldGroupname does not exist in the directory or if the directory with the given directoryId cannot be found.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

InvalidGroupException - if the new groupName does not meet the groupName requirements of the directory or if a group already exists with the new groupName.

storeGroupAttributes

void storeGroupAttributes(long directoryId,
                          String groupName,
                          Map<String,Set<String>> attributes)
                   throws DirectoryPermissionException,
                          GroupNotFoundException,
                          DirectoryNotFoundException,
                          OperationFailedException

Adds or updates a group's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.

The attributes map represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing attribute on the group.

This method does not update primary field attributes like firstName, lastName, etc.

Parameters:

directoryId - ID of the directory to find and update the group.

groupName - groupName of the group to update.

attributes - map of one-to-many attribute-values. All attribute keys are treated as new or updated attributes.

Throws:

GroupNotFoundException - if no group with the supplied groupName exists in the directory

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP_ATTRIBUTE.

See Also:

updateGroup(long, com.atlassian.crowd.model.group.GroupTemplate)

removeGroupAttributes

void removeGroupAttributes(long directoryId,
                           String groupName,
                           String attributeName)
                    throws DirectoryPermissionException,
                           GroupNotFoundException,
                           DirectoryNotFoundException,
                           OperationFailedException

Removes a group's attribute values in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to find and update the group.

groupName - groupName of the group to update.

attributeName - all attribute values for this key will be removed from the group.

Throws:

GroupNotFoundException - if no group with the supplied groupName exists in the directory

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP_ATTRIBUTE.

See Also:

updateGroup(long, com.atlassian.crowd.model.group.GroupTemplate)

removeGroup

void removeGroup(long directoryId,
                 String groupName)
          throws GroupNotFoundException,
                 DirectoryNotFoundException,
                 DirectoryPermissionException,
                 OperationFailedException,
                 ReadOnlyGroupException

Removes a group matching the supplied groupName in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to remove the group from.

groupName - groupName of the group to remove.

Throws:

GroupNotFoundException - if no group with the supplied groupName exists in the directory

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.DELETE_GROUP.

ReadOnlyGroupException - if the group is read-only

OperationFailedException - underlying directory implementation failed to execute the operation.

isUserDirectGroupMember

boolean isUserDirectGroupMember(long directoryId,
                                String username,
                                String groupName)
                         throws DirectoryNotFoundException,
                                OperationFailedException

Returns true if the user is a direct member of the group in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to inspect membership information.

username - name of the user to inspect.

groupName - name of the group to inspect.

Returns:

true if and only if the user is a direct member of the group. If the group or user does not exist in the directory, false is returned.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

isGroupDirectGroupMember

boolean isGroupDirectGroupMember(long directoryId,
                                 String childGroup,
                                 String parentGroup)
                          throws DirectoryNotFoundException,
                                 OperationFailedException

Returns true if the childGroup is a direct member of the parentGroup in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to inspect membership information.

childGroup - name of the group to inspect.

parentGroup - name of the group to inspect.

Returns:

true if and only if the childGroup is a direct member of the parentGroup. If either group does not exist in the directory, false is returned.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

addUserToGroup

void addUserToGroup(long directoryId,
                    String username,
                    String groupName)
             throws DirectoryPermissionException,
                    DirectoryNotFoundException,
                    UserNotFoundException,
                    GroupNotFoundException,
                    OperationFailedException,
                    ReadOnlyGroupException,
                    MembershipAlreadyExistsException

Adds an existing user as a direct member of an existing group in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add membership information.

username - username of the user.

groupName - name of the group.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if the user does not exist in the directory

GroupNotFoundException - if the group does not exist in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

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

ReadOnlyGroupException - if the group is read-only

addGroupToGroup

void addGroupToGroup(long directoryId,
                     String childGroup,
                     String parentGroup)
              throws DirectoryPermissionException,
                     DirectoryNotFoundException,
                     GroupNotFoundException,
                     InvalidMembershipException,
                     NestedGroupsNotSupportedException,
                     OperationFailedException,
                     ReadOnlyGroupException,
                     MembershipAlreadyExistsException

Adds an existing child group as direct member of an existing parent group in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add membership information.

childGroup - name of child group.

parentGroup - name of the parent group.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

GroupNotFoundException - if the group does not exist in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

InvalidMembershipException - GroupType of childGroup does not match parentGroup.

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

NestedGroupsNotSupportedException - If the directory does not support nested groups.

ReadOnlyGroupException - if the group is read-only

removeUserFromGroup

void removeUserFromGroup(long directoryId,
                         String username,
                         String groupName)
                  throws DirectoryPermissionException,
                         DirectoryNotFoundException,
                         UserNotFoundException,
                         GroupNotFoundException,
                         MembershipNotFoundException,
                         OperationFailedException,
                         ReadOnlyGroupException

Removes an existing user from being a direct member of an existing group in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add membership information.

username - username of the user.

groupName - name of the group.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

UserNotFoundException - if the user does not exist in the directory

GroupNotFoundException - if the group does not exist in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

MembershipNotFoundException - user is not a direct member of group.

ReadOnlyGroupException - if the group is read-only

removeGroupFromGroup

void removeGroupFromGroup(long directoryId,
                          String childGroup,
                          String parentGroup)
                   throws DirectoryPermissionException,
                          GroupNotFoundException,
                          DirectoryNotFoundException,
                          InvalidMembershipException,
                          MembershipNotFoundException,
                          OperationFailedException,
                          ReadOnlyGroupException

Removes an existing child group from being a direct member of an existing parent group in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to add membership information.

childGroup - name of child group.

parentGroup - name of the parent group.

Throws:

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

GroupNotFoundException - if the group does not exist in the directory

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

MembershipNotFoundException - group is not a direct member of group.

InvalidMembershipException - GroupType of childGroup does not match parentGroup.

ReadOnlyGroupException - if the group is read-only

searchDirectGroupRelationships

<T> List<T> searchDirectGroupRelationships(long directoryId,
                                           MembershipQuery<T> query)
                                    throws DirectoryNotFoundException,
                                           OperationFailedException

Searches for direct group relationships in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to inspect membership information.

query - membership query.

Returns:

List of User entities, Group entites, String usernames or String group names matching the query criteria. If there are no results, returns an empty List.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

searchDirectGroupRelationshipsGroupedByName

<T> com.google.common.collect.ListMultimap<String,T> searchDirectGroupRelationshipsGroupedByName(long directoryId,
                                                                                                 MembershipQuery<T> query)
                                                                                          throws OperationFailedException,
                                                                                                 DirectoryNotFoundException

Searches for direct group relationships in the directory specified by the passed in directoryId.

Parameters:

directoryId - ID of the directory to inspect membership information.

query - membership query.

Returns:

ListMultimap, where key is element of MembershipQuery.getEntityNamesToMatch() and the value is list of User entities, Group entites, String usernames or String group names matching the query criteria for the given key.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

isUserNestedGroupMember

boolean isUserNestedGroupMember(long directoryId,
                                String username,
                                String groupName)
                         throws DirectoryNotFoundException,
                                OperationFailedException

Returns true if the user is a direct or indirect (nested) member of the group in the directory specified by the passed in directoryId.

If the directory does not support nested groups, this call will be equivalent to isUserDirectGroupMember(long, String, String).

WARNING: this method could be very slow if the underlying RemoteDirectory does not employ caching.

Parameters:

directoryId - ID of the directory to inspect membership information.

username - name of the user to inspect.

groupName - name of the group to inspect.

Returns:

true if and only if the user is a direct or indirect (nested) member of the group. If the group or user does not exist in the directory, false is returned.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

isUserNestedGroupMember

boolean isUserNestedGroupMember(long directoryId,
                                String username,
                                Set<String> groupNames)
                         throws DirectoryNotFoundException,
                                OperationFailedException

Returns true if the user is a direct or indirect (nested) member of any of the specified groups in the directory specified by the passed in directoryId.

If the directory does not support nested groups, this call will be equivalent to isUserDirectGroupMember(long, String, String).

WARNING: this method could be very slow if the underlying RemoteDirectory does not employ caching.

Parameters:

directoryId - ID of the directory to inspect membership information.

username - name of the user to inspect.

groupNames - names of the group to inspect.

Returns:

true if and only if the user is a direct or indirect (nested) member of any of the specified groups. If the groups or user do not exist in the directory, false is returned.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

filterNestedUserMembersOfGroups

Set<String> filterNestedUserMembersOfGroups(long directoryId,
                                            Set<String> userNames,
                                            Set<String> groupNames)
                                     throws OperationFailedException,
                                            DirectoryNotFoundException

Returns names of users who are (nested) members of any of the specified groups. WARNING: this method could be very slow if the underlying RemoteDirectory does not employ caching.

Parameters:

directoryId - ID of the directory to inspect membership information.

userNames - names of users to inspect.

groupName - names of groups to inspect.

Returns:

names of users who are (nested) members of any of the specified groups.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

isGroupNestedGroupMember

boolean isGroupNestedGroupMember(long directoryId,
                                 String childGroup,
                                 String parentGroup)
                          throws DirectoryNotFoundException,
                                 OperationFailedException

Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup in the directory specified by the passed in directoryId.

If the directory does not support nested groups, this call will be equivalent to isGroupDirectGroupMember(long, String, String).

WARNING: this method could be very slow if the underlying RemoteDirectory does not employ caching.

Parameters:

directoryId - ID of the directory to inspect membership information.

childGroup - name of the user to inspect.

parentGroup - name of the group to inspect.

Returns:

true if and only if the childGroup is a direct or indirect (nested) member of the parentGruop. If either group does not exist in the directory, false is returned.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

countDirectMembersOfGroup

BoundedCount countDirectMembersOfGroup(long directoryId,
                                       String groupName,
                                       int querySizeHint)
                                throws DirectoryNotFoundException,
                                       OperationFailedException

Count the direct members of a group in the provided directory with an upper bound. The upper bound is there so that, in directories that do not support efficient counting of memberships, the count request is not unbounded.

Parameters:

groupName - the name of the group to search for

querySizeHint - hinting at the maximum number of memberships that should be counted. The directory that implements this may choose to count less or more. This is a user provided suggestion for potential efficiency.

Returns:

A bounded count of the number of memberships in the given group for the provided directory. If the group does not exist then exactly 0 will be returned.

Throws:

DirectoryNotFoundException - if a directory for the provided id could not be found.

OperationFailedException - if we failed to count the number of memberships for that group in the given directory.

searchNestedGroupRelationships

<T> List<T> searchNestedGroupRelationships(long directoryId,
                                           MembershipQuery<T> query)
                                    throws DirectoryNotFoundException,
                                           OperationFailedException

Searches for direct and indirect (nested) group relationships in the directory specified by the passed in directoryId.

If the directory does not support nested groups, this call will be equivalent to searchDirectGroupRelationships(long, com.atlassian.crowd.search.query.membership.MembershipQuery).

WARNING: this method could be very slow if the underlying RemoteDirectory does not employ caching.

Parameters:

directoryId - ID of the directory to inspect membership information.

query - membership query.

Returns:

List of User entities, Group entites, String usernames or String group names matching the query criteria.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

addAllUsers

BulkAddResult<User> addAllUsers(long directoryId,
                                Collection<UserTemplateWithCredentialAndAttributes> users,
                                boolean overwrite)
                         throws DirectoryPermissionException,
                                DirectoryNotFoundException,
                                OperationFailedException

Will add a collection of users to the directory specified by the passed in directoryId param.

If adding a particular user fails then this user will be skipped and the error will be reported in the logs and the BulkAddResult object.

If the underlying directory supports bulk adding of entities (ie. implements InternalRemoteDirectory), it may be faster than manual iteration of each entity.

Parameters:

directoryId - the directory to add the User too.

users - the templates of the users to add.

overwrite - true if you want to remove any existing user matching a username in the users to add prior to adding the user. false if you want to skip over users that already exist (same username exists).

Returns:

results for bulk add process.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.CREATE_USER. or if the overwrite is true and the directory is not allowed to perform operations of type OperationType.DELETE_USER

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

addAllGroups

BulkAddResult<Group> addAllGroups(long directoryId,
                                  Collection<GroupTemplate> groups,
                                  boolean overwrite)
                           throws DirectoryPermissionException,
                                  DirectoryNotFoundException,
                                  OperationFailedException,
                                  InvalidGroupException

Will add a collection of Group to the directory specified by the passed in directoryId param.

If adding a group fails then this user will be skipped and the error will be reported in the logs and the BulkAddResult object.

If the underlying directory supports bulk adding of entities (ie. implements InternalRemoteDirectory), it may be faster than manual iteration of each entity.

Parameters:

directoryId - the directory to add the Group too.

groups - the Groups to add.

overwrite - true if you want to remove any existing group matching a username in the groups to add prior to adding the group. false if you want to skip over groups that already exist (same group name exists).

Returns:

results for bulk add process.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.CREATE_GROUP. or if the overwrite is true and the directory is not allowed to perform operations of type OperationType.DELETE_GROUP

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

InvalidGroupException - if any of the group is invalid

addAllUsersToGroup

BulkAddResult<String> addAllUsersToGroup(long directoryID,
                                         Collection<String> userNames,
                                         String groupName)
                                  throws DirectoryPermissionException,
                                         DirectoryNotFoundException,
                                         GroupNotFoundException,
                                         OperationFailedException

A bulk version of addUserToGroup(long, String, String).

If creating a particular membership fails, it will be skipped and the error will be reported in the logs and the BulkAddResult object.

If the underlying directory supports bulk adding of entities (ie. implements InternalRemoteDirectory), it may be faster than manual iteration of each entity.

Parameters:

directoryID - the directory to add the membership to.

userNames - usernames of users to add membership to.

groupName - name of group to add users to.

Returns:

results for bulk add process consisting of the names of the users which could not be added to the group.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryPermissionException - if the directory is not allowed to perform operations of type OperationType.UPDATE_GROUP.

DirectoryNotFoundException - if the directory with the given directoryId cannot be found.

GroupNotFoundException - if the groupName did not resolve to a group

supportsNestedGroups

boolean supportsNestedGroups(long directoryId)
                      throws DirectoryInstantiationException,
                             DirectoryNotFoundException

Returns true if the underlying directory implementation supports nested groups.

Parameters:

directoryId - ID of directory.

Returns:

true if the directory supports nested groups

Throws:

DirectoryInstantiationException - if there was an error instantiating the directory

DirectoryNotFoundException - if the directory could not be found.

isSynchronisable

boolean isSynchronisable(long directoryId)
                  throws DirectoryInstantiationException,
                         DirectoryNotFoundException

Returns true if the underlying directory implementation supports manual synchronisation of the directory's local cache.

That is if we keep a local cache that is periodically updated from the remote server.

If a directory is synchronisable (i.e. isSynchronisable returns true, it is safe to cast the directory with the given ID into a SynchronisableDirectory.

Parameters:

directoryId - ID of directory.

Returns:

true if the directory supports synchronisation

Throws:

DirectoryInstantiationException - if there was an error instantiating the directory

DirectoryNotFoundException - if the directory could not be found.

getSynchronisationMode

@Nullable
SynchronisationMode getSynchronisationMode(long directoryId)
                                              throws DirectoryInstantiationException,
                                                     DirectoryNotFoundException

Returns the preferred synchronisation mode defined for the directory if synchronisable, else null

Parameters:

directoryId - ID of the directory

Returns:

the preferred SynchronisationMode for a synchronisable directory, null otherwise.

Throws:

DirectoryInstantiationException

DirectoryNotFoundException

synchroniseCache

void synchroniseCache(long directoryId,
                      SynchronisationMode mode)
               throws OperationFailedException,
                      DirectoryNotFoundException

Requests that this directory should update its cache by synchronising with the remote User data. The synchronisation will occur asynchronously, i.e. this method returns immediately and the synchronization continues in the background.

If a synchronisation is currently in progress when this method is called, then this method does nothing.

Parameters:

directoryId - ID of directory.

mode - the mode of the synchronisation

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory could not be found.

synchroniseCache

void synchroniseCache(long directoryId,
                      SynchronisationMode mode,
                      boolean runInBackground)
               throws OperationFailedException,
                      DirectoryNotFoundException

Requests that this directory should update its cache by synchronising with the remote User data.

If a synchronisation is currently in progress when this method is called, then this method does nothing if runInBackGround is true, otherwise it will throw OperationFailedException.

Parameters:

directoryId - ID of directory.

mode - the mode of the synchronisation

runInBackground - If True the synchronise will happen asynchronously.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

DirectoryNotFoundException - if the directory could not be found.

isSynchronising

boolean isSynchronising(long directoryId)
                 throws DirectoryInstantiationException,
                        DirectoryNotFoundException

Returns true if the given Directory is currently synchronising. This method should only be used to give an indication regarding the synchronisation state in the UI and should not be used to control whether or not to start another synchronisation.

Parameters:

directoryId - ID of directory.

Returns:

true if the given Directory is currently synchronising, otherwise false.

Throws:

DirectoryInstantiationException - if there was an error instantiating the directory

DirectoryNotFoundException - if the directory could not be found

getDirectorySynchronisationInformation

DirectorySynchronisationInformation getDirectorySynchronisationInformation(long directoryId)
                                                                    throws DirectoryInstantiationException,
                                                                           DirectoryNotFoundException

Retrieves the sync info for the directory - last sync start time & duration, current sync start time (if directory is currently synchronising)

Parameters:

directoryId - ID of directory

Returns:

a DirectorySynchronisationInformation object that contains the synchronisation information for the directory. null if the RemoteDirectory is not an instance of SynchronisableDirectory

Throws:

DirectoryInstantiationException - if there was an error instantiating the directory

DirectoryNotFoundException - if the directory could not be found.

supportsExpireAllPasswords

boolean supportsExpireAllPasswords(long directoryId)
                            throws DirectoryInstantiationException,
                                   DirectoryNotFoundException

Returns true if the underlying directory implementation supports expiring passwords

Parameters:

directoryId - ID of directory.

Returns:

true if the directory supports expiring passwords

Throws:

DirectoryInstantiationException - if there was an error instantiating the directory

DirectoryNotFoundException - if the directory could not be found.

expireAllPasswords

void expireAllPasswords(long directoryId)
                 throws OperationFailedException,
                        DirectoryNotFoundException

Sets the UserConstants.REQUIRES_PASSWORD_CHANGE attribute to true for all users in the directory

Throws:

OperationFailedException

DirectoryNotFoundException

getUserAvatarByName

AvatarReference getUserAvatarByName(long directoryId,
                                    String username,
                                    int sizeHint)
                             throws UserNotFoundException,
                                    OperationFailedException,
                                    DirectoryNotFoundException

Return an avatar, if available, for the named user in the specified directory.

Parameters:

sizeHint - a hint in pixels for the context in which this will be used

Returns:

an avatar, or null if none is available

Throws:

UserNotFoundException

OperationFailedException

DirectoryNotFoundException

updateUserFromRemoteDirectory

@ExperimentalApi
User updateUserFromRemoteDirectory(@Nonnull
                                                    User remoteUser)
                                             throws OperationFailedException,
                                                    DirectoryNotFoundException,
                                                    UserNotFoundException

Updates the user details for the specified user based on the details in the remote directory. Typically done as a part of authenticateUser(long, String, PasswordCredential), but in case the user is authenticated in another way, it might be useful to update the user's data. Currently includes: - creating the user if he doesn't exist locally yet - renaming the user if the name has changed in remote - optionally updating the user group memberships, depending on the directory configuration

Parameters:

remoteUser - the remote user to update for

Returns:

the internal user after the update

Throws:

OperationFailedException

DirectoryNotFoundException

UserNotFoundException

userAuthenticated

@ExperimentalApi
User userAuthenticated(long directoryId,
                                        String username)
                                 throws OperationFailedException,
                                        DirectoryNotFoundException,
                                        UserNotFoundException,
                                        InactiveAccountException

Throws:

OperationFailedException

DirectoryNotFoundException

UserNotFoundException

InactiveAccountException

findAuthorisedApplications

@ExperimentalApi
List<Application> findAuthorisedApplications(long directoryId,
                                                              List<String> groupNames)

Finds all applications that a user from a given directory belonging to the specified groups can authenticate to.

Parameters:

directoryId - directory id of the user.

groupNames - group memberships of the user in the particular directory.

Returns:

list of applications the user can authenticate to.