org.sakaiproject.service.legacy.user
Interface UserDirectoryService

All Superinterfaces:
EntityProducer
All Known Implementing Classes:
BaseUserDirectoryService

public interface UserDirectoryService
extends EntityProducer

UserDirectory is the Interface for CHEF user directory services. Everything known about a user in CHEF is stored in the user directory (with the exception of the user's authentication password).

Each service component that provides this interface handles location of user information (objects following the User interface) based on a user id string (getUser()). They also handle adding new user objects into the directory and updating existing user objects.

Version:
$Revision: 5970 $
Author:
University of Michigan, CHEF Software Development Team
See Also:
org.chefproject.core.User

Nested Class Summary
 
Nested classes inherited from class org.sakaiproject.service.legacy.entity.EntityProducer
EntityProducer.ChangeType
 
Field Summary
static String REFERENCE_ROOT
          This string starts the references to resources in this service.
static String SECURE_ADD_USER
          Name for the event of adding a group.
static String SECURE_REMOVE_USER
          Name for the event of removing a user.
static String SECURE_UPDATE_USER_ANY
          Name for the event of updating any user info.
static String SECURE_UPDATE_USER_OWN
          Name for the event of updating one's own user info.
static String SERVICE_NAME
          This string can be used to find the service in the service manager.
 
Method Summary
 UserEdit addUser(String id)
          Add a new user to the directory.
 User addUser(String id, String firstName, String lastName, String email, String pw, String type, ResourceProperties properties)
          Add a new user to the directory, complete in one operation.
 boolean allowAddUser(String id)
          check permissions for addUser().
 boolean allowRemoveUser(String id)
          check permissions for removeUser().
 boolean allowUpdateUser(String id)
          check permissions for editUser()
 User authenticate(String id, String password)
          Authenticate a user / password.
 void cancelEdit(UserEdit user)
          Cancel the changes made to a UserEdit object, and release the lock.
 void commitEdit(UserEdit user)
          Commit the changes made to a UserEdit object, and release the lock.
 int countSearchUsers(String criteria)
          Count all the users that match this criteria in id or target, first or last name.
 int countUsers()
          Count all the users.
 void destroyAuthentication()
          Remove authentication for the current user.
 UserEdit editUser(String id)
          Get a locked user object for editing.
 Collection findUsersByEmail(String email)
          Find the user objects which have this email address.
 User getAnonymousUser()
          Access the anonymous user object.
 User getCurrentUser()
          Access the user object associated with the "current" request.
 User getUser(String id)
          Access a user object.
 User getUserByEid(String eid)
          Access a user object, given an enterprise id.
 List getUsers()
          Access all user objects - known to us (not from external providers).
 List getUsers(Collection ids)
          Access a bunch of user object.
 List getUsers(int first, int last)
          Find all the users within the record range given (sorted by sort name).
 UserEdit mergeUser(Element el)
          Add a new user to the directory, from a definition in XML.
 void removeUser(UserEdit user)
          Remove this user's information from the directory - it must be a user with a lock from editUser().
 List searchUsers(String criteria, int first, int last)
          Search all the users that match this criteria in id or email, first or last name, returning a subset of records within the record range given (sorted by sort name).
 String userReference(String id)
          Access the internal reference which can be used to access the resource from within the system.
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.EntityProducer
archive, getEntity, getEntityAuthzGroups, getEntityDescription, getEntityResourceProperties, getEntityUrl, getHttpAccess, getLabel, importEntities, merge, parseEntityReference, syncWithSiteChange, willArchiveMerge, willImport
 

Field Detail

SERVICE_NAME

public static final String SERVICE_NAME
This string can be used to find the service in the service manager.


REFERENCE_ROOT

public static final String REFERENCE_ROOT
This string starts the references to resources in this service.

See Also:
Constant Field Values

SECURE_ADD_USER

public static final String SECURE_ADD_USER
Name for the event of adding a group.

See Also:
Constant Field Values

SECURE_REMOVE_USER

public static final String SECURE_REMOVE_USER
Name for the event of removing a user.

See Also:
Constant Field Values

SECURE_UPDATE_USER_OWN

public static final String SECURE_UPDATE_USER_OWN
Name for the event of updating one's own user info.

See Also:
Constant Field Values

SECURE_UPDATE_USER_ANY

public static final String SECURE_UPDATE_USER_ANY
Name for the event of updating any user info.

See Also:
Constant Field Values
Method Detail

getUser

public User getUser(String id)
             throws IdUnusedException
Access a user object.

Parameters:
id - The user id string.
Returns:
A user object containing the user information
Throws:
IdUnusedException - if not found

getUserByEid

public User getUserByEid(String eid)
                  throws IdUnusedException
Access a user object, given an enterprise id.

Parameters:
eid - The user eid string.
Returns:
A user object containing the user information
Throws:
IdUnusedException - if not found

getUsers

public List getUsers(Collection ids)
Access a bunch of user object.

Parameters:
ids - The Collection (String) of user ids.
Returns:
A List (User) of user objects for valid ids.

getCurrentUser

public User getCurrentUser()
Access the user object associated with the "current" request.

Returns:
The current user (may be anon).

findUsersByEmail

public Collection findUsersByEmail(String email)
Find the user objects which have this email address.

Parameters:
email - The email address string.
Returns:
A Collection (User) of user objects which have this email address (may be empty).

allowUpdateUser

public boolean allowUpdateUser(String id)
check permissions for editUser()

Parameters:
id - The user id.
Returns:
true if the user is allowed to update the user, false if not.

editUser

public UserEdit editUser(String id)
                  throws IdUnusedException,
                         PermissionException,
                         InUseException
Get a locked user object for editing. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
id - The user id string.
Returns:
A UserEdit object for editing.
Throws:
IdUnusedException - if not found, or if not an UserEdit object
PermissionException - if the current user does not have permission to mess with this user.
InUseException - if the User object is locked by someone else.

commitEdit

public void commitEdit(UserEdit user)
                throws IdUsedException
Commit the changes made to a UserEdit object, and release the lock. The UserEdit is disabled, and not to be used after this call.

Parameters:
user - The UserEdit object to commit.
Throws:
IdUsedException - if the User eid is already in use by another User object.

cancelEdit

public void cancelEdit(UserEdit user)
Cancel the changes made to a UserEdit object, and release the lock. The UserEdit is disabled, and not to be used after this call.

Parameters:
user - The UserEdit object to commit.

getAnonymousUser

public User getAnonymousUser()
Access the anonymous user object.

Returns:
the anonymous user object.

getUsers

public List getUsers()
Access all user objects - known to us (not from external providers).

Returns:
A list of user objects containing each user's information.
Throws:
IdUnusedException - if not found.

getUsers

public List getUsers(int first,
                     int last)
Find all the users within the record range given (sorted by sort name).

Parameters:
first - The first record position to return.
last - The last record position to return.
Returns:
A list (User) of all the users within the record range given (sorted by sort name).

countUsers

public int countUsers()
Count all the users.

Returns:
The count of all users.

searchUsers

public List searchUsers(String criteria,
                        int first,
                        int last)
Search all the users that match this criteria in id or email, first or last name, returning a subset of records within the record range given (sorted by sort name).

Parameters:
criteria - The search criteria.
first - The first record position to return.
last - The last record position to return.
Returns:
A list (User) of all the aliases matching the criteria, within the record range given (sorted by sort name).

countSearchUsers

public int countSearchUsers(String criteria)
Count all the users that match this criteria in id or target, first or last name.

Returns:
The count of all users matching the criteria.

allowAddUser

public boolean allowAddUser(String id)
check permissions for addUser().

Parameters:
id - The group id.
Returns:
true if the user is allowed to addUser(id), false if not.

addUser

public UserEdit addUser(String id)
                 throws IdInvalidException,
                        IdUsedException,
                        PermissionException
Add a new user to the directory. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
id - The user id.
Returns:
A locked UserEdit object (reserving the id).
Throws:
IdInvalidException - if the user id is invalid.
IdUsedException - if the user id is already used.
PermissionException - if the current user does not have permission to add a user.

addUser

public User addUser(String id,
                    String firstName,
                    String lastName,
                    String email,
                    String pw,
                    String type,
                    ResourceProperties properties)
             throws IdInvalidException,
                    IdUsedException,
                    PermissionException
Add a new user to the directory, complete in one operation.

Parameters:
id - The user id.
firstName - The user first name.
lastName - The user last name.
email - The user email.
pw - The user password.
type - The user type.
properties - Other user properties.
Returns:
The User object created.
Throws:
IdInvalidException - if the user id is invalid.
IdUsedException - if the user id is already used.
PermissionException - if the current user does not have permission to add a user.

mergeUser

public UserEdit mergeUser(Element el)
                   throws IdInvalidException,
                          IdUsedException,
                          PermissionException
Add a new user to the directory, from a definition in XML. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
el - The XML DOM Element defining the user.
Returns:
A locked UserEdit object (reserving the id).
Throws:
IdInvalidException - if the user id is invalid.
IdUsedException - if the user id is already used.
PermissionException - if the current user does not have permission to add a user.

allowRemoveUser

public boolean allowRemoveUser(String id)
check permissions for removeUser().

Parameters:
id - The group id.
Returns:
true if the user is allowed to removeUser(id), false if not.

removeUser

public void removeUser(UserEdit user)
                throws PermissionException
Remove this user's information from the directory - it must be a user with a lock from editUser(). The UserEdit is disabled, and not to be used after this call.

Parameters:
user - The locked user object to remove.
Throws:
PermissionException - if the current user does not have permission to remove this user.

authenticate

public User authenticate(String id,
                         String password)
Authenticate a user / password.

Parameters:
id - The user id.
password - The password.
Returns:
The User object of the authenticated user if successfull, null if not.

destroyAuthentication

public void destroyAuthentication()
Remove authentication for the current user.


userReference

public String userReference(String id)
Access the internal reference which can be used to access the resource from within the system.

Parameters:
id - The user id string.
Returns:
The the internal reference which can be used to access the resource from within the system.