/* ===================================================================
 * UserBiz.java
 * 
 * Copyright (c) 2004 Matt Magoffin (spamsqr@msqr.us)
 * 
 * This program is free software; you can redistribute it and/or 
 * modify it under the terms of the GNU General Public License as 
 * published by the Free Software Foundation; either version 2 of 
 * the License, or (at your option) any later version.
 * 
 * This program 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 
 * General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License 
 * along with this program; if not, write to the Free Software 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
 * 02111-1307 USA
 * ===================================================================
 * $Id: UserBiz.java 23 2009-05-03 22:59:25Z msqr $
 * ===================================================================
 */

package magoffin.matt.ieat.biz;

import java.util.List;

import magoffin.matt.ieat.AuthorizationException;
import magoffin.matt.ieat.domain.User;

/**
 * Business interface for users.
 * 
 * @author Matt Magoffin (spamsqr@msqr.us)
 * @version $Revision: 23 $ $Date: 2009-05-04 10:59:25 +1200 (Mon, 04 May 2009) $
 */
public interface UserBiz {
	
	/** Bit flag for Admin user access level. */
	public static final int ACCESS_ADMIN = 0x1;
	
	/** 
	 * Flag for a String value that should not change.
	 * 
	 * <p>For example, when updating a User, the password field can be 
	 * left unchagned when set to this value.</p>
	 */
	public static final String DO_NOT_CHANGE_VALUE = "**DO_NOT_CHANGE**";
	
	/**
	 * Register a new user.
	 * 
	 * <p>Use this method to register a new user. After registration
	 * the user will be stored in the back end, but the user will
	 * require confirmation before they can officially log into the 
	 * application (see {@link #confirmRegisteredUser(String, String, BizContext)}).
	 * </p>
	 * 
	 * @param user the new user to register
	 * @param context the BizContext
	 * 
	 * @return a confirmation string suitable to pass to 
	 * {@link #confirmRegisteredUser(String, String, BizContext)}
	 * @throws AuthorizationException if the desired login is taken already, 
	 * this exception will be thrown with the reason code 
	 * {@link AuthorizationException#DUPLICATE_LOGIN}
	 */
	public String registerUser(User user, BizContext context) throws AuthorizationException;
	
	/**
	 * Confirm a registered user.
	 * 
	 * <p>After a user has registered (see {@link #registerUser(User, BizContext)}) they 
	 * must confirm the registration via this method. After confirmation the 
	 * user can login via {@link #logonUser(String, String)} as a normal
	 * user.</p>
	 * 
	 * @param login the login to confirm
	 * @param confirmationCode the confirmation code
	 * @param context the BizContext
	 * @return the confirmed user
	 * @throws AuthorizationException if the confirmationCode does not match
	 * then the reason code will be set to {@link AuthorizationException#REGISTRATION_NOT_CONFIRMED}, 
	 * if the login is not found then {@link AuthorizationException#UNKNOWN_LOGIN}, if 
	 * the account has already been confirmed then 
	 * {@link AuthorizationException#REGISTRATION_ALREADY_CONFIRMED}
	 */
	public User confirmRegisteredUser(String login, String confirmationCode, BizContext context)
	throws AuthorizationException;
	
	/**
	 * Store a User in the back end.
	 * 
	 * <p>This method will accept new users as well as updates 
	 * to existing users.</p>
	 * 
	 * <p>When updating an existing user, if the User's password field
	 * is set to {@link #DO_NOT_CHANGE_VALUE} then the User's password
	 * will not be updated in the back end.</p>
	 * 
	 * @param user the user to store
	 * @param context the current context
	 * @return the stored user
	 * @throws AuthorizationException if the current user is not authorized to update 
	 * this user
	 */
	public User storeUser(User user, BizContext context) throws AuthorizationException;
	
	/**
	 * Remove a User from the back end.
	 * @param userId the ID of the User to remove
	 * @param context the current context
	 */
	public void removeUser(Integer userId, BizContext context);

	/**
	 * Authenticate a user by their username and password.
	 * 
	 * @param login the login name of the user to logon
	 * @param password the attempted password
	 * @return the User if found and password matches
	 * @throws AuthorizationException if user not found or password
	 * does not match
	 */
	public User logonUser(String login, String password) throws AuthorizationException;
	
	/**
	 * Get a User by its ID.
	 * @param userId the ID of the user to get
	 * @param context the current context
	 * @return User
	 */
	public User getUserById(Integer userId, BizContext context);
	
	/**
	 * Return <em>true</em> if the supplied user has the specified access level.
	 * @param user the user to test
	 * @param level the level (use the <code>ACCESS_*</code> constants)
	 * @return <em>true</em> if the supplied user has the specified access level
	 */
	public boolean hasAccessLevel(User user, int level);
	
	/**
	 * Call to email a user a link with a one-time password.
	 * 
	 * <p>Calling this method will do the following:</p>
	 * <ol>
	 * <li>Generate a random password for the user</li>
	 * <li>Update the user with the new password</li>
	 * <li>Generate a confirmation code for the user to pass later
	 * to {@link #confirmForgotPassword(String, String, String, BizContext)}</li>
	 * </ol>
	 * 
	 * @param login the login of the user that forgot their password
	 * @param context the current context
	 * @return a confirmation string suitable to pass to 
	 * {@link #confirmForgotPassword(String, String, String, BizContext)}
	 * @throws AuthorizationException if the <var>login</var> is not found the reason 
	 * code will be set to {@link AuthorizationException#UNKNOWN_LOGIN}
	 */
	public String forgotPassword(String login, BizContext context) throws AuthorizationException;
	
	/**
	 * Confirm a forgotten password.
	 * 
	 * @param login the login of the user being confirmed
	 * @param confirmationCode the confirmation code issued by a previous 
	 * call to {@link #forgotPassword(String, BizContext)}
	 * @param newPassword the new password to set
	 * @param context the current context
	 * @return the confirmed user
	 * @throws AuthorizationException if the <var>login</var> is not found the reason 
	 * code will be set to {@link AuthorizationException#UNKNOWN_LOGIN}, if the confirmationCode 
	 * does not match then the reason code will be set to 
	 * {@link AuthorizationException#FORGOTTEN_PASSWORD_NOT_CONFIRMED}
	 */
	public User confirmForgotPassword(String login, String confirmationCode, String newPassword, BizContext context)
	throws AuthorizationException;
	
	/**
	 * Get a list of User objects that have a specific access level.
	 * @param level the access level
	 * @return list of users
	 */
	public List<User> getUsersWithAccess(int level);
}
