Package com.spotfire.server.api.userdir
Class UserDirectory
java.lang.Object
com.spotfire.server.api.userdir.UserDirectory
Provides functionality to create, read, update and delete users and groups.
- Since:
- 10.1
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
addMember
(GroupPrincipal group, SpotfirePrincipal principal) Adds the given principal (user or group) to the given group.abstract void
addMembers
(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) Adds the given principals (users or groups) to the given group.abstract GroupPrincipal
createGroup
(String name, String displayName, String emailAddress) Creates a new group in theSPOTFIRE
domain.abstract UserPrincipal
createUser
(String name, String domainName, String displayName, String emailAddress, String password) Creates a new user.abstract boolean
deletePrincipal
(SpotfirePrincipal principal) Deletes the given principal (user or group), if it exists.abstract boolean
deletePrincipals
(Collection<? extends SpotfirePrincipal> principals) Deletes the given principals (users or groups), if they exist.abstract Set
<GroupPrincipal> getAncestorGroups
(SpotfirePrincipal principal) Returns the groups that the given principal (user or group) is an immediate or inherited member of.abstract GroupPrincipal
Returns the group with the specified GUID.abstract GroupPrincipal
Returns the group with the specified name and domain.abstract Set
<SpotfirePrincipal> getMembers
(GroupPrincipal group) Returns the immediate members (users or groups) of the given group.abstract Set
<GroupPrincipal> getParentGroups
(SpotfirePrincipal principal) Returns the groups that the given principal (user or group) is an immediate member of.abstract UserPrincipal
Returns the user with the specified GUID.abstract UserPrincipal
Returns the user with the specified name and domain.abstract boolean
isMember
(GroupPrincipal group, SpotfirePrincipal principal) Returns true if the given principal (user or group) is a member (immediate or inherited) of the given group.abstract UserPrincipal
lock
(UserPrincipal user, long time, TimeUnit unit) Locks the given user for a specified amount of time.abstract boolean
removeMember
(GroupPrincipal group, SpotfirePrincipal principal) Removes the given principal (user or group) from the given group if it exists and is a member of the group.abstract boolean
removeMembers
(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) Removes the given principals (users or groups) from the given group.abstract Set
<GroupPrincipal> searchGroups
(PrincipalProperty searchProperty, String searchExpression, int maxResults) Returns all groups, up to the specified upper limit, with a given property that matches the given search expression.abstract Set
<UserPrincipal> searchUsers
(PrincipalProperty searchProperty, String searchExpression, int maxResults) Returns all users, up to the specified upper limit, with a given property that matches the given search expression.abstract <T extends SpotfirePrincipal>
TsetDisplayName
(T principal, String displayName) Sets the display name for the given principal (user or group).abstract <T extends SpotfirePrincipal>
TsetEmailAddress
(T principal, String emailAddress) Sets the e-mail address for the given principal (user or group).abstract UserPrincipal
setEnabled
(UserPrincipal user, boolean enabled) Enables or disables the given user.abstract void
setMembers
(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) Sets the given principals (users or groups) as members of the given group.abstract <T extends SpotfirePrincipal>
TSets the name for the given principal (user or group).abstract void
setParentGroups
(SpotfirePrincipal principal, Collection<GroupPrincipal> groups) Sets the groups that the given principal (user or group) should be an immediate member of.abstract void
setPassword
(UserPrincipal user, String password) Sets the password for the given user.abstract UserPrincipal
unlock
(UserPrincipal user) Unlocks the given user.
-
Method Details
-
getUser
Returns the user with the specified name and domain.- Parameters:
name
- the name of the user, must not benull
or an empty stringdomainName
- the name of the user's domain, must not benull
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
Returns the user with the specified GUID.- Parameters:
guid
- the GUID of the user, must not benull
- Returns:
- the requested user, or
null
if no such user exists - Throws:
UserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
getGroup
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 benull
or an empty stringdomainName
- the name of the group domain, must not benull
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
Returns the group with the specified GUID.- Parameters:
guid
- the GUID of the group, must not benull
- Returns:
- the requested group, or
null
if no such group exists - Throws:
UserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
searchUsers
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 benull
searchExpression
- the search expression to match with, must not benull
or an empty string and must not exceed 450 charactersmaxResults
- 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
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 benull
searchExpression
- the search expression to match with, must not benull
or an empty string and must not exceed 450 charactersmaxResults
- 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
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 isnull
the user will not be able to login when using Spotfire Database as authentication method.- Parameters:
name
- the name of the user, must not benull
or an empty string and must not exceed 200 charactersdomainName
- the domain name, must not benull
or an empty string and must not exceed 200 charactersdisplayName
- the display name, must not benull
or an empty string and must not exceed 450 charactersemailAddress
- the e-mail address, may benull
but must not be an empty string or an invalid e-mail addresspassword
- the new password, may benull
but must not be an empty string- Returns:
- the newly created user
- Throws:
InvalidPasswordException
- if the password is invalidInvalidArgumentException
- if the user name, the domain name, the display name or the e-mail address is invalidPrincipalAlreadyExistsException
- if a user with the same name already exists in the same domainInvalidOperationException
- if creation of users is not allowed (at all, or in the given domain)UserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
createGroup
public abstract GroupPrincipal createGroup(String name, String displayName, String emailAddress) throws InvalidArgumentException, PrincipalAlreadyExistsException, UserDirectoryException Creates a new group in theSPOTFIRE
domain.- Parameters:
name
- the name of the group, must not benull
or an empty string and must not exceed 200 charactersdisplayName
- the display name, must not benull
or an empty string and must not exceed 450 charactersemailAddress
- the e-mail address, may benull
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 invalidPrincipalAlreadyExistsException
- if a group with the same name already exists in theSPOTFIRE
domainUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
setName
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 benull
name
- the new, must not benull
or an empty string and must not exceed 200 characters- Returns:
- the updated principal
- Throws:
InvalidArgumentException
- if the name is invalidNoSuchPrincipalException
- if the principal doesn't existPrincipalAlreadyExistsException
- if another principal of the same type with the new name already exists in the same domainInvalidOperationException
- if the principal is fixedUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
setDisplayName
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 benull
displayName
- the new display name, must not benull
or an empty string and must not exceed 450 characters- Returns:
- the updated principal
- Throws:
InvalidArgumentException
- if the display name is invalidNoSuchPrincipalException
- if the principal doesn't existInvalidOperationException
- if the principal is fixedUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
setEmailAddress
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 benull
emailAddress
- the new e-mail address, may benull
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 invalidNoSuchPrincipalException
- if the principal doesn't existInvalidOperationException
- if the principal is fixedUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
setEnabled
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 thelock(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 benull
enabled
- the new value for the enabled flag- Returns:
- the updated user
- Throws:
NoSuchPrincipalException
- if the user doesn't existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
unlock
public abstract UserPrincipal unlock(UserPrincipal user) throws NoSuchPrincipalException, UserDirectoryException Unlocks the given user.- Parameters:
user
- the user to unlock, must not benull
- Returns:
- the updated user
- Throws:
NoSuchPrincipalException
- if the user doesn't existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
- See Also:
-
lock
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 thesetEnabled(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 benull
time
- the time for which the user should be locked, must be greater than0
unit
- the time unit of thetime
argument, must not benull
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 existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
- See Also:
-
setPassword
public abstract void setPassword(UserPrincipal user, String password) throws InvalidPasswordException, NoSuchPrincipalException, UserDirectoryException Sets the password for the given user. If the password isnull
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 benull
password
- the new password, may benull
but must not be an empty string- Throws:
InvalidPasswordException
- if the password invalidNoSuchPrincipalException
- if the user doesn't existInvalidOperationException
- if the user is fixedUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
deletePrincipal
Deletes the given principal (user or group), if it exists. Returnstrue
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 benull
- Returns:
true
if a change was made as a result of this call, andfalse
otherwise- Throws:
InvalidOperationException
- if the principal is fixedUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
deletePrincipals
public abstract boolean deletePrincipals(Collection<? extends SpotfirePrincipal> principals) throws UserDirectoryException Deletes the given principals (users or groups), if they exist. Returnstrue
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 benull
- Returns:
true
if a change was made as a result of this call, andfalse
otherwise- Throws:
InvalidOperationException
- if any of the principals are fixedUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
getParentGroups
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 benull
- Returns:
- a possibly empty set of all groups that the given principal is an immediate member of
- Throws:
NoSuchPrincipalException
- if the principal doesn't existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
setParentGroups
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 benull
groups
- a possibly empty collection of groups that the principal should be an immediate member of, must not benull
- Throws:
NoSuchPrincipalException
- if the principal or any of the group principals doesn't existInvalidArgumentException
- 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 immutableUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
getAncestorGroups
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 benull
- 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 existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
isMember
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 benull
principal
- the principal to determine membership for, must not benull
- Returns:
true
if the given principal is a member of the given group andfalse
otherwise- Throws:
NoSuchPrincipalException
- if the group or the principal doesn't existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
getMembers
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 benull
- Returns:
- a possibly empty set of all immediate members of the group
- Throws:
NoSuchPrincipalException
- if the group doesn't existUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
setMembers
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 benull
principals
- a possibly empty collection of principals that should be set as members of the group, must not benull
- Throws:
NoSuchPrincipalException
- if the group or any of the member principals doesn't existInvalidArgumentException
- 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 immutableUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
addMember
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 benull
principal
- the principal that should be added to the group, must not benull
- Throws:
NoSuchPrincipalException
- if the group or the member principal doesn't existInvalidArgumentException
- 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 immutableUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
addMembers
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 benull
principals
- a possibly empty collection of principals that should be added to the group, must not benull
- Throws:
NoSuchPrincipalException
- if the group or any of the member principals doesn't existInvalidArgumentException
- 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 immutableUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
removeMember
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. Returnstrue
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 benull
principal
- the principal that should be removed from the group, must not benull
- Returns:
true
if a change was made as a result of this call, andfalse
otherwise- Throws:
NoSuchPrincipalException
- if the group or the member principal doesn't existInvalidOperationException
- if the group is immutableUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-
removeMembers
public abstract boolean removeMembers(GroupPrincipal group, Collection<? extends SpotfirePrincipal> principals) throws NoSuchPrincipalException, UserDirectoryException Removes the given principals (users or groups) from the given group. Returnstrue
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 benull
principals
- a possibly empty collection of principals that should be removed from the group, must not benull
- Returns:
true
if a change was made as a result of this call, andfalse
otherwise- Throws:
NoSuchPrincipalException
- if the group or any of the member principals doesn't existInvalidOperationException
- if the group is immutableUserDirectoryException
- if an unexpected error occurs- Since:
- 10.1
-