Package com.atlassian.crowd.manager.application

Interface ApplicationService

All Known Implementing Classes:
AbstractDelegatingApplicationService, AllowingAuthenticateByEmailApplicationService, ApplicationServiceGeneric, CachingApplicationService, RecoveryModeAwareApplicationService, TranslatingApplicationService
public interface ApplicationService
The exposed service provided by Crowd to client applications.

This class performs amalgamation across the active directories assigned to client applications (providing a unified view of their directories).

  • Method Details

    • authenticateUser

      User authenticateUser(Application application, String username, PasswordCredential passwordCredential) throws OperationFailedException, InactiveAccountException, InvalidAuthenticationException, ExpiredCredentialException, UserNotFoundException
      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.
      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.
      ExpiredCredentialException - if the users credentials have expired
      InactiveAccountException - if the users account is marked as inactive
      InvalidAuthenticationException - if authentication with the provided credentials failed, or potentially the user does not exist.
      UserNotFoundException

    • isUserAuthorised

      boolean isUserAuthorised(Application application, String username)
      Returns true if the user is permitted to attempt authentication 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.
      Parameters:
      application - application user is authenticating against
      username - username
      Returns:
      true</tt> if the user is permitted to attempt authentication with the application, otherwise <tt>false. If the user could not be found, false will be returned.

    • isUserAuthorised

      @Deprecated boolean isUserAuthorised(Application application, User user)
      Deprecated.
      use isUserAuthorised(Application, String)
      Returns true if the user is permitted to attempt authentication 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.
      Parameters:
      application - application user is authenticating against
      user - the user that will be checked
      Returns:
      true</tt> if the user is permitted to attempt authentication with the application, otherwise <tt>false. If the user could not be found, false will be returned.
      Since:
      2.10

    • addAllUsers

      void addAllUsers(Application application, Collection<UserTemplateWithCredentialAndAttributes> users) throws ApplicationPermissionException, OperationFailedException, BulkAddFailedException
      Adds the user to THE FIRST permissible active directory.

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

      Parameters:
      application - add to application's assigned directories.
      users - 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

      User findUserByName(Application application, String name) throws UserNotFoundException
      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.

      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.

    • findRemoteUserByName

      User findRemoteUserByName(Application application, String username) throws UserNotFoundException
      Returns the first user with the matching username from all active directories authoratiative remote directory. This method may perform a remote call and thus relies on the response times of remote directories.

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

      Parameters:
      application - search application's assigned directories.
      username - the username of the user to find.
      Returns:
      first matching user.
      Throws:
      UserNotFoundException - user not found in any of the directories.

    • findUserWithAttributesByName

      UserWithAttributes findUserWithAttributesByName(Application application, String name) throws UserNotFoundException
      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.

      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.

    • findUserByKey

      User findUserByKey(Application application, String key) throws UserNotFoundException
      Returns the user with a matching key from all the active directories assigned to the application.
      Parameters:
      application - application that is looking up the user.
      key - user key to look up by.
      Returns:
      matching user.
      Throws:
      UserNotFoundException - if the canonical user with the given key is not found in the active directories mapped to the application.

    • findUserWithAttributesByKey

      UserWithAttributes findUserWithAttributesByKey(Application application, String key) throws UserNotFoundException
      Returns the user with a matching key from all the active directories assigned to the application.
      Parameters:
      application - application that is looking up the user.
      key - user key to look up by.
      Returns:
      matching user, with attributes.
      Throws:
      UserNotFoundException - if the canonical user with the given key is not found in the active directories mapped to the application.

    • addUser

      @Deprecated User addUser(Application application, UserTemplate user, PasswordCredential credential) throws InvalidUserException, OperationFailedException, InvalidCredentialException, ApplicationPermissionException
      Deprecated.
      Use addUser(com.atlassian.crowd.model.application.Application, com.atlassian.crowd.model.user.UserTemplateWithAttributes, com.atlassian.crowd.embedded.api.PasswordCredential) instead. Since v2.9
      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.

      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 findUserByName(com.atlassian.crowd.model.application.Application, String).
      Throws:
      InvalidCredentialException - if the user's credential does not meet the validation requirements for an associated directory.
      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.
      ApplicationPermissionException - if none of the application's associated directories are allowed to perform operations of type OperationType.CREATE_USER.

    • addUser

      UserWithAttributes addUser(Application application, UserTemplateWithAttributes user, PasswordCredential credential) throws InvalidUserException, OperationFailedException, InvalidCredentialException, ApplicationPermissionException
      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.

      Parameters:
      application - add to application's assigned directories.
      user - a template of the user to be added. The directoryId of the UserTemplateWithAttributes is ignored, and will be mutated for each directoryMapping.
      credential - the password credential of the user (unencrypted).
      Returns:
      the added user returned from findUserWithAttributesByName(com.atlassian.crowd.model.application.Application, String).
      Throws:
      InvalidCredentialException - if the user's credential does not meet the validation requirements for an associated directory.
      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.
      ApplicationPermissionException - if none of the application's associated directories are allowed to perform operations of type OperationType.CREATE_USER.

    • updateUser

      User updateUser(Application application, UserTemplate user) throws InvalidUserException, OperationFailedException, ApplicationPermissionException, UserNotFoundException
      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.

      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.

    • setUserStatusLocally

      User setUserStatusLocally(@Nonnull Application application, String username, boolean userActiveInternally) throws InvalidUserException, OperationFailedException, ApplicationPermissionException, UserNotFoundException, DirectoryNotFoundException
      Set the user's active status in the first active directory the User belongs

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

      If setting the active flag fails for any other reason, such as directory failure, update failure, etc., an Exception is thrown immediately.

      Returns the updated User.

      Parameters:
      application - application with assigned directories to operate on.
      username - username for which active status change is needed.
      userActiveInternally - Whether to activate/deactivate the user
      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.
      UserNotFoundException - user does not exist in internal directory of the application.
      ApplicationPermissionException
      DirectoryNotFoundException
      Since:
      6.1.0

    • renameUser

      User renameUser(Application application, String oldUserName, String newUsername) throws UserNotFoundException, OperationFailedException, ApplicationPermissionException, InvalidUserException
      Renames the user in the first active directory the users exists in.

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

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

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

      Returns the renamed User.

      Parameters:
      application - application with assigned directories to operate on.
      oldUserName - current username of the user to rename.
      newUsername - new username of the renamed user.
      Returns:
      the renamed User.
      Throws:
      UserNotFoundException - user does not exist in any of the associated active directories of the application.
      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.
      InvalidUserException - if the new username does not meet the username requirements for an associated directory.

    • updateUserCredential

      void updateUserCredential(Application application, String username, PasswordCredential credential) throws OperationFailedException, UserNotFoundException, InvalidCredentialException, ApplicationPermissionException
      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.

      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.
      UnsupportedOperationException - if the underlying directory does not support user renaming.

    • storeUserAttributes

      void storeUserAttributes(Application application, String username, Map<String,Set<String>> attributes) throws OperationFailedException, ApplicationPermissionException, UserNotFoundException
      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.

      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:
      UserNotFoundException - if the user with the supplied username does not exist in ANY assigned directory.
      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.

    • removeUserAttributes

      void removeUserAttributes(Application application, String username, String attributeName) throws OperationFailedException, ApplicationPermissionException, UserNotFoundException
      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.

      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:
      UserNotFoundException - if the user with the supplied username does not exist in ANY assigned directory.
      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.

    • removeUser

      void removeUser(Application application, String user) throws OperationFailedException, UserNotFoundException, ApplicationPermissionException
      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.

      Parameters:
      application - remove from application's assigned directories.
      user - the name of the user to remove.
      Throws:
      OperationFailedException - underlying directory implementation failed to execute the operation.
      UserNotFoundException - if user with given name does not exist in ANY assigned directory.
      ApplicationPermissionException - if the User's directory does not have permission to perform operations of type OperationType.DELETE_USER.

    • searchUsers

      <T> List<T> searchUsers(Application application, EntityQuery<T> query)
      Returns a List<User> or List<String> matching the search criteria defined in the query for ALL of the active directories assigned to the application.

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

      Parameters:
      application - search application's assigned directories.
      query - the search query.
      Returns:
      List<User> user objects or List<String> usernames, depending on the query.

    • findGroupByName

      Group findGroupByName(Application application, String name) throws GroupNotFoundException
      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.

      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

      GroupWithAttributes findGroupWithAttributesByName(Application application, String name) throws GroupNotFoundException
      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.

      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

      Group addGroup(Application application, GroupTemplate group) throws InvalidGroupException, OperationFailedException, ApplicationPermissionException
      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.

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

      Group updateGroup(Application application, GroupTemplate group) throws InvalidGroupException, OperationFailedException, ApplicationPermissionException, GroupNotFoundException
      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.

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

      void storeGroupAttributes(Application application, String groupname, Map<String,Set<String>> attributes) throws OperationFailedException, ApplicationPermissionException, GroupNotFoundException
      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.

      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:
      GroupNotFoundException - if the group with the supplied groupname does not exist in ANY assigned directory.
      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.

    • removeGroupAttributes

      void removeGroupAttributes(Application application, String groupname, String attributeName) throws OperationFailedException, ApplicationPermissionException, GroupNotFoundException
      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.

      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:
      GroupNotFoundException - if the group with the supplied groupname does not exist in ANY assigned directory.
      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.

    • removeGroup

      void removeGroup(Application application, String group) throws OperationFailedException, GroupNotFoundException, ApplicationPermissionException
      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.

      Parameters:
      application - remove from application's assigned directories.
      group - the name of the group to remove.
      Throws:
      OperationFailedException - underlying directory implementation failed to execute the operation.
      GroupNotFoundException - if group with given name does not exist in ANY assigned directory.
      ApplicationPermissionException - if none of the application's associated directories are allowed to perform operations of type OperationType.DELETE_GROUP.

    • searchGroups

      <T> List<T> searchGroups(Application application, EntityQuery<T> query)
      Returns a List<Group> matching the search criteria defined in the query for ALL of the active directories assigned to the application.

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

      Parameters:
      application - search application's assigned directories.
      query - the search query.
      Returns:
      List<Group> group objects or List<String> groupnames, depending on the query.

    • addUserToGroup

      void addUserToGroup(Application application, String username, String groupName) throws OperationFailedException, UserNotFoundException, GroupNotFoundException, ApplicationPermissionException, MembershipAlreadyExistsException
      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.

      Parameters:
      application - modify groups in application's assigned directories.
      username - username of the user.
      groupName - name of the group.
      Throws:
      UserNotFoundException - when the user cannot be found in ANY directory
      GroupNotFoundException - when the group cannot be found in ANY directory
      MembershipAlreadyExistsException - if the user is already a member of the group
      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.

    • addGroupToGroup

      void addGroupToGroup(Application application, String childGroupName, String parentGroupName) throws OperationFailedException, GroupNotFoundException, ApplicationPermissionException, InvalidMembershipException, MembershipAlreadyExistsException
      Makes groups matching the given name (childGroupName) direct members of the group (parentGroupName) across ALL active directories.
      Parameters:
      application - modify groups in the application's assigned directories.
      childGroupName - name of child group.
      parentGroupName - name of parent group.
      Throws:
      GroupNotFoundException - when the parent or child group do not exist
      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.
      MembershipAlreadyExistsException - if the child group is already a child of the parent group
      InvalidMembershipException - The child and parent are of different group types or would cause a circular reference.

    • removeUserFromGroup

      void removeUserFromGroup(Application application, String username, String groupName) throws OperationFailedException, GroupNotFoundException, UserNotFoundException, ApplicationPermissionException, MembershipNotFoundException
      Makes the primary user of the given username no longer a member of the group on the directory where the primary user resides.
      Parameters:
      application - modify groups in application's assigned directories.
      username - username of the user.
      groupName - name of the group.
      Throws:
      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.
      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.

    • removeGroupFromGroup

      void removeGroupFromGroup(Application application, String childGroup, String parentGroup) throws OperationFailedException, GroupNotFoundException, ApplicationPermissionException, MembershipNotFoundException
      Makes child group matching the given name not members of the parent group across ALL active directories.
      Parameters:
      application - modify groups in application's assigned directories.
      childGroup - name of child group.
      parentGroup - name of parent group.
      Throws:
      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.
      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.

    • isUserDirectGroupMember

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

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

      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.

      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.

      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

      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.

      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.

      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

      <T> List<T> searchDirectGroupRelationships(Application application, MembershipQuery<T> query)
      Searches for direct group relationships in any of the application's active assigned directories. When searching for the groups an entity is a member of, the membership aggregation semantic will determine whether only the owning directory (when false) or all directories (when true) will be searched.
      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

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

      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.

      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

      String getCurrentEventToken(Application application) throws IncrementalSynchronisationNotAvailableException
      Returns a token that can be used for querying events that have happened after the token was generated.

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

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

      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
      Since:
      2.3

    • getNewEvents

      Events getNewEvents(Application application, String eventToken) throws EventTokenExpiredException, OperationFailedException
      Returns an events object which contains a new eventToken and events that happened after the given eventToken was generated.

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

      Parameters:
      application - return events visible to application
      eventToken - event token that was retrieved by a call to 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
      Since:
      2.3

    • findWebhookById

      Webhook findWebhookById(Application application, long webhookId) throws WebhookNotFoundException, ApplicationPermissionException
      Retrieves a Webhook by its identifier. Identifiers are assigned when a Webhook is created.
      Parameters:
      application - the application that owns the Webhook. Only the application that registered the Webhook is allowed to retrieve it
      webhookId - Id of a Webhook, as returned by registerWebhook(com.atlassian.crowd.model.application.Application, String, String)
      Returns:
      the Webhook
      Throws:
      WebhookNotFoundException - if a Webhook with the given Id does not exist
      ApplicationPermissionException - if the Webhook exists, but was registered by a different application

    • registerWebhook

      Webhook registerWebhook(Application application, String endpointUrl, @Nullable String token) throws InvalidWebhookEndpointException
      Registers a Webhook associated to the application.
      Parameters:
      application - the application that owns the Webhook. Only this application will be able to unregister it later.
      endpointUrl - the application-provided HTTP endpoint that will be POST'ed by Crowd when new events are ready to be collected.
      token - the token Crowd will use to ping the Webhook endpoint (optional).
      Returns:
      the new Webhook
      Throws:
      InvalidWebhookEndpointException - when endpointUrl is not a valid url
      Since:
      2.7

    • unregisterWebhook

      void unregisterWebhook(Application application, long webhookId) throws ApplicationPermissionException, WebhookNotFoundException
      Unregisters a Webhook. Only the application that created the Webhook can unregister it.
      Parameters:
      application - the application that owns the Webhook.
      webhookId - the identifier of the Webhook that will be unregistered.
      Throws:
      ApplicationPermissionException - if the application is not the same that registered the Webhook.
      WebhookNotFoundException - if the Webhook is not found on the server
      Since:
      2.7

    • getCapabilitiesForNewUsers

      UserCapabilities getCapabilitiesForNewUsers(Application application)
      Gets the expected capabilities for new users.

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

      Parameters:
      application - the application the directories are assigned to
      Returns:
      the capabilities a new user will have
      See Also:

    • getUserAvatarLink

      @Nullable URI getUserAvatarLink(Application application, String username, int sizeHint) throws UserNotFoundException, DirectoryNotFoundException, OperationFailedException
      Gets a URL for an avatar for this user, if one is available. This may point back to the same Crowd server or to another service. The URI should be evaluated relative to Crowd's base URL.
      Parameters:
      username - the user to fetch an avatar for, as returned from a find method
      sizeHint - a hint in pixels for how large the image should be
      Throws:
      UserNotFoundException
      DirectoryNotFoundException
      OperationFailedException

    • getUserAvatar

      @Nullable AvatarReference getUserAvatar(Application application, String username, int sizeHint) throws UserNotFoundException, DirectoryNotFoundException, OperationFailedException
      Gets an avatar for this user, if one is available. This may be a URL or a blob of image data. If it's a URI, it should be evaluated relative to Crowd's base URL.
      Parameters:
      username - the user to fetch an avatar for, as returned from a find method
      sizeHint - a hint in pixels for how large the image should be
      Throws:
      UserNotFoundException
      DirectoryNotFoundException
      OperationFailedException

    • expireAllPasswords

      void expireAllPasswords(Application application) throws OperationFailedException
      Expires all passwords for all directories which are part of this application, regardless of group mapping.
      Parameters:
      application - the application for which to expire all passwords in all mapped directories.
      Throws:
      OperationFailedException - if any of the directories fail to expire all passwords. This can lead to only some of the users having expired passwords.

    • userAuthenticated

      @ExperimentalApi User userAuthenticated(Application application, String username) throws UserNotFoundException, OperationFailedException, InactiveAccountException
      Throws:
      UserNotFoundException
      OperationFailedException
      InactiveAccountException

    • getMemberships

      @ExperimentalApi ApplicationService.MembershipsIterable getMemberships(Application application)
      Returns all memberships for the given application.
      Parameters:
      application - the application for which memberships will be returned
      Returns:
      all memberships for the given application.

    • createPagedUserSearcher

      @ExperimentalApi <T> PagedSearcher<T> createPagedUserSearcher(Application application, EntityQuery<T> query) throws PagingNotSupportedException
      Creates paged user searcher for a given user query. Use this method to avoid re-querying the same data and lower memory usage. Searcher never pre-fetches nor keeps more than requested batch size results per directory.
      Throws:
      PagingNotSupportedException

    • createPagedGroupSearcher

      @ExperimentalApi <T> PagedSearcher<T> createPagedGroupSearcher(Application application, EntityQuery<T> query) throws PagingNotSupportedException
      Creates paged group searcher for a given group query. Use this method to avoid re-querying the same data and lower memory usage. Searcher never pre-fetches nor keeps more than requested batch size results per directory.
      Throws:
      PagingNotSupportedException