Package com.spotfire.server.api.userdir

Class UserDirectory

java.lang.Object
com.spotfire.server.api.userdir.UserDirectory
public abstract class UserDirectory extends Object
Provides functionality to create, read, update and delete users and groups.
Since:
10.1
See Also:

  • Method Details Link icon

    • getUser Link icon

      public abstract UserPrincipal getUser(String name, String domainName) throws UserDirectoryException
      Returns the user with the specified name and domain.
      Parameters:
      name - the name of the user, must not be null or an empty string
      domainName - the name of the user's domain, must not be null or an empty string
      Returns:
      the requested user, or null if no such user exists
      Throws:
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • getUser Link icon

      public abstract UserPrincipal getUser(Guid guid) throws UserDirectoryException
      Returns the user with the specified GUID.
      Parameters:
      guid - the GUID of the user, must not be null
      Returns:
      the requested user, or null if no such user exists
      Throws:
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • getGroup Link icon

      public abstract GroupPrincipal getGroup(String name, String domainName) throws UserDirectoryException
      Returns the group with the specified name and domain.
      Parameters:
      name - the name of the group, must not be null or an empty string
      domainName - the name of the group domain, must not be null or an empty string
      Returns:
      the requested group, or null if no such group exists
      Throws:
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • getGroup Link icon

      public abstract GroupPrincipal getGroup(Guid guid) throws UserDirectoryException
      Returns the group with the specified GUID.
      Parameters:
      guid - the GUID of the group, must not be null
      Returns:
      the requested group, or null if no such group exists
      Throws:
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • searchUsers Link icon

      public abstract Set<UserPrincipal> searchUsers(PrincipalProperty searchProperty, String searchExpression, int maxResults) throws UserDirectoryException
      Returns all users, up to the specified upper limit, with a given property that matches the given search expression.

      The search expression should be a name, display name or email address, or part thereof, with optional '?' (matches any single character) and '*' (matches zero or more characters) wildcards.

      Parameters:
      searchProperty - the property to search, must not be null
      searchExpression - the search expression to match with, must not be null or an empty string and must not exceed 450 characters
      maxResults - the maximum number of users to return, or -1 if no limit should be imposed
      Returns:
      a possibly empty set of all users with a given property that matches the given search expression
      Throws:
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • searchGroups Link icon

      public abstract Set<GroupPrincipal> searchGroups(PrincipalProperty searchProperty, String searchExpression, int maxResults) throws UserDirectoryException
      Returns all groups, up to the specified upper limit, with a given property that matches the given search expression.

      The search expression should be a name, display name or email address, or part thereof, with optional '?' (matches any single character) and '*' (matches zero or more characters) wildcards.

      Parameters:
      searchProperty - the property to search, must not be null
      searchExpression - the search expression to match with, must not be null or an empty string and must not exceed 450 characters
      maxResults - the maximum number of groups to return, or -1 if no limit should be imposed
      Returns:
      a possibly empty set of all groups with a given property that matches the given search expression
      Throws:
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • createUser Link icon

      public abstract UserPrincipal createUser(String name, String domainName, String displayName, String emailAddress, String password) throws InvalidArgumentException, PrincipalAlreadyExistsException, UserDirectoryException
      Creates a new user. If the password is null the user will not be able to login when using Spotfire Database as authentication method.
      Parameters:
      name - the name of the user, must not be null or an empty string and must not exceed 200 characters
      domainName - the domain name, must not be null or an empty string and must not exceed 200 characters
      displayName - the display name, must not be null or an empty string and must not exceed 450 characters
      emailAddress - the e-mail address, may be null but must not be an empty string or an invalid e-mail address
      password - the new password, may be null but must not be an empty string
      Returns:
      the newly created user
      Throws:
      InvalidPasswordException - if the password is invalid
      InvalidArgumentException - if the user name, the domain name, the display name or the e-mail address is invalid
      PrincipalAlreadyExistsException - if a user with the same name already exists in the same domain
      InvalidOperationException - if creation of users is not allowed (at all, or in the given domain)
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • createGroup Link icon

      public abstract GroupPrincipal createGroup(String name, String displayName, String emailAddress) throws InvalidArgumentException, PrincipalAlreadyExistsException, UserDirectoryException
      Creates a new group in the SPOTFIRE domain.
      Parameters:
      name - the name of the group, must not be null or an empty string and must not exceed 200 characters
      displayName - the display name, must not be null or an empty string and must not exceed 450 characters
      emailAddress - the e-mail address, may be null but must not be an empty string or an invalid e-mail address or exceed 450 characters
      Returns:
      the newly created group
      Throws:
      InvalidArgumentException - if the group name, the display name or the e-mail address is invalid
      PrincipalAlreadyExistsException - if a group with the same name already exists in the SPOTFIRE domain
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • setName Link icon

      public abstract <T extends SpotfirePrincipal> T setName(T principal, String name) throws InvalidArgumentException, NoSuchPrincipalException, PrincipalAlreadyExistsException, UserDirectoryException
      Sets the name for the given principal (user or group).
      Type Parameters:
      T - the type of principal
      Parameters:
      principal - the principal to set the name for, must not be null
      name - the new, must not be null or an empty string and must not exceed 200 characters
      Returns:
      the updated principal
      Throws:
      InvalidArgumentException - if the name is invalid
      NoSuchPrincipalException - if the principal doesn't exist
      PrincipalAlreadyExistsException - if another principal of the same type with the new name already exists in the same domain
      InvalidOperationException - if the principal is fixed
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • setDisplayName Link icon

      public abstract <T extends SpotfirePrincipal> T setDisplayName(T principal, String displayName) throws InvalidArgumentException, NoSuchPrincipalException, UserDirectoryException
      Sets the display name for the given principal (user or group).
      Type Parameters:
      T - the type of principal
      Parameters:
      principal - the principal to set the display name for, must not be null
      displayName - the new display name, must not be null or an empty string and must not exceed 450 characters
      Returns:
      the updated principal
      Throws:
      InvalidArgumentException - if the display name is invalid
      NoSuchPrincipalException - if the principal doesn't exist
      InvalidOperationException - if the principal is fixed
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • setEmailAddress Link icon

      public abstract <T extends SpotfirePrincipal> T setEmailAddress(T principal, String emailAddress) throws InvalidArgumentException, NoSuchPrincipalException, UserDirectoryException
      Sets the e-mail address for the given principal (user or group).
      Type Parameters:
      T - the type of principal
      Parameters:
      principal - the principal to set the e-mail address for, must not be null
      emailAddress - the new e-mail address, may be null but must not be an empty string or an invalid e-mail address or exceed 450 characters
      Returns:
      the updated principal
      Throws:
      InvalidArgumentException - if the e-mail address is invalid
      NoSuchPrincipalException - if the principal doesn't exist
      InvalidOperationException - if the principal is fixed
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • setEnabled Link icon

      public abstract UserPrincipal setEnabled(UserPrincipal user, boolean enabled) throws NoSuchPrincipalException, UserDirectoryException
      Enables or disables the given user. Disabling a user means that it will be prevented from logging in. To prevent a user for logging in for an limited amount of time use the lock(UserPrincipal, long, TimeUnit) method instead. The change will not have any effect on a currently authenticated user (until the user needs to re-authenticate, possibly due to an absolute session timeout).
      Parameters:
      user - the user to set the enabled flag for, must not be null
      enabled - the new value for the enabled flag
      Returns:
      the updated user
      Throws:
      NoSuchPrincipalException - if the user doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • unlock Link icon

      public abstract UserPrincipal unlock(UserPrincipal user) throws NoSuchPrincipalException, UserDirectoryException
      Unlocks the given user.
      Parameters:
      user - the user to unlock, must not be null
      Returns:
      the updated user
      Throws:
      NoSuchPrincipalException - if the user doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1
      See Also:

    • lock Link icon

      public abstract UserPrincipal lock(UserPrincipal user, long time, TimeUnit unit) throws InvalidArgumentException, NoSuchPrincipalException, UserDirectoryException
      Locks the given user for a specified amount of time. Locking a user means that it will be temporarily prevented from logging in. To prevent a user for logging in for an indefinite amount of time use the setEnabled(UserPrincipal, boolean) method instead. The change will not have any effect on a currently authenticated user (until the user needs to re-authenticate, possibly due to an absolute session timeout).
      Parameters:
      user - the user to lock, must not be null
      time - the time for which the user should be locked, must be greater than 0
      unit - the time unit of the time argument, must not be null and cannot be a higher granularity than seconds
      Returns:
      the updated user
      Throws:
      InvalidArgumentException - if the time exceeds the maximum time a user may be locked (configurable)
      NoSuchPrincipalException - if the user doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1
      See Also:

    • setPassword Link icon

      public abstract void setPassword(UserPrincipal user, String password) throws InvalidPasswordException, NoSuchPrincipalException, UserDirectoryException
      Sets the password for the given user. If the password is null any existing password will be cleared and the user will not be able to login when using Spotfire Database as authentication method.
      Parameters:
      user - the user to set the password for, must not be null
      password - the new password, may be null but must not be an empty string
      Throws:
      InvalidPasswordException - if the password invalid
      NoSuchPrincipalException - if the user doesn't exist
      InvalidOperationException - if the user is fixed
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • deletePrincipal Link icon

      public abstract boolean deletePrincipal(SpotfirePrincipal principal) throws UserDirectoryException
      Deletes the given principal (user or group), if it exists. Returns true if the principal existed and thus was deleted (ore equivalently if a change was made as a result of this call).
      Parameters:
      principal - the principal to delete, must not be null
      Returns:
      true if a change was made as a result of this call, and false otherwise
      Throws:
      InvalidOperationException - if the principal is fixed
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • deletePrincipals Link icon

      public abstract boolean deletePrincipals(Collection<? extends SpotfirePrincipal> principals) throws UserDirectoryException
      Deletes the given principals (users or groups), if they exist. Returns true if one or more principals existed and thus were deleted (ore equivalently if a change was made as a result of this call).
      Parameters:
      principals - a possibly empty collection of principals to delete, must not be null
      Returns:
      true if a change was made as a result of this call, and false otherwise
      Throws:
      InvalidOperationException - if any of the principals are fixed
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • getParentGroups Link icon

      public abstract Set<GroupPrincipal> getParentGroups(SpotfirePrincipal principal) throws NoSuchPrincipalException, UserDirectoryException
      Returns the groups that the given principal (user or group) is an immediate member of.
      Parameters:
      principal - the principal, must not be null
      Returns:
      a possibly empty set of all groups that the given principal is an immediate member of
      Throws:
      NoSuchPrincipalException - if the principal doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • setParentGroups Link icon

      public abstract void setParentGroups(SpotfirePrincipal principal, Collection<GroupPrincipal> groups) throws NoSuchPrincipalException, UserDirectoryException
      Sets the groups that the given principal (user or group) should be an immediate member of. The principal will be removed from any existing groups.
      Parameters:
      principal - the principal, must not be null
      groups - a possibly empty collection of groups that the principal should be an immediate member of, must not be null
      Throws:
      NoSuchPrincipalException - if the principal or any of the group principals doesn't exist
      InvalidArgumentException - if any of the groups is a descendant of the principal (and making the principal a member of the group would thus create a circular dependency)
      InvalidOperationException - if any of the given groups are immutable
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • getAncestorGroups Link icon

      public abstract Set<GroupPrincipal> getAncestorGroups(SpotfirePrincipal principal) throws NoSuchPrincipalException, UserDirectoryException
      Returns the groups that the given principal (user or group) is an immediate or inherited member of.
      Parameters:
      principal - the principal, must not be null
      Returns:
      a possibly empty set of all groups that the given principal is an immediate or inherited member of
      Throws:
      NoSuchPrincipalException - if the principal doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • isMember Link icon

      public abstract boolean isMember(GroupPrincipal group, SpotfirePrincipal principal) throws NoSuchPrincipalException, UserDirectoryException
      Returns true if the given principal (user or group) is a member (immediate or inherited) of the given group.
      Parameters:
      group - the group to determine membership of, must not be null
      principal - the principal to determine membership for, must not be null
      Returns:
      true if the given principal is a member of the given group and false otherwise
      Throws:
      NoSuchPrincipalException - if the group or the principal doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • getMembers Link icon

      public abstract Set<SpotfirePrincipal> getMembers(GroupPrincipal group) throws NoSuchPrincipalException, UserDirectoryException
      Returns the immediate members (users or groups) of the given group.
      Parameters:
      group - the group, must not be null
      Returns:
      a possibly empty set of all immediate members of the group
      Throws:
      NoSuchPrincipalException - if the group doesn't exist
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • setMembers Link icon

      public abstract void setMembers(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) throws NoSuchPrincipalException, UserDirectoryException
      Sets the given principals (users or groups) as members of the given group. Any existing members will be removed.
      Parameters:
      group - the group for which the the members should be set, must not be null
      principals - a possibly empty collection of principals that should be set as members of the group, must not be null
      Throws:
      NoSuchPrincipalException - if the group or any of the member principals doesn't exist
      InvalidArgumentException - if the group is a descendant of any of the principals (and making the principal a member of the group would thus create a circular dependency)
      InvalidOperationException - if the group is immutable
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • addMember Link icon

      public abstract void addMember(GroupPrincipal group, SpotfirePrincipal principal) throws NoSuchPrincipalException, UserDirectoryException
      Adds the given principal (user or group) to the given group.
      Parameters:
      group - the group which the principal should be added to, must not be null
      principal - the principal that should be added to the group, must not be null
      Throws:
      NoSuchPrincipalException - if the group or the member principal doesn't exist
      InvalidArgumentException - if the group is a descendant of the principal (and adding the principal as a member would thus create a circular dependency)
      InvalidOperationException - if the group is immutable
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • addMembers Link icon

      public abstract void addMembers(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) throws NoSuchPrincipalException, UserDirectoryException
      Adds the given principals (users or groups) to the given group.
      Parameters:
      group - the group which the principals should be added to, must not be null
      principals - a possibly empty collection of principals that should be added to the group, must not be null
      Throws:
      NoSuchPrincipalException - if the group or any of the member principals doesn't exist
      InvalidArgumentException - if the group is a descendant of any of the principals (and making the principal a member of the group would thus create a circular dependency)
      InvalidOperationException - if the group is immutable
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • removeMember Link icon

      public abstract boolean removeMember(GroupPrincipal group, SpotfirePrincipal principal) throws NoSuchPrincipalException, UserDirectoryException
      Removes the given principal (user or group) from the given group if it exists and is a member of the group. Returns true if the principal existed and was a member of the group and thus was removed (ore equivalently if a change was made as a result of this call).
      Parameters:
      group - the group which the principals should be removed from, must not be null
      principal - the principal that should be removed from the group, must not be null
      Returns:
      true if a change was made as a result of this call, and false otherwise
      Throws:
      NoSuchPrincipalException - if the group or the member principal doesn't exist
      InvalidOperationException - if the group is immutable
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1

    • removeMembers Link icon

      public abstract boolean removeMembers(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) throws NoSuchPrincipalException, UserDirectoryException
      Removes the given principals (users or groups) from the given group. Returns true if one or more of the principals existed and were members of the group and thus were removed (ore equivalently if a change was made as a result of this call).
      Parameters:
      group - the group which the principals should be removed from, must not be null
      principals - a possibly empty collection of principals that should be removed from the group, must not be null
      Returns:
      true if a change was made as a result of this call, and false otherwise
      Throws:
      NoSuchPrincipalException - if the group or any of the member principals doesn't exist
      InvalidOperationException - if the group is immutable
      UserDirectoryException - if an unexpected error occurs
      Since:
      10.1