usermanager.java

老外的在线考试

/*
 * UserEJB - CyberDemia's User management library implemented using EJBs.
 * Copyright (C) 2003 CyberDemia Research and Services
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA  02111-1307, USA.
 *
 * See the COPYING file located in the top-level-directory of
 * the archive of this library for complete text of license.
 */
package com.cyberdemia.user;
import javax.ejb.*;
import java.rmi.RemoteException;

/**
* UserManager is a facade that provides
* useful methods for managing User and related beans.
*
* @author Alexander Yap
*/
public interface UserManager extends EJBObject
{
	/**
	 * Adds a new user to the database using the data passed in
	 * by a UserData instance. Some fields in UserData are ignored, such
	 * as id and createdMillis.
	 * This method first checks that the user's email address does not match
	 * any existing email addresses in the database.
	 * Note that the lastName is always atored in all upper-case to simplify searching.
	 * 
	 * @param data UserData instance storing data for the new user.
	 * @return Unique ID (primary key) of the new user.
	 * @throws RemoteException
	 * @throws UserException if the email address already exists in the database, or due to some other error.
	 */
	public String addUser(UserData data) throws RemoteException, UserException;

	/**
	 * Removed an existing user from the database.
	 * @param id Unique ID of user to remove.
	 * @throws RemoteException
	 * @throws UserException if there is an error.
	 */
	public void removeUser(String id) throws RemoteException, UserException;

	/**
	 * Gets the unique IDs of all users in the database.
	 * @return Array of all user IDs.
	 * @throws RemoteException
	 */
	public String[] getUsers() throws RemoteException;

	/**
	 * Gets the data of a user identified by its unique ID. 
	 * @param id User ID.
	 * @return UserData instance storing the user's data, or null if the user doesn't exist.
	 * @throws RemoteException
	 */
	public UserData getUserData(String id) throws RemoteException;

	/**
	 * Updates an existing user with new data passed in as a UserData instance.
	 * The user to modify is identified by UserData's id field.
	 * @param data UserData instance storing user data.
	 * @throws RemoteException
	 * @throws UserException if an error occurs such as the id is invalid.
	 */
	public void setUserData(UserData data) throws RemoteException, UserException;

	/**
	 * Gets the data of a user identified by its unique ID.  
	 * @param email User email address
	 * @return UserData instance storing the user's data, or null if the user doesn't exist.
	 * @throws RemoteException
	 */
	public UserData getUserDataByEmail(String email) throws RemoteException;
	
	/**
	 * Finds users by searching for a substring within the email address.
	 * The search may or may not be case-sensitive depending on the
	 * underlying database.
	 * For example, search string "lex@yah" will match email addresses
	 * like "[e-mail]" and "[e-mail]".
	 * 
	 * @param emailSearchStr Email address substring to search for.
	 * @return Array of UserData instances for found users, or empty array if no user found.
	 * @throws RemoteException
	 */
	public UserData[] searchUsersByEmail(String emailSearchStr) throws RemoteException;
	
	/**
	 * Finds users by searching for a substring within the last name.
	 * The substring is converted to upper-case before being compared
	 * with values from database what are also all in upper-case. 
	 * Hence, the search is effectively case-insensitive regardless
	 * of the underlying database.
	 * For example, search string "le" will match last names
	 * like "ALEX", "Leonardo" and "napolean".
	 *
	 * @param lastNameSearchStr Last name substring to search for.
	 * @return Array of UserData instances for found users, or empty array if no user found.
	 * @throws RemoteException
	 */
	public UserData[] searchUsersByLastName(String lastNameSearchStr) throws RemoteException;

	/**
	 * Checks if any user with the specified email address already exists in the database.
	 * @param email Email address to check for.
	 * @return true if a user with the email address exist, otherwise false.
	 * @throws RemoteException
	 */
	public boolean isEmailExists(String email) throws RemoteException;

	/**
	* Validates a User ID against a specified password. 
	* This method is provided in case the client code needs to perform some
	* programmatic authentication. If authentication is managed by the container,
	* there is no need for this method.
	* @param id User ID to validate.
	* @param password  Password of user.
	* @return true if user is valid and the password matches, otherwise false
	*/
	public boolean validateUser(String id, String password) throws RemoteException;

	/**
	* Gets resources within the specified category that are
	* associated with the specified user.
	* @param id User ID
	* @param catKey  Key to identify the category of resource to extract, or null to extract all resources.
	* @return Array of resource IDs.
	*/
	public String[] getResourcesInUser( String id, String catKey ) throws RemoteException;

	/**
	* Associates a resource with the specified user.
	* @param id User ID
	* @param catKey  Key to identify the category of resource to add.
	* @param resId   The ID of the resource to add.
	* @return true if resource is added successfully, otherwise false (it already exists).
	*/
	public boolean addResourceToUser( String id, String catKey, String resId ) throws RemoteException;

	/**
	* Removes a resource from the specified user.
	* @param id User ID
	* @param catKey  Key to identify the category of resource to remove.
	* @param resId   The ID of the resource to remove.
	* @return true if resource is removed successfully, otherwise false (not found).
	*/
	public boolean removeResourceFromUser( String id, String catKey, String resId ) throws RemoteException;

	/**
	* Gets roles that are associated with the specified user.
	* @param id User ID
	* @return Array of role names.
	*/
	public String[] getRolesInUser( String id ) throws RemoteException;

}