com.sssw.fw.directory.api
Interface EbiDirectoryDelegate

All Superinterfaces:

EbiDelegate

public interface EbiDirectoryDelegate

extends EbiDelegate

The directory delegate is provided as a facade for accessing user and group principals either through the local directory manager or through the remote directory service EJB

Fields inherited from interface com.sssw.fw.api.EbiDelegate

SERVICE_LOCAL, SERVICE_REMOTE

Method Summary

void	addGroup(EbiContext context, String groupname) Adds a group to the writable realm.
void	addUser(EbiContext context, String username, String password) Adds a user to the writable realm.
Principal	authUserPassword(EbiContext context, String user, String password) Authenticates a user with specified userid, and password.
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 the group/user caches in realm cache.
void	flushGroupCache(EbiContext context, String realm) Flushes the group caches in realm cache.
void	flushUserCache(EbiContext context, String realm) Flushes the user caches in realm cache.
void	flushUserInCache(EbiContext ctx, String realm, String username) Flushes the specified user from the specified realm cache.
Principal	getAnonymous() Returns the "anonymous" principal from the primary realm
Principal	getAuthenticatedUser(EbiContext context) Returns the authenticated user from the session or request
Principal	getAuthenticatedUser(EbiContext context, String realm) Returns the authenticated user from the session or request using the specified realm
Collection	getConfiguredRealms() Retrieves a Collection of realm names from the DirectoryService.
EbiRealmUser	getEbiRealmUser(EbiContext context, String username, String uniqueID, String prinType) Creates an EbiRealmUser/EbiRealmGroup principal.
Principal	getEbiRealmUserByUniqueID(EbiContext context, String uniqueID, String prinType) Retrieves a Principal based on unique ID.
Collection	getEbiRealmUsersByUniqueIDs(EbiContext context, String[] uniqueIDs, String prinType) Retrieves a Collection of Principals based on unique IDs.
Group	getGroup(EbiContext context, String name) Returns a group principal for the specified group principal name (searches in the primary realm first, and if not found search the secondary realm if there is any.)
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, Principal userPrinc) Returns a collection of Groups that have the specified principal as a member.
Collection	getGroupMembershipList(EbiContext context, String realm, Principal userPrinc) Returns a collection of Groups for the specified user principal from the specified realm.
Collection	getGroups(EbiContext context) Returns a collection of Groups from the realms configured in the directory service..
Collection	getGroups(EbiContext context, EbiDirectoryGroupsQuery query) Returns a collection of Groups from the realms configured in the directory service.
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.
Collection	getGroups(EbiContext context, String realm, int beginIndex, int endIndex) Returns a collection of Groups that fall within the specified range from the specified realm.
String	getPrimaryRealmName() Gets the name of the primary realm.
Collection	getRealmGroups(EbiContext context) Gets a collection of groups from realms that do not have parent groups.
Collection	getRealmGroups(EbiContext context, String realm) Gets a collection of groups from a specified realm that do not have parent groups.
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 name) Returns a user principal for the specified principal name (searches in the primary realm first and if not found, search in the secondary realm if there is any configured in the directory service.)
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) Returns a collection of user principals from realms specified in the directory service.
Collection	getUsers(EbiContext context, EbiDirectoryUsersQuery query) Returns a collection of user principals from realms specified in the directory service.
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) Checks to see if a principal is "anonymous" in the realms.
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	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 userID) Checks to see if the specified user ID contains valid characters for the primary realm.
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) Logs off the current user from the session
void	logoff(EbiContext context, String realm) Logs off the current user from the session
void	removeGroup(EbiContext context, String groupname) Removes a group from the writable realm.
void	removeUser(EbiContext context, String username) Removes a user from the writeable realm.

Methods implemented from interface com.sssw.fw.api.EbiDelegate

getName

Method Detail

getUsers

public Collection getUsers(EbiContext context)
                    throws EboException

Returns a collection of user principals from realms specified in the directory service.

Parameters:

context - an EbiContext object.

Returns:

a collection of user principals of type EbiRealmUser from configured realms.

getUser

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

Returns a user principal for the specified principal name (searches in the primary realm first and if not found, search in the secondary realm if there is any configured in the directory service.)

Parameters:

context - an EbiContext object.

name - a principal name.

Returns:

a Principal of the specified principal name.

getGroups

public Collection getGroups(EbiContext context)
                     throws EboException

Returns a collection of Groups from the realms configured in the directory service..

Parameters:

context - an EbiContext object.

Returns:

a collection of groups of type EbiRealmGroup from the configured realms.

getGroup

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

Returns a group principal for the specified group principal name (searches in the primary realm first, and if not found search the secondary realm if there is any.)

Parameters:

context - an EbiContext object.

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,
                                         Principal userPrinc)
                                  throws EboException

Returns a collection of Groups that have the specified principal as a member.

Parameters:

context - an EbiContext object.

userPrinc - a user principal.

Returns:

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

authUserPassword

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

Authenticates a user with specified userid, and password. (Tries to authenticate to the primary realm first, and if failed to authenticate, try authenticate to the second realm if there is any specified in the directory service.

Parameters:

context - an EbiContext object.

user - an user identifier.

password - a user password.

Returns:

a user Principal if authentication succeeded, else return null.

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 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,
                            String realm,
                            int beginIndex,
                            int endIndex)
                     throws EboException

Returns a collection of Groups that fall within the specified range from the specified realm. Groups are sorted alphabetically (case-sensitive), by name.

Parameters:

context - an EbiContext object.

realm - a name of the specified realm.

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.

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. Groups are sorted alphabetically (case-sensitive), by name.

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.

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.

addUser

public void addUser(EbiContext context,
                    String username,
                    String password)
             throws EboException

Adds a user to the writable realm.

Parameters:

context - an EbiContext object.

username - the user name to be added.

password - the password for the user.

addGroup

public void addGroup(EbiContext context,
                     String groupname)
              throws EboException

Adds a group to the writable realm.

Parameters:

context - an EbiContext object.

groupname - the group name to be added.

removeUser

public void removeUser(EbiContext context,
                       String username)
                throws EboException

Removes a user from the writeable realm.

Parameters:

context - an EbiContext object.

username - the user name to be removed.

removeGroup

public void removeGroup(EbiContext context,
                        String groupname)
                 throws EboException

Removes a group from the writable realm.

Parameters:

context - an EbiContext object.

groupname - the group name to be removed.

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 prinType)
                             throws EboUnrecoverableSystemException

Creates an EbiRealmUser/EbiRealmGroup principal.

Parameters:

context - an EbiContext object.

username - a principal name.

uniqueID - a unique identifier for the principal.

prinType - whether it is a user,group,or container principal. A principal type can be FW_PRINCIPAL_USER, FW_PRINCIPAL_GROUP, or FW_PRINCIPAL_CONTAINER which is defined in com.sssw.fw.api.EbiConstants. For container principal, the uniqueID is expected to be the DN of the container.

Returns:

an EbiRealmUser/EbiReamGroup principal.

getEbiRealmUserByUniqueID

public Principal getEbiRealmUserByUniqueID(EbiContext context,
                                           String uniqueID,
                                           String prinType)
                                    throws EboException

Retrieves a Principal based on unique ID.

Parameters:

context - an EbiContext object.

uniqueID - a unique identifier for the principal.

prinType - whether it is a user,group,or container principal. A principal type can be FW_PRINCIPAL_USER, FW_PRINCIPAL_GROUP, or FW_PRINCIPAL_CONTAINER which is defined in com.sssw.fw.api.EbiConstants. For container principal, the uniqueID is expected to be the DN of the container.

Returns:

an EbiRealmUser principal.

getEbiRealmUsersByUniqueIDs

public Collection getEbiRealmUsersByUniqueIDs(EbiContext context,
                                              String[] uniqueIDs,
                                              String prinType)
                                       throws EboException

Retrieves a Collection of Principals based on unique IDs.

Parameters:

context - an EbiContext object.

uniqueID - an array of unique identifiers for the principal.

prinType - whether it is a user,group,or container principal. A principal type can be FW_PRINCIPAL_USER, FW_PRINCIPAL_GROUP, or FW_PRINCIPAL_CONTAINER which is defined in com.sssw.fw.api.EbiConstants. For container principal, the uniqueID is expected to be the DN of the container.

Returns:

a collection of principals of type Principal.

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

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)

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

Parameters:

princ - the principal to check

Returns:

true if the specified principal is "anonymous" in the realms false otherwise

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

Returns the "anonymous" principal from the primary realm

Returns:

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

getRealmGroups

public Collection getRealmGroups(EbiContext context)
                          throws EboException

Gets a collection of groups from realms that do not have parent groups.

Parameters:

context - an EbiContext object.

Returns:

a collection of groups of type EbiRealmGroup that do not have parent groups.

getRealmGroups

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

Gets a collection of 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 the group/user caches in realm cache.

Parameters:

context - an EbiContext object.

realm - name of the specified realm (if null, flush all realms)

flushGroupCache

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

Flushes the group caches in realm cache.

Parameters:

context - an EbiContext object.

realm - name of the specified realm (if null, flush all realms)

flushUserCache

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

Flushes the user caches in realm cache.

Parameters:

context - an EbiContext object.

realm - name of the specified realm (if null, flush all realms)

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)
            throws EboException

Logs off the current user from the session

Parameters:

context - an EbiContext

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)

Returns the authenticated user from the session or request

Parameters:

context - an EbiContext

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

getUsers

public Collection getUsers(EbiContext context,
                           EbiDirectoryUsersQuery query)
                    throws EboException

Returns a collection of user principals from realms specified in the directory service. A query object is used to filter the user list.

Parameters:

context - an EbiContext object.

query - an EbiDirectoryUsersQuery object.

Returns:

a collection of user principals of type EbiRealmUser from configured realms.

getGroups

public Collection getGroups(EbiContext context,
                            EbiDirectoryGroupsQuery query)
                     throws EboException

Returns a collection of Groups from the realms configured in the directory service. A query object is used to filter the group list.

Parameters:

context - an EbiContext object.

query - an EbiDirectoryGroupsQuery object.

Returns:

a collection of groups of type EbiRealmGroup from the configured realms.

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.

isValidUserID

public boolean isValidUserID(String userID)

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

Returns:

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

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.