com.sssw.fw.directory.api
Interface EbiDirectoryManager

All Superinterfaces:

EbiRealm, EbiWriteableRealm

public interface EbiDirectoryManager

extends EbiWriteableRealm

The directory manager provides access to user and group repositories, as well as authentication functionality. The directory manager manages a realm that provides read access to a user and group repository

Method Summary

Principal	authUserPassword(EbiContext context, String realm, String user, String password) Authenticates a user with specified userid, password, and realm name.
EbiRealmUser	convertPrincipal(EbiContext context, Principal princ) Converts an app server principal to EbiRealmUser/EbiRealmGroup.
void	flushCache(EbiContext context, String realm) Flushes both group and user caches in the directory service.
void	flushGroupCache(EbiContext context, String realm) Flushes the group caches.
void	flushUserCache(EbiContext context, String realm) Flushes the user caches.
void	flushUserInCache(EbiContext ctx, String realm, String username) Flushes the specified user from the specified realm cache.
Collection	getAncestorContainers(EbiContext context, EbiRealmPrincipal prin) Enumerates any ancestors, all the way up to the Root Realm Container, of the specified container.
Principal	getAnonymous(String realm) Returns the "anonymous" principal from the specified realm
Principal	getAuthenticatedUser(EbiContext context, String realm) Returns the authenticated user from the session or request using the specified realm
Collection	getChildren(EbiContext context, EbiRealmContainer container, boolean getSubcontainers, boolean getUsers) Enumerates the child objects (immediate descendants) of a specific Realm Container.
Collection	getConfiguredRealms() Retrieves a Collection of realm names from the DirectoryService.
Collection	getDescendants(EbiContext context, EbiRealmContainer container, boolean getSubcontainers, boolean getUsers) Enumerates the descendant objects of a specific Realm Container.
EbiRealmUser	getEbiRealmUser(EbiContext context, String username, String uniqueID, String userType) Creates an EbiRealmUser/EbiRealmGroup principal.
Group	getGroup(EbiContext context, String realm, String name) Returns a group principal for the specified group principal name from the specified realm.
Collection	getGroupMembershipList(EbiContext context, String realm, Principal userPrinc) Returns a collection of groups for the specified user principal from the specified realm.
Collection	getGroupMembershipList(EbiContext context, String realm, String user) Returns a collection of groups for the specified user from the specified realm.
Collection	getGroups(EbiContext context, int beginIndex, int endIndex) Returns a collection of group principals that fall within the specified range from the combined set of realm groups.
Collection	getGroups(EbiContext context, String realm) Returns a collection of groups from the specified realm.
String	getManagerName() Returns the manager name.
EbiRealmContainer	getParentContainer(EbiContext context, EbiRealmPrincipal prin) Gets the parent container for a specific Realm Container.
String	getPrimaryRealmName() Gets the name of the primary realm.
EbiRealmContainer	getRealmContainer(EbiContext context, String name) Gets a Realm Container, given its distinguished name.
Collection	getRealmGroups(EbiContext context, String realm) Gets the groups from a specified realm that do not have parent groups.
EbiRealmUser	getRealmUser(EbiContext context, String name) Gets a Realm User, given the user's distinguished name.
EbiRealmContainer	getRootContainer(EbiContext context) Gets the Root Container within the directory hierarchy.
int	getTotalGroups(EbiContext context) Returns the total number of groups from the configured realms.
int	getTotalGroups(EbiContext context, String realm) Returns the total number of groups from the specified realm.
int	getTotalUsers(EbiContext context) Returns the total number of users from the configured realms.
int	getTotalUsers(EbiContext context, String realm) Returns the total number of users from the specified realm.
Principal	getUser(EbiContext context, String realm, String name) Returns a user principal for the specified principal name from the specified realm.
Collection	getUsers(EbiContext context, int beginIndex, int endIndex) Returns a collection of user principals that fall within the specified range from the combined set of realm users.
Collection	getUsers(EbiContext context, String realm) Returns a collection of user principals from the specified realm.
boolean	isAnonymous(Principal princ, String realm) Checks to see if a principal is "anonymous" in the specified realm.
boolean	isContainerSupported(String realm) Checks to see if directory containers are supported by the specified realm.
boolean	isDescendant(EbiContext context, EbiRealmContainer container, Principal prin) Checks to see if the specified principal is a descendant of the specified Realm Container.
boolean	isDynamicGroupSupported(String realm) Checks to see if the realm supports dynamic groups.
boolean	isGroupQuerySupported(String realm) Checks to see if the realm supports group queries.
boolean	isNestedGroupSupported(String realm) Checks to see if the realm supports nested groups.
boolean	isUserQuerySupported(String realm) Checks to see if the realm supports user queries.
boolean	isValidUserID(String realm, String userID) Checks to see if the specified user ID contains valid characters for the specified realm.
boolean	isWriteableRealm(String realm) Tests to see if the realm specified by a realm name is configured as the writeable realm
void	logoff(EbiContext context, String realm) Logs off the current user from the session

Methods implemented from interface com.sssw.fw.directory.api.EbiWriteableRealm

addGroup, addUser, removeGroup, removeUser

Methods implemented from interface com.sssw.fw.directory.api.EbiRealm

authUserPassword, getAnonymous, getAuthenticatedUser, getChildGroups, getEbiRealmUserByUniqueID, getEbiRealmUsersByUniqueIDs, getGroup, getGroupMembershipList, getGroups, getGroups, getParentGroups, getRealmGroups, getRealmName, getUser, getUsers, getUsers, isAnonymous, isContainerSupported, isDynamicGroupSupported, isGroupQuerySupported, isNestedGroupSupported, isUserQuerySupported, isValidUserID, logoff

Method Detail

getUsers

public Collection getUsers(EbiContext context,
                           String realm)
                    throws EboException

Returns a collection of user principals from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

Returns:

a collection of user principals of type EbiRealmUser from the specified realm.

getUsers

public Collection getUsers(EbiContext context,
                           int beginIndex,
                           int endIndex)
                    throws EboException

Returns a collection of user principals that fall within the specified range from the combined set of realm users.

Parameters:

context - an EbiContext object.

beginIndex - the start index in the range of users to retrieve (inclusive)

endIndex - the end index in the range of users to retrieve (inclusive)

Returns:

a collection of user principals of type EbiRealmUser from the specified realm.

getUser

public Principal getUser(EbiContext context,
                         String realm,
                         String name)
                  throws EboException

Returns a user principal for the specified principal name from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

name - a principal name.

Returns:

a Principal from the specified realm and principal name.

getGroups

public Collection getGroups(EbiContext context,
                            String realm)
                     throws EboException

Returns a collection of groups from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

Returns:

a collection of groups of type EbiRealmGroup for for the specified realm.

getTotalGroups

public int getTotalGroups(EbiContext context,
                          String realm)
                   throws EboException

Returns the total number of groups from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

Returns:

an integer representing the total number of groups for the specified realm.

getTotalGroups

public int getTotalGroups(EbiContext context)
                   throws EboException

Returns the total number of groups from the configured realms.

Parameters:

context - an EbiContext object.

Returns:

an integer representing the total number of groups for the configured realms.

getTotalUsers

public int getTotalUsers(EbiContext context,
                         String realm)
                  throws EboException

Returns the total number of users from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

Returns:

an integer representing the total number of users for the specified realm.

getTotalUsers

public int getTotalUsers(EbiContext context)
                  throws EboException

Returns the total number of users from the configured realms.

Parameters:

context - an EbiContext object.

Returns:

an integer representing the total number of users for the configured realms.

getGroups

public Collection getGroups(EbiContext context,
                            int beginIndex,
                            int endIndex)
                     throws EboException

Returns a collection of group principals that fall within the specified range from the combined set of realm groups.

Parameters:

context - an EbiContext object.

beginIndex - the start index in the range of groups to retrieve (inclusive)

endIndex - the end index in the range of groups to retrieve (inclusive)

Returns:

a collection of groups of type EbiRealmGroup for the specified realm.

getGroup

public Group getGroup(EbiContext context,
                      String realm,
                      String name)
               throws EboException

Returns a group principal for the specified group principal name from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

name - a group principal name.

Returns:

a group principal for the specified group principal name from the specified realm.

getGroupMembershipList

public Collection getGroupMembershipList(EbiContext context,
                                         String realm,
                                         Principal userPrinc)
                                  throws EboException

Returns a collection of groups for the specified user principal from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

userPrinc - a user principal.

Returns:

a collection of groups of type EbiRealmGroup for the specified user principal from the specified realm.

getGroupMembershipList

public Collection getGroupMembershipList(EbiContext context,
                                         String realm,
                                         String user)
                                  throws EboException

Returns a collection of groups for the specified user from the specified realm.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

user - a user name.

Returns:

a collection of groups of type EbiRealmGroup for the specified user principal from the specified realm.

authUserPassword

public Principal authUserPassword(EbiContext context,
                                  String realm,
                                  String user,
                                  String password)
                           throws EboUnrecoverableSystemException,
                                  EboSecurityException

Authenticates a user with specified userid, password, and realm name.

Parameters:

context - an EbiContext object.

realm - a name for the specified realm.

user - an user identifier.

password - a user password.

Returns:

a user Principal if authentication succeeded, else return null.

convertPrincipal

public EbiRealmUser convertPrincipal(EbiContext context,
                                     Principal princ)
                              throws EboException

Converts an app server principal to EbiRealmUser/EbiRealmGroup.

Parameters:

context - an EbiContext object.

princ - an app server principal.

Returns:

an EbiRealmUser/EbiRealmGroup principal.

getEbiRealmUser

public EbiRealmUser getEbiRealmUser(EbiContext context,
                                    String username,
                                    String uniqueID,
                                    String userType)

Creates an EbiRealmUser/EbiRealmGroup principal.

Parameters:

context - an EbiContext object.

username - a principal name.

uniqueID - a unique identifier for the principal.

userType - whether it is a user or group principal.

Returns:

an EbiRealmUser/EbiReamGroup principal.

getManagerName

public String getManagerName()

Returns the manager name.

Returns:

the manager name.

getConfiguredRealms

public Collection getConfiguredRealms()

Retrieves a Collection of realm names from the DirectoryService. Currently the DirectoryService allows at most two realms to exist, a readable realm and a writeable realm

Returns:

a collection of realm names of type String.

isWriteableRealm

public boolean isWriteableRealm(String realm)

Tests to see if the realm specified by a realm name is configured as the writeable realm

Parameters:

realm - the name of a realm to be checked

Returns:

true if the realm is configured as the writeable realm, false otherwise

getPrimaryRealmName

public String getPrimaryRealmName()

Gets the name of the primary realm.

Returns:

the name of the primary realm.

isAnonymous

public boolean isAnonymous(Principal princ,
                           String realm)
                    throws EboException

Checks to see if a principal is "anonymous" in the specified realm.

Parameters:

princ - the principal to check

realm - the realm name for the specified realm to check

Returns:

true if the specified principal is "anonymous" in the specified realm, false otherwise

getAnonymous

public Principal getAnonymous(String realm)
                       throws EboException

Returns the "anonymous" principal from the specified realm

Returns:

the principal object that represent an "anonymous" user in the specified realm

getRealmGroups

public Collection getRealmGroups(EbiContext context,
                                 String realm)
                          throws EboException

Gets the groups from a specified realm that do not have parent groups.

Parameters:

context - an EbiContext object.

realm - name of the specified realm, if null, primary realm is used.

Returns:

a collection of groups of type EbiRealmGroup that do not have parent groups. If the specified realm doesn't support nested groups, the returned collection will contain all groups managed by the realm.

isNestedGroupSupported

public boolean isNestedGroupSupported(String realm)

Checks to see if the realm supports nested groups.

Parameters:

realm - name of the specified realm, if null, primary realm is used.

Returns:

true if the realm supports nested groups, false otherwise.

isGroupQuerySupported

public boolean isGroupQuerySupported(String realm)

Checks to see if the realm supports group queries. Group queries provide for retrieval of selected groups.

Parameters:

realm - name of the specified realm, if null, primary realm is used.

Returns:

true if the realm supports group queries, false otherwise.

isUserQuerySupported

public boolean isUserQuerySupported(String realm)

Checks to see if the realm supports user queries. User queries provide for retrieval of selected users.

Parameters:

realm - name of the specified realm, if null, primary realm is used.

Returns:

true if the realm supports group queries, false otherwise.

isDynamicGroupSupported

public boolean isDynamicGroupSupported(String realm)

Checks to see if the realm supports dynamic groups. Dynamic groups utilize queries to determine group membership.

Parameters:

realm - name of the specified realm, if null, primary realm is used.

Returns:

true if the realm supports dynamic groups, false otherwise.

flushCache

public void flushCache(EbiContext context,
                       String realm)
                throws EboException

Flushes both group and user caches in the directory service. If realm provided is null, it flushes caches in all realms configured in the directory service.

Parameters:

context - an EbiContext object.

realm - name of the specified realm.

flushGroupCache

public void flushGroupCache(EbiContext context,
                            String realm)
                     throws EboException

Flushes the group caches. If realm provided is null, it flushes the user caches for all realms configured in the directory service.

Parameters:

context - an EbiContext object.

realm - name of the specified realm.

flushUserCache

public void flushUserCache(EbiContext context,
                           String realm)
                    throws EboException

Flushes the user caches. If realm provided is null, it flushes the user caches for all realms configured in the directory service.

Parameters:

context - an EbiContext object.

realm - name of the specified realm.

flushUserInCache

public void flushUserInCache(EbiContext ctx,
                             String realm,
                             String username)
                      throws EboException

Flushes the specified user from the specified realm cache. If the realm provided is null, it flushes the user from all the realm caches configured in the directory service.

Parameters:

context - an EbiContext object.

realm - name of the specified realm.

username - name of the user to flush

logoff

public void logoff(EbiContext context,
                   String realm)
            throws EboException

Logs off the current user from the session

Parameters:

context - an EbiContext

realm - name of the specified realm

getAuthenticatedUser

public Principal getAuthenticatedUser(EbiContext context,
                                      String realm)
                               throws EboException

Returns the authenticated user from the session or request using the specified realm

Parameters:

context - an EbiContext

realm - name of the realm

isContainerSupported

public boolean isContainerSupported(String realm)

Checks to see if directory containers are supported by the specified realm.

Parameters:

realm - the name of the realm to check; if null, then the primary realm is used

Returns:

true if the realm supports containers, false otherwise.

getRootContainer

public EbiRealmContainer getRootContainer(EbiContext context)
                                   throws EboUnrecoverableSystemException

Gets the Root Container within the directory hierarchy.

Parameters:

context - context

Returns:

the Root Container object

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

getChildren

public Collection getChildren(EbiContext context,
                              EbiRealmContainer container,
                              boolean getSubcontainers,
                              boolean getUsers)
                       throws EboUnrecoverableSystemException

Enumerates the child objects (immediate descendants) of a specific Realm Container.

Parameters:

context - context

container - the parent Realm Container

getSubcontainers - if true, any child containers are included in the returned results

getUsers - if true, any users are included in the returned results

Returns:

a Collection of EbiRealmPrincipal's (EbiRealmContainer's and/or EbiRealmUser's)

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

getDescendants

public Collection getDescendants(EbiContext context,
                                 EbiRealmContainer container,
                                 boolean getSubcontainers,
                                 boolean getUsers)
                          throws EboUnrecoverableSystemException

Enumerates the descendant objects of a specific Realm Container.

Parameters:

context - context

container - the ancestor Realm Container

getSubcontainers - if true, any descendant containers are included in the returned results

getUsers - if true, any users are included in the returned results

Returns:

a Collection of EbiRealmPrincipal's (EbiRealmContainer's and/or EbiRealmUser's)

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

getParentContainer

public EbiRealmContainer getParentContainer(EbiContext context,
                                            EbiRealmPrincipal prin)
                                     throws EboUnrecoverableSystemException

Gets the parent container for a specific Realm Container.

Parameters:

context - context

container - the Realm Principal whose parent is to be retrieved

Returns:

the parent Realm Container or null if the root container is passed in

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

getRealmContainer

public EbiRealmContainer getRealmContainer(EbiContext context,
                                           String name)
                                    throws EboUnrecoverableSystemException

Gets a Realm Container, given its distinguished name.

Parameters:

context - context

name - the distinguished name of the container

Returns:

the Realm Container or null if not found

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

getRealmUser

public EbiRealmUser getRealmUser(EbiContext context,
                                 String name)
                          throws EboUnrecoverableSystemException

Gets a Realm User, given the user's distinguished name.

Parameters:

context - context

name - the user's distinguished name

Returns:

the Realm User object, or null of the user was not found

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

isDescendant

public boolean isDescendant(EbiContext context,
                            EbiRealmContainer container,
                            Principal prin)
                     throws EboUnrecoverableSystemException

Checks to see if the specified principal is a descendant of the specified Realm Container.

Parameters:

context - context

container - the parent Realm Container

prin - the principal

Returns:

true if the principal is a descendant of the container, false otherwise

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

getAncestorContainers

public Collection getAncestorContainers(EbiContext context,
                                        EbiRealmPrincipal prin)
                                 throws EboUnrecoverableSystemException

Enumerates any ancestors, all the way up to the Root Realm Container, of the specified container.

Parameters:

context - context

prin - the Realm Principal whose ancestors are to be enumerated

Returns:

a Collection of EbiRealmContainer's; the Collection is empty if the Root Realm Container is passed in

Throws:

EboUnrecoverableSystemException - on an unrecoverable system exception

isValidUserID

public boolean isValidUserID(String realm,
                             String userID)

Checks to see if the specified user ID contains valid characters for the specified realm.

Parameters:

realm - the specified realm

Returns:

true if the user ID contains valid characters, false otherwise.