com.atlassian.crowd.manager.application
Class ApplicationServiceGeneric

java.lang.Object
  com.atlassian.crowd.manager.application.ApplicationServiceGeneric

All Implemented Interfaces:

ApplicationService

public class ApplicationServiceGeneric
extends Object
implements ApplicationService

Constructor Summary

ApplicationServiceGeneric(DirectoryManager directoryManager, PermissionManager permissionManager, DirectoryInstanceLoader directoryInstanceLoader, com.atlassian.event.api.EventPublisher eventPublisher, EventStore eventStore)

Method Summary

void	addAllUsers(Application application, Collection<UserTemplateWithCredentialAndAttributes> userTemplates) Adds the user to THE FIRST permissible active directory.
Group	addGroup(Application application, GroupTemplate group) Adds the group to ALL the active permissible directories.
void	addGroupToGroup(Application application, String childGroupName, String parentGroupName) Makes groups matching the given name (childGroupName) direct members of the group (parentGroupName) across ALL active directories.
User	addUser(Application application, UserTemplate user, PasswordCredential credential) Adds the user to the first permissible active directory.
void	addUserToGroup(Application application, String username, String groupName) Makes the primary user of the given username a direct member of the group on the directory where the primary user resides.
User	authenticateUser(Application application, String username, PasswordCredential passwordCredential) Will attempt to authenticate the given user against the application.
Group	findGroupByName(Application application, String name) Returns the first group with the matching groupname from all the active directories assigned to the application.
GroupWithAttributes	findGroupWithAttributesByName(Application application, String name) Returns the first group with the matching groupname from all the active directories assigned to the application.
User	findUserByName(Application application, String name) Returns the first user with the matching username from all the active directories assigned to the application.
UserWithAttributes	findUserWithAttributesByName(Application application, String name) Returns the first user with the matching username from all the active directories assigned to the application.
String	getCurrentEventToken(Application application) Returns a token that can be used for querying events that have happened after the token was generated.
Events	getNewEvents(Application application, String eventToken) Returns an events object which contains a new eventToken and events that happened after the given eventToken was generated.
boolean	isGroupDirectGroupMember(Application application, String childGroup, String parentGroup) Returns true if the childGroup is a direct member of the parentGroup in any of the application's assigned directories.
boolean	isGroupNestedGroupMember(Application application, String childGroup, String parentGroup) Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup in any of the application's active assigned directories.
boolean	isUserAuthorised(Application application, String username) Returns true if the user is authorised to authenticate with the application.
boolean	isUserDirectGroupMember(Application application, String username, String groupName) Returns true if the user is a direct member of the group in the directory of the first user found with the specified username.
boolean	isUserNestedGroupMember(Application application, String username, String groupName) Returns true if the user is a direct or indirect (nested) member of the group in the directory of the first user found with the specified username.
void	removeGroup(Application application, String groupname) Removes ALL groups from each of the application's assigned directories that are active.
void	removeGroupAttributes(Application application, String groupname, String attributeName) Removes a group's attribute values for all active permissible directories assigned to the application.
void	removeGroupFromGroup(Application application, String childGroup, String parentGroup) Makes child group matching the given name not members of the parent group across ALL active directories.
void	removeUser(Application application, String username) Removes the user from the first active directory they are found in.
void	removeUserAttributes(Application application, String username, String attributeName) Removes a user's attribute values for the first active directory containing this username.
void	removeUserFromGroup(Application application, String username, String groupName) Makes the primary user of the given username no longer a member of the group on the directory where the primary user resides.
void	resetUserCredential(Application application, String username) Resets the credentials of the first matching user in the application's active directories.
<T> List<T>	searchDirectGroupRelationships(Application application, MembershipQuery<T> query) Searches for direct group relationships in any of the application's active assigned directories.
<T> List<T>	searchGroups(Application application, EntityQuery<T> query) Returns a List matching the search criteria defined in the query for ALL of the active directories assigned to the application.
<T> List<T>	searchNestedGroupRelationships(Application application, MembershipQuery<T> query) Searches for direct and indirect (nested) group relationships in any of the application's active assigned directories.
<T> List<T>	searchUsers(Application application, EntityQuery<T> query) Returns a List or List matching the search criteria defined in the query for ALL of the active directories assigned to the application.
List<User>	searchUsersAllowingDuplicateNames(Application application, EntityQuery<User> query) Returns a List matching the search criteria defined in the query for ALL of the active directories assigned to the application.
void	storeGroupAttributes(Application application, String groupname, Map<String,Set<String>> attributes) Adds or updates a group's attributes with the new Map of attribute values for all active permissible directories assigned to the application.
void	storeUserAttributes(Application application, String username, Map<String,Set<String>> attributes) Adds or updates a user's attributes with the new Map of attribute values for the first active directory containing this username.
Group	updateGroup(Application application, GroupTemplate group) Updates the group in ALL the active permissible directories.
User	updateUser(Application application, UserTemplate user) Updates the user in the first active directory the User belongs.
void	updateUserCredential(Application application, String username, PasswordCredential credential) Updates the credentials of the first matching user from all the active directories assigned to the application.

Methods inherited from class java.lang.Object

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

Constructor Detail

ApplicationServiceGeneric

public ApplicationServiceGeneric(DirectoryManager directoryManager,
                                 PermissionManager permissionManager,
                                 DirectoryInstanceLoader directoryInstanceLoader,
                                 com.atlassian.event.api.EventPublisher eventPublisher,
                                 EventStore eventStore)

Method Detail

authenticateUser

public User authenticateUser(Application application,
                             String username,
                             PasswordCredential passwordCredential)
                      throws OperationFailedException,
                             InactiveAccountException,
                             InvalidAuthenticationException,
                             ExpiredCredentialException,
                             UserNotFoundException

Description copied from interface: ApplicationService

Will attempt to authenticate the given user against the application. The logic should start by going through directories defined in the application one by one, trying to authenticate user against each directory. When an authentication against directory is positive, the method returns the user. Otherwise, an exception indicating the reason will be thrown. In case that some of the underlying directories cannot perform the operation at the time of authentication, either by technical failures or the application not having the right permission to query the directory, as indicated by OperationFailedException being thrown, the authentication logic will skip those directories, instead relying on the operative ones, in the order defined in the application's directory mappings. However, if the user, still, cannot be authenticated against any remaining directories, we suspect one of the bad directories must have held the user account, in which case OperationFailedException, which indicates the underlying cause of the first failing directory, will be thrown from this method.

Specified by:

authenticateUser in interface ApplicationService

Parameters:

application - the application to authenticate against

username - the username to authenticate against

passwordCredential - the password to use for authentication

Returns:

A user if the user can successfully authenticate.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

InactiveAccountException - if the users account is marked as inactive

InvalidAuthenticationException - if authentication with the provided credentials failed, or potentially the user does not exist.

ExpiredCredentialException - if the users credentials have expired

UserNotFoundException

isUserAuthorised

public boolean isUserAuthorised(Application application,
                                String username)

Description copied from interface: ApplicationService

Returns true if the user is authorised to authenticate with the application. If the user could not be found, then false is returned.

For a user to have access to an application:

1. the Application must be active.
2. and either:
   • the User is stored in a directory which is associated to the Application and the "allow all to authenticate" flag is true.
   • the User is a member of a Group that is allowed to authenticate with the Application and both the User and Group are from the same RemoteDirectory.

Specified by:

isUserAuthorised in interface ApplicationService

Parameters:

application - application user is authenticating against

username - username

Returns:

true if the user is authorised to authenticate with the application, otherwise false. If the user could not be found, false will be returned.

addAllUsers

public void addAllUsers(Application application,
                        Collection<UserTemplateWithCredentialAndAttributes> userTemplates)
                 throws ApplicationPermissionException,
                        OperationFailedException,
                        BulkAddFailedException

Description copied from interface: ApplicationService

Adds the user to THE FIRST permissible active directory.

If no directories have CREATE_USER permission, an ApplicationPermissionException is thrown.

Specified by:

addAllUsers in interface ApplicationService

Parameters:

application - add to application's assigned directories.

userTemplates - the users to add.

Throws:

ApplicationPermissionException - thrown when no CREATE USER permission for any of the directories.

OperationFailedException - underlying directory implementation failed to execute the operation.

BulkAddFailedException - throw when it failed to create a user in of the directories.

findUserByName

public User findUserByName(Application application,
                           String name)
                    throws UserNotFoundException

Description copied from interface: ApplicationService

Returns the first user with the matching username from all the active directories assigned to the application.

The directories are searched in the order they are assigned to the application.

Specified by:

findUserByName in interface ApplicationService

Parameters:

application - search application's assigned directories.

name - the username of the user to find.

Returns:

first matching user.

Throws:

UserNotFoundException - user not found in any of the directories.

findUserWithAttributesByName

public UserWithAttributes findUserWithAttributesByName(Application application,
                                                       String name)
                                                throws UserNotFoundException

Description copied from interface: ApplicationService

Returns the first user with the matching username from all the active directories assigned to the application.

The directories are searched in the order they are assigned to the application.

Specified by:

findUserWithAttributesByName in interface ApplicationService

Parameters:

application - search application's assigned directories.

name - the username of the user to find.

Returns:

first matching user.

Throws:

UserNotFoundException - user not found in any of the directories.

addUser

public User addUser(Application application,
                    UserTemplate user,
                    PasswordCredential credential)
             throws InvalidUserException,
                    OperationFailedException,
                    InvalidCredentialException,
                    ApplicationPermissionException

Description copied from interface: ApplicationService

Adds the user to the first permissible active directory.

If the user exists in ANY of the application's active assigned directories, then an InvalidUserException will be thrown.

If the add operation fails on the directory because of permission restrictions, an ApplicationPermissionException is thrown If ALL directories permissions fail, an ApplicationPermissionException is thrown.

If the add operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Returns the added user from the directory operation.

Specified by:

addUser in interface ApplicationService

Parameters:

application - add to application's assigned directories.

user - a template of the user to be added. The directoryId of the UserTemplate is ignored, and will be mutated for each directoryMapping.

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

Returns:

the added user returned from ApplicationService.findUserByName(com.atlassian.crowd.model.application.Application , String).

Throws:

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

OperationFailedException - underlying directory implementation failed to execute the operation.

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

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

updateUser

public User updateUser(Application application,
                       UserTemplate user)
                throws InvalidUserException,
                       OperationFailedException,
                       ApplicationPermissionException,
                       UserNotFoundException

Description copied from interface: ApplicationService

Updates the user in the first active directory the User belongs.

If the user does not exist in ANY of the application's active assigned directories, then a UserNotFoundException will be thrown.

If the update operation is not allowed on the User's directory, an ApplicationPermissionException is thrown.

If the update operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Returns the updated User.

Specified by:

updateUser in interface ApplicationService

Parameters:

application - application with assigned directories to operate on.

user - a template of the user to be added. The directoryId of the UserTemplate is ignored, and directories searched for the given username.

Returns:

the updated User.

Throws:

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

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if the User's directory is not allowed to perform operations of type OperationType.UPDATE_USER.

UserNotFoundException - user does not exist in any of the associated active directories of the application.

updateUserCredential

public void updateUserCredential(Application application,
                                 String username,
                                 PasswordCredential credential)
                          throws OperationFailedException,
                                 InvalidCredentialException,
                                 ApplicationPermissionException,
                                 UserNotFoundException

Description copied from interface: ApplicationService

Updates the credentials of the first matching user from all the active directories assigned to the application.

Thus, the method only operates on the same user returned from a call to findUserByName.

Specified by:

updateUserCredential in interface ApplicationService

Parameters:

application - update in application's assigned directories.

username - name of user.

credential - new (unencrypted) credentials.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

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

ApplicationPermissionException - if the first directory in which the user is found doesn't have the permission to perform operations of type OperationType.UPDATE_USER.

UserNotFoundException - if no user with the given name exists in ANY assigned directory.

resetUserCredential

public void resetUserCredential(Application application,
                                String username)
                         throws OperationFailedException,
                                InvalidCredentialException,
                                ApplicationPermissionException,
                                InvalidEmailAddressException,
                                UserNotFoundException

Description copied from interface: ApplicationService

Resets the credentials of the first matching user in the application's active directories.

Thus, the method only operates on the same user returned from a call to findUserByName.

This method will only function correctly if the User has an email address, otherwise no email can be sent to the user.

Specified by:

resetUserCredential in interface ApplicationService

Parameters:

application - update in application's assigned directories.

username - name of user.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

InvalidCredentialException - if the generated credential does not meet the validation requirements for an associated directory.

ApplicationPermissionException - if the first directory in which the user is found doesn't have the permission to perform operations of type OperationType.UPDATE_USER.

InvalidEmailAddressException - if the user doesn't have a valid email address and can't be notified.

UserNotFoundException - if no user with the given name exists in ANY assigned directory

storeUserAttributes

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

Description copied from interface: ApplicationService

Adds or updates a user's attributes with the new Map of attribute values for the first active directory containing this username.

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.

If the user does not exist in ANY of the application's assigned directories, then a UserNotFoundException will be thrown.

If the directory does not have UPDATE_USER permission, an ApplicationPermissionException is thrown.

If the update operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Specified by:

storeUserAttributes in interface ApplicationService

Parameters:

application - application with assigned directories to operate on.

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:

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if the User's directory does not have permission to perform operations of type OperationType.UPDATE_USER_ATTRIBUTE.

UserNotFoundException - if the user with the supplied username does not exist in ANY assigned directory.

removeUserAttributes

public void removeUserAttributes(Application application,
                                 String username,
                                 String attributeName)
                          throws OperationFailedException,
                                 ApplicationPermissionException,
                                 UserNotFoundException

Description copied from interface: ApplicationService

Removes a user's attribute values for the first active directory containing this username.

If the user does not exist in ANY of the application's assigned directories, then a UserNotFoundException will be thrown.

If the directory does not have UPDATE_USER permission, an ApplicationPermissionException is thrown.

If the update operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Specified by:

removeUserAttributes in interface ApplicationService

Parameters:

application - application with assigned directories to operate on.

username - username of the user to update.

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

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if the User's directory does not have permission to perform operations of type OperationType.UPDATE_USER_ATTRIBUTE.

UserNotFoundException - if the user with the supplied username does not exist in ANY assigned directory.

removeUser

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

Description copied from interface: ApplicationService

Removes the user from the first active directory they are found in.

If the user does not exist in ANY of the application's assigned directories, then a UserNotFoundException will be thrown.

If the remove operation fails because of permission restrictions, an ApplicationPermissionException is thrown.

Specified by:

removeUser in interface ApplicationService

Parameters:

application - remove from application's assigned directories.

username - the name of the user to remove.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if the User's directory does not have permission to perform operations of type OperationType.DELETE_USER.

UserNotFoundException - if user with given name does not exist in ANY assigned directory.

searchUsers

public <T> List<T> searchUsers(Application application,
                               EntityQuery<T> query)

Description copied from interface: ApplicationService

Returns a List or List matching the search criteria defined in the query for ALL of the active directories assigned to the application.

Specified by:

searchUsers in interface ApplicationService

Parameters:

application - search application's assigned directories.

query - the search query.

Returns:

List user objects or List usernames, depending on the query.

searchUsersAllowingDuplicateNames

public List<User> searchUsersAllowingDuplicateNames(Application application,
                                                    EntityQuery<User> query)

Description copied from interface: ApplicationService

Returns a List matching the search criteria defined in the query for ALL of the active directories assigned to the application. Users with duplicate user names but different directory IDs can be returned.

Specified by:

searchUsersAllowingDuplicateNames in interface ApplicationService

Parameters:

application - search application's assigned directories.

query - the search query.

Returns:

List user objects.

findGroupByName

public Group findGroupByName(Application application,
                             String name)
                      throws GroupNotFoundException

Description copied from interface: ApplicationService

Returns the first group with the matching groupname from all the active directories assigned to the application.

The directories are searched in the order they are assigned to the application.

Specified by:

findGroupByName in interface ApplicationService

Parameters:

application - search application's assigned directories.

name - the groupname of the group to find.

Returns:

first matching group.

Throws:

GroupNotFoundException - group not found in any of the directories.

findGroupWithAttributesByName

public GroupWithAttributes findGroupWithAttributesByName(Application application,
                                                         String name)
                                                  throws GroupNotFoundException

Description copied from interface: ApplicationService

Returns the first group with the matching groupname from all the active directories assigned to the application.

The directories are searched in the order they are assigned to the application.

Specified by:

findGroupWithAttributesByName in interface ApplicationService

Parameters:

application - search application's assigned directories.

name - the groupname of the group to find.

Returns:

first matching group.

Throws:

GroupNotFoundException - group not found in any of the directories.

addGroup

public Group addGroup(Application application,
                      GroupTemplate group)
               throws InvalidGroupException,
                      OperationFailedException,
                      ApplicationPermissionException

Description copied from interface: ApplicationService

Adds the group to ALL the active permissible directories.

If the group exists in ANY of the application's active assigned directories, then an InvalidGroupException will be thrown.

If the add operation fails on a directory because of permissioning restrictions, an INFO message is logged. If ALL directories permissions fail, an ApplicationPermissionException is thrown.

If the add operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Returns the group from the first directory containing the group.

Specified by:

addGroup in interface ApplicationService

Parameters:

application - add to application's assigned directories.

group - a template of the group to be added. The directoryId of the GroupTemplate is ignored, and will be mutated for each directoryMapping.

Returns:

the added group returned from ApplicationService.findGroupByName(com.atlassian.crowd.model.application.Application , String).

Throws:

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

OperationFailedException - underlying directory implementation failed to execute the operation.

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

updateGroup

public Group updateGroup(Application application,
                         GroupTemplate group)
                  throws InvalidGroupException,
                         OperationFailedException,
                         ApplicationPermissionException,
                         GroupNotFoundException

Description copied from interface: ApplicationService

Updates the group in ALL the active permissible directories.

If the group does not exist in ANY of the application's assigned directories, then a GroupNotFoundException will be thrown.

If the update operation fails on a directory because of permissioning restrictions, an INFO message is logged. If ALL directories permissions fail, an ApplicationPermissionException is thrown.

If the update operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Returns the group from the first directory containing the group.

Specified by:

updateGroup in interface ApplicationService

Parameters:

application - application with assigned directories to operate on.

group - a template of the group to be added. The directoryId of the GroupTemplate is ignored, and will be mutated for each directoryMapping.

Returns:

the added group returned from ApplicationService.findGroupByName(com.atlassian.crowd.model.application.Application , String).

Throws:

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

OperationFailedException - underlying directory implementation failed to execute the operation.

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

GroupNotFoundException - group does not exist in any of the associated directories of the application.

storeGroupAttributes

public void storeGroupAttributes(Application application,
                                 String groupname,
                                 Map<String,Set<String>> attributes)
                          throws OperationFailedException,
                                 ApplicationPermissionException,
                                 GroupNotFoundException

Description copied from interface: ApplicationService

Adds or updates a group's attributes with the new Map of attribute values for all active permissible directories assigned to the application.

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.

If the group does not exist in ANY of the application's assigned directories, then a GroupNotFoundException will be thrown.

If the update operation fails on a directory because of permissioning restrictions, an INFO message is logged. If ALL directories permissions fail, an ApplicationPermissionException is thrown.

If the update operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Specified by:

storeGroupAttributes in interface ApplicationService

Parameters:

application - application with assigned directories to operate on.

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:

OperationFailedException - underlying directory implementation failed to execute the operation.

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

GroupNotFoundException - if the group with the supplied groupname does not exist in ANY assigned directory.

removeGroupAttributes

public void removeGroupAttributes(Application application,
                                  String groupname,
                                  String attributeName)
                           throws OperationFailedException,
                                  ApplicationPermissionException,
                                  GroupNotFoundException

Description copied from interface: ApplicationService

Removes a group's attribute values for all active permissible directories assigned to the application.

If the group does not exist in ANY of the application's assigned directories, then a GroupNotFoundException will be thrown.

If the update operation fails on a directory because of permissioning restrictions, an INFO message is logged. If ALL directories permissions fail, an ApplicationPermissionException is thrown.

If the update operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Specified by:

removeGroupAttributes in interface ApplicationService

Parameters:

application - application with assigned directories to operate on.

groupname - groupname of the group to update.

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

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

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

GroupNotFoundException - if the group with the supplied groupname does not exist in ANY assigned directory.

removeGroup

public void removeGroup(Application application,
                        String groupname)
                 throws OperationFailedException,
                        ApplicationPermissionException,
                        GroupNotFoundException

Description copied from interface: ApplicationService

Removes ALL groups from each of the application's assigned directories that are active.

If the group doesn't exist in ANY of the application's assigned directories that are active, then a GroupNotFoundException will be thrown.

If the remove operation fails on a directory because of permissioning restrictions, an INFO message is logged. If ALL directories permissions fail, a ApplicationPermissionException is thrown.

If the remove operation fails on a directory for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

Specified by:

removeGroup in interface ApplicationService

Parameters:

application - remove from application's assigned directories.

groupname - the name of the group to remove.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

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

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

searchGroups

public <T> List<T> searchGroups(Application application,
                                EntityQuery<T> query)

Description copied from interface: ApplicationService

Returns a List matching the search criteria defined in the query for ALL of the active directories assigned to the application.

Specified by:

searchGroups in interface ApplicationService

Parameters:

application - search application's assigned directories.

query - the search query.

Returns:

List group objects or List groupnames, depending on the query.

addUserToGroup

public void addUserToGroup(Application application,
                           String username,
                           String groupName)
                    throws OperationFailedException,
                           ApplicationPermissionException,
                           UserNotFoundException,
                           GroupNotFoundException

Description copied from interface: ApplicationService

Makes the primary user of the given username a direct member of the group on the directory where the primary user resides.

A user exists in one individual directory, however a group is thought to "span" all directories (users from different directories can belong to the same group). With this in mind, if the group does not exist in the User's directory (but does already exist), then this method will attempt to automatically add the group to that directory for you.

Specified by:

addUserToGroup in interface ApplicationService

Parameters:

application - modify groups in application's assigned directories.

username - username of the user.

groupName - name of the group.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if the application's directory where the primary user resides does not allow operations of type OperationType.UPDATE_GROUP or the group is readonly.

UserNotFoundException - when the user cannot be found in ANY directory

GroupNotFoundException - when the group cannot be found in ANY directory

addGroupToGroup

public void addGroupToGroup(Application application,
                            String childGroupName,
                            String parentGroupName)
                     throws OperationFailedException,
                            ApplicationPermissionException,
                            GroupNotFoundException,
                            InvalidMembershipException

Description copied from interface: ApplicationService

Makes groups matching the given name (childGroupName) direct members of the group (parentGroupName) across ALL active directories.

Specified by:

addGroupToGroup in interface ApplicationService

Parameters:

application - modify groups in the application's assigned directories.

childGroupName - name of child group.

parentGroupName - name of parent group.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if we were unable to create the membership in any directory. This is based on Edit permissions, Create permissions, and whether Nested Groups is supported by the individual directories.

GroupNotFoundException - when the parent or child group do not exist

InvalidMembershipException - The child and parent are of different group types or would cause a circular reference.

removeUserFromGroup

public void removeUserFromGroup(Application application,
                                String username,
                                String groupName)
                         throws OperationFailedException,
                                ApplicationPermissionException,
                                MembershipNotFoundException,
                                UserNotFoundException,
                                GroupNotFoundException

Description copied from interface: ApplicationService

Makes the primary user of the given username no longer a member of the group on the directory where the primary user resides.

Specified by:

removeUserFromGroup in interface ApplicationService

Parameters:

application - modify groups in application's assigned directories.

username - username of the user.

groupName - name of the group.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

ApplicationPermissionException - if the application's directory where the primary user resides does not allow operations of type OperationType.UPDATE_GROUP.

MembershipNotFoundException - if the user is not a direct member of the group in an assigned directory.

UserNotFoundException - when the user cannot be found in ANY directory

GroupNotFoundException - when the group does not exist in the directory where the primary user resides.

removeGroupFromGroup

public void removeGroupFromGroup(Application application,
                                 String childGroup,
                                 String parentGroup)
                          throws OperationFailedException,
                                 ApplicationPermissionException,
                                 MembershipNotFoundException,
                                 GroupNotFoundException

Description copied from interface: ApplicationService

Makes child group matching the given name not members of the parent group across ALL active directories.

Specified by:

removeGroupFromGroup in interface ApplicationService

Parameters:

application - modify groups in application's assigned directories.

childGroup - name of child group.

parentGroup - name of parent group.

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

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

MembershipNotFoundException - if the user is not a direct member of the group in an assigned directory.

GroupNotFoundException - when the child group cannot be found in ANY directory OR when ALL child groups are in directories which don't have the requested parent group.

isUserDirectGroupMember

public boolean isUserDirectGroupMember(Application application,
                                       String username,
                                       String groupName)

Description copied from interface: ApplicationService

Returns true if the user is a direct member of the group in the directory of the first user found with the specified username.

Specified by:

isUserDirectGroupMember in interface ApplicationService

Parameters:

application - search groups in application's assigned directories.

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 any directory, false is returned.

isGroupDirectGroupMember

public boolean isGroupDirectGroupMember(Application application,
                                        String childGroup,
                                        String parentGroup)

Description copied from interface: ApplicationService

Returns true if the childGroup is a direct member of the parentGroup in any of the application's assigned directories.

Specified by:

isGroupDirectGroupMember in interface ApplicationService

Parameters:

application - search groups in application's assigned directories.

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 any directory, false is returned.

isUserNestedGroupMember

public boolean isUserNestedGroupMember(Application application,
                                       String username,
                                       String groupName)

Description copied from interface: ApplicationService

Returns true if the user is a direct or indirect (nested) member of the group in the directory of the first user found with the specified username.

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

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

See CWD-1485 for explanation of logic in amalgamation.

Nesting is not resolved across directories.

Specified by:

isUserNestedGroupMember in interface ApplicationService

Parameters:

application - search groups in application's assigned directories.

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.

isGroupNestedGroupMember

public boolean isGroupNestedGroupMember(Application application,
                                        String childGroup,
                                        String parentGroup)

Description copied from interface: ApplicationService

Returns true if the childGroup is a direct or indirect (nested) member of the parentGroup in any of the application's active assigned directories.

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

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

See CWD-1485 for explanation of logic in amalgamation.

Nesting is not resolved across directories.

Specified by:

isGroupNestedGroupMember in interface ApplicationService

Parameters:

application - search groups in application's assigned directories.

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 parentGroup. If either group does not exist in the directory, false is returned.

searchDirectGroupRelationships

public <T> List<T> searchDirectGroupRelationships(Application application,
                                                  MembershipQuery<T> query)

Description copied from interface: ApplicationService

Searches for direct group relationships in any of the application's active assigned directories. When searching for the groups a user is a member of only the directory of the user (as determined by findUserByName) is searched. When searching for memberships of a group or groups a group is a member of all directories are searched and the results amalgamated.

Specified by:

searchDirectGroupRelationships in interface ApplicationService

Parameters:

application - search groups in application's assigned directories.

query - membership query.

Returns:

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

searchNestedGroupRelationships

public <T> List<T> searchNestedGroupRelationships(Application application,
                                                  MembershipQuery<T> query)

Description copied from interface: ApplicationService

Searches for direct and indirect (nested) group relationships in any of the application's active assigned directories.

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

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

When searching for the groups a user is a member of only the directory of the user (as determined by findUserByName) is searched. When searching for memberships of a group or groups a group is a member of all directories are searched and the results amalgamated.

Specified by:

searchNestedGroupRelationships in interface ApplicationService

Parameters:

application - search groups in application's assigned directories.

query - membership query.

Returns:

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

getCurrentEventToken

public String getCurrentEventToken(Application application)
                            throws IncrementalSynchronisationNotAvailableException

Description copied from interface: ApplicationService

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.

Specified by:

getCurrentEventToken in interface ApplicationService

Parameters:

application - current application

Returns:

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

Throws:

IncrementalSynchronisationNotAvailableException - if the application cannot provide incremental synchronisation

getNewEvents

public Events getNewEvents(Application application,
                           String eventToken)
                    throws EventTokenExpiredException,
                           OperationFailedException

Description copied from interface: ApplicationService

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 ApplicationService.getCurrentEventToken(Application) again before asking for new events.

Specified by:

getNewEvents in interface ApplicationService

Parameters:

application - return events visible to application

eventToken - event token that was retrieved by a call to ApplicationService.getCurrentEventToken(com.atlassian.crowd.model.application.Application) 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

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