com.spotfire.server.userdir
Interface UserDirectory

public interface UserDirectory

This interface provides functionality to list and modify users and groups in DS Server.

Since:

DSS 7.3

Field Summary

static int	OPERATION_READ_GROUPS Constant specifying the operation of reading groups.
static int	OPERATION_READ_USERS Constant specifying the operation of reading users.
static int	OPERATION_WRITE_GROUPS Constant specifying the operation of writing groups.
static int	OPERATION_WRITE_USERS Constant specifying the operation of writing users.
static int	SERVICE_PROVIDER_ALL Constant specifying the internal and external service providers.
static int	SERVICE_PROVIDER_EXTERNAL Constant specifying the external service provider.
static int	SERVICE_PROVIDER_INTERNAL Constant specifying the internal service provider

Method Summary

void	addMember(GroupPrincipal group, SpotfirePrincipal principal) Adds a member to a group principal in the directory.
GroupPrincipal	createGroupPrincipal(String name) Creates a new group principal in the directory.
UserPrincipal	createUserPrincipal(String name, String password) Creates a new user principal in the directory.
GroupPrincipal	getAdministratorGroup() Returns the administrator group principal.
GroupPrincipal[]	getDefaultGroups() Returns an array containing the default groups on the server.
GroupPrincipal	getGroupPrincipal(String name) Returns the group principal with the specified name from the directory.
GroupPrincipal[]	getGroupPrincipals() Returns an array containing all group principals in the directory.
GroupPrincipal[]	getGroupPrincipals(String regExp) Returns an array containing all group principals with names that matches the given regular expression.
GroupPrincipal[]	getGroups(SpotfirePrincipal principal) Returns an array containing all groups of which the specified principal is an immediate member.
GroupPrincipal[]	getImmutableGroups() Returns an array containing all immutable groups on the server.
SpotfirePrincipal[]	getMembers(GroupPrincipal group) Returns an array containing all immediate members (both users and other groups) of a group in the directory.
GroupPrincipal	getPrimaryGroup(SpotfirePrincipal principal) Returns the specified principal's primary group.
SpotfirePrincipal	getPrincipal(Guid guid) Returns the principal with the specified GUID from the directory.
UserPrincipal	getUserPrincipal(String name) Returns the user principal with the specified name from the directory.
UserPrincipal[]	getUserPrincipals() Returns an array containing all user principals in the directory.
UserPrincipal[]	getUserPrincipals(String regExp) Returns an array containing all user principals with names that matches the given regular expression.
boolean	isAdministrator(UserPrincipal user)
boolean	isDefaultGroup(GroupPrincipal group)
boolean	isImmutableGroup(GroupPrincipal group)
boolean	isMember(GroupPrincipal group, SpotfirePrincipal principal) Check if a principal is member of a group.
boolean	isOperationSupported(int operation, int serviceProvider) Check if an operation is supported by the user directory or not.
void	removeMember(GroupPrincipal group, SpotfirePrincipal principal) Removes a member from a group in the directory.
void	removePrincipal(SpotfirePrincipal principal) Removes a principal from the directory.
void	renamePrincipal(SpotfirePrincipal principal, String name) Changes the name of a principal in the directory.
void	setGroups(SpotfirePrincipal principal, GroupPrincipal[] groups) Set all groups that a principal belongs to.
void	setMembers(GroupPrincipal group, SpotfirePrincipal[] principals) Sets all members of a group.
void	setPassword(UserPrincipal user, String password) Changes the password for a user
void	setPrimaryGroup(SpotfirePrincipal principal, GroupPrincipal primaryGroup) Sets the primary group for the specified principal.

Field Detail

OPERATION_READ_USERS

static final int OPERATION_READ_USERS

Constant specifying the operation of reading users.

See Also:

Constant Field Values

OPERATION_WRITE_USERS

static final int OPERATION_WRITE_USERS

Constant specifying the operation of writing users.

See Also:

Constant Field Values

OPERATION_READ_GROUPS

static final int OPERATION_READ_GROUPS

Constant specifying the operation of reading groups.

See Also:

Constant Field Values

OPERATION_WRITE_GROUPS

static final int OPERATION_WRITE_GROUPS

Constant specifying the operation of writing groups.

See Also:

Constant Field Values

SERVICE_PROVIDER_INTERNAL

static final int SERVICE_PROVIDER_INTERNAL

Constant specifying the internal service provider

See Also:

Constant Field Values

SERVICE_PROVIDER_EXTERNAL

static final int SERVICE_PROVIDER_EXTERNAL

Constant specifying the external service provider.

See Also:

Constant Field Values

SERVICE_PROVIDER_ALL

static final int SERVICE_PROVIDER_ALL

Constant specifying the internal and external service providers.

See Also:

Constant Field Values

Method Detail

getUserPrincipal

UserPrincipal getUserPrincipal(String name)

Returns the user principal with the specified name from the directory.

Parameters:

name - the name of the user

Returns:

a UserPrincipal if the directory contains a user with the given name, or null if such a user does not exist

Throws:

UserDirectoryException - if an error occurred in the service provider

getGroupPrincipal

GroupPrincipal getGroupPrincipal(String name)

Returns the group principal with the specified name from the directory.

Parameters:

name - the name of the group

Returns:

a GroupPrincipal if the directory contains a group with the given name, or null if such a group does not exist

Throws:

UserDirectoryException - if an error occurred in the service provider

getPrincipal

SpotfirePrincipal getPrincipal(Guid guid)

Returns the principal with the specified GUID from the directory.

Parameters:

guid - the GUID of the principal

Returns:

a UserPrincipal or a GroupPrincipal if the directory contains a principal with the given GUID, or null if such a principal does not exist

Throws:

UserDirectoryException - if an error occurred in the service provider

getUserPrincipals

UserPrincipal[] getUserPrincipals()

Returns an array containing all user principals in the directory.

Returns:

an array containing all user principals

Throws:

UserDirectoryException - if an error occurred in the service provider

getUserPrincipals

UserPrincipal[] getUserPrincipals(String regExp)

Returns an array containing all user principals with names that matches the given regular expression.

Parameters:

regExp - a regular expression This follows the syntax of java.util.regex.Pattern in jdk 1.4

Returns:

an array containing all user principals with matching names

Throws:

IllegalArgumentException - if the given regular expression is invalid

UserDirectoryException - if an error occurred in the service provider

getGroupPrincipals

GroupPrincipal[] getGroupPrincipals()

Returns an array containing all group principals in the directory.

Returns:

an array containing all group principals

Throws:

UserDirectoryException - if an error occurred in the service provider

getGroupPrincipals

GroupPrincipal[] getGroupPrincipals(String regExp)

Returns an array containing all group principals with names that matches the given regular expression.

Parameters:

regExp - a regular expression. This follows the syntax of java.util.regex.Pattern in jdk 1.4

Returns:

an array containing all group principals with matching names

Throws:

IllegalArgumentException - if the given regular expression is invalid

UserDirectoryException - if an error occurred in the service provider

getMembers

SpotfirePrincipal[] getMembers(GroupPrincipal group)

Returns an array containing all immediate members (both users and other groups) of a group in the directory. The method is not recursive and does not expand subgroups.

Parameters:

group - a group principal

Returns:

a SpotfirePrincipal array containing all immediate group members. Each can be either a UserPrincipal or a GroupPrincipal object.

Throws:

NoSuchPrincipalException - if the given group cannot be found in the directory

UserDirectoryException - if an error occurred in the service provider

isMember

boolean isMember(GroupPrincipal group,
                 SpotfirePrincipal principal)

Check if a principal is member of a group. This method is recursive and will check inherited groups.

Parameters:

group - a group principal

principal - the principal to check membership for

Returns:

true if the given principal is a member of the group, otherwise false

Throws:

NoSuchPrincipalException - if the given group or principal cannot be found in the directory

UserDirectoryException - if an error occurred in the service provider

getGroups

GroupPrincipal[] getGroups(SpotfirePrincipal principal)

Returns an array containing all groups of which the specified principal is an immediate member. The method is not recursive and does not return inherited groups.

Parameters:

principal - the principal to retrieve groups for

Returns:

an array containing all group principals of which the given principal is an immediate member

Throws:

NoSuchPrincipalException - if the given principal cannot be found in the directory

UserDirectoryException - if an error occurred in the service provider

getDefaultGroups

GroupPrincipal[] getDefaultGroups()

Returns an array containing the default groups on the server. The default groups are automatically created during installation and must always exist.

Returns:

an array containing the default group principals

Throws:

UserDirectoryException - if an error occurred in the service provider

getImmutableGroups

GroupPrincipal[] getImmutableGroups()

Returns an array containing all immutable groups on the server. The immutable groups cannot be modified.

Returns:

an array containing the immutable group principals

Throws:

UserDirectoryException - if an error occurred in the service provider

isImmutableGroup

boolean isImmutableGroup(GroupPrincipal group)

isDefaultGroup

boolean isDefaultGroup(GroupPrincipal group)

isAdministrator

boolean isAdministrator(UserPrincipal user)

getAdministratorGroup

GroupPrincipal getAdministratorGroup()

Returns the administrator group principal.

Returns:

the administrator group principal

Throws:

UserDirectoryException - if an error occurred in the service provider

createUserPrincipal

UserPrincipal createUserPrincipal(String name,
                                  String password)

Creates a new user principal in the directory.

Parameters:

name - the name of the user principal to be created

password - the password for the user principal to be created

Returns:

the created user principal

Throws:

PrincipalAlreadyExistsException - if a principal with the specified name already exists in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support creating user principals.

UserDirectoryException - if an error occurred in the service provider

setPassword

void setPassword(UserPrincipal user,
                 String password)

Changes the password for a user

Parameters:

user - the user whos password to change

password - the new password

Throws:

NoSuchPrincipalException - if the given user principal cannot be found in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support modifying passwords.

createGroupPrincipal

GroupPrincipal createGroupPrincipal(String name)

Creates a new group principal in the directory.

Parameters:

name - the name of the group principal to be created

Returns:

the created group principal

Throws:

PrincipalAlreadyExistsException - if a principal with the specified name already exists in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support creating group principals.

UserDirectoryException - if an error occurred in the service provider

removePrincipal

void removePrincipal(SpotfirePrincipal principal)

Removes a principal from the directory.

Parameters:

principal - the principal to be removed

Throws:

NoSuchPrincipalException - if the given principal cannot be found in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support removing principals.

UserDirectoryException - if an error occurred in the service provider

renamePrincipal

void renamePrincipal(SpotfirePrincipal principal,
                     String name)

Changes the name of a principal in the directory.

Parameters:

principal - the principal to change the name for

name - the new name

Throws:

NoSuchPrincipalException - if the given principal cannot be found in the directory

PrincipalAlreadyExistsException - if a principal with the specified name already exists in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support renaming principals.

UserDirectoryException - if an error occurred in the service provider

addMember

void addMember(GroupPrincipal group,
               SpotfirePrincipal principal)

Adds a member to a group principal in the directory.

Parameters:

group - the group principal to add a member to

principal - the principal to be added as a member

Throws:

NoSuchPrincipalException - if the group or the principal cannot be found in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support modifying group principals.

UserDirectoryException - if an error occurred in the service provider

removeMember

void removeMember(GroupPrincipal group,
                  SpotfirePrincipal principal)

Removes a member from a group in the directory. Does nothing if the principal is not a member of the group.

Parameters:

group - the group principal to remove a member from

principal - the principal to be removed as a member

Throws:

NoSuchPrincipalException - if any of the given principals cannot be found in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support modifying group principals.

UserDirectoryException - if an error occurred in the service provider

setMembers

void setMembers(GroupPrincipal group,
                SpotfirePrincipal[] principals)

Sets all members of a group. This method will remove all previous members of the group before adding the new members.

Parameters:

group - the group principal to set members for

principals - the new group members

Throws:

NoSuchPrincipalException - if any of the given principals cannot be found in the directory

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support modifying group principals.

UserDirectoryException - if an error occurred in the service provider

setGroups

void setGroups(SpotfirePrincipal principal,
               GroupPrincipal[] groups)

Set all groups that a principal belongs to. This method will remove all previous groups of the principal.

Parameters:

principal -

groups -

Throws:

NoSuchPrincipalException - if the principal or any of the group principals cannot be found in the directory.

ReadOnlyDirectoryException - if the directory is configured with a service provider that does not support modifying group principals.

UserDirectoryException - if an error occurred in the underlying system

getPrimaryGroup

GroupPrincipal getPrimaryGroup(SpotfirePrincipal principal)

Returns the specified principal's primary group.

Parameters:

principal - the principal whose primary group should be return

Returns:

the principal's primary group

setPrimaryGroup

void setPrimaryGroup(SpotfirePrincipal principal,
                     GroupPrincipal primaryGroup)

Sets the primary group for the specified principal. The principal must already be a direct member of the primary group. This method will overwrite any previous primary group. To delete a primary group association, call this method with the primaryGroup argument set to null.

Parameters:

principal - the principal to set the primary group for

primaryGroup - the principal's primary group

Throws:

InvalidPrimaryGroupException - if the specified primary group is invalid

isOperationSupported

boolean isOperationSupported(int operation,
                             int serviceProvider)

Check if an operation is supported by the user directory or not.

Parameters:

operation - UserDirectory.OPERATION_READ_USERS, UserDirectory.OPERATION_WRITE_USERS, UserDirectory.OPERATION_READ_GROUPS or UserDirectory.OPERATION_WRITE_GROUPS.

serviceProvider - UserDirectory.SERVICE_PROVIDER_INTERNAL, UserDirectory.SERVICE_PROVIDER_EXTERNAL or UserDirectory.SERVICE_PROVIDER_ALL.

Returns:

true if the operation is supported, false otherwise.