com.boylesoftware.cb2.commons.user
Class UserBLO

java.lang.Object
  com.boylesoftware.cb2.BLObject
      com.boylesoftware.cb2.commons.user.UserBLO

All Implemented Interfaces:

AuthenticationListener, java.io.Serializable

public class UserBLO

extends BLObject

implements AuthenticationListener

Generic implementation of an application user account business entity. This BLO allows to login/logout users and manage their accounts.

This BLO requires the following initialization parameters:

• fetchUserDetailsByLoginNameQN -- names the query in the configuration file used to fetch user details data model by a user's login name. The data model returned by the query should be UserBasicDM or derived from it.
• fetchUserDescriptorsQN -- names the query in the configuration file used to fetch descriptors for all available in the system user accounts. The data models returned by the query should be UserBasicDM or derived from it.

This BLO implements SecurityBLI interface so it can be used with CB2's support for Servlet Specification user authentication/authorization when deployed under name "user".

Version:

$Id: UserBLO.java,v 1.1 2003/04/22 17:34:18 levahim Exp $

Author:

Lev Himmelfarb

See Also:

UserBasicDM, AuthenticationListener, Serialized Form

Field Summary

static int	ERR_ALREADY_LOGGEDIN Error code indicating that the user is already logged in and you are trying to log in again.
protected static int	ERR_BASE Base value for error codes.
static int	ERR_INVALID_PASSWORD Error code indicating that the password was invalid.
static int	ERR_INVALID_USERNAME Error code indicating that the login name was invalid.
protected java.lang.String	fetchUserDetailsByLoginNameQN Name of the select query in the configuration file which is used for getting a user details data model by the user's login name.
protected UserBasicDM	loggedInUserDM DM of the logged in user or null if no user is logged in.

Fields inherited from class com.boylesoftware.cb2.BLObject

bloc, log

Constructor Summary

UserBLO()

Method Summary

void	addUserSessionStateListener(UserSessionStateListener listener) Registers the specified listener for user session state events.
protected void	destroy() Free all used by the BLO resources.
protected void	fireUserLoggedInEvent(long userId) Call userLoggedIn() method on all registered user session state event listeners.
protected void	fireUserLoggedOutEvent(long userId) Call userLoggedOut() method on all registered user session state event listeners.
protected void	init() Initializes the BLO.
boolean	isInRole(java.lang.String role) Returns true if currently logged in user is in the specified by name role.
boolean	isLoggedIn() Returns true if a user is authenticated and successfully logged in meaning that the BLO is in authenticated mode.
boolean	login(java.lang.String username, java.lang.String password) Tries to log in the specified by login name user.
void	logout() Logs out the currently logged in user.
void	processUserLogin(java.security.Principal principal) Notify the BLO about a user login event.
void	processUserLogout() Notify the BLO about a user logout event.
protected void	registerLogin(UserBasicDM dm) Performes all internal BLO operations for a user login action.
void	removeUserSessionStateListener(UserSessionStateListener listener) Removes the specified listener for user session state events from the internal list of listeners.

Methods inherited from class com.boylesoftware.cb2.BLObject

activate, getApplicationContext, getBLO, getBLOContainer, getDAO, getDAO, getDAOConfig, getDAOConfig, getDeploymentName, getInitParameter, getLastErrors, isRollbackOnly, setErrors, setRollbackOnly

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERR_BASE

protected static final int ERR_BASE

Base value for error codes.

See Also:

Constant Field Values

ERR_INVALID_USERNAME

public static final int ERR_INVALID_USERNAME

Error code indicating that the login name was invalid.

See Also:

Constant Field Values

ERR_INVALID_PASSWORD

public static final int ERR_INVALID_PASSWORD

Error code indicating that the password was invalid.

See Also:

Constant Field Values

ERR_ALREADY_LOGGEDIN

public static final int ERR_ALREADY_LOGGEDIN

Error code indicating that the user is already logged in and you are trying to log in again.

See Also:

Constant Field Values

fetchUserDetailsByLoginNameQN

protected java.lang.String fetchUserDetailsByLoginNameQN

Name of the select query in the configuration file which is used for getting a user details data model by the user's login name. This field is populated from fetchUserDetailsByLoginNameQN BLO initialization parameter.

loggedInUserDM

protected UserBasicDM loggedInUserDM

DM of the logged in user or null if no user is logged in.

Constructor Detail

UserBLO

public UserBLO()

Method Detail

init

protected void init()
             throws BLException

Initializes the BLO. Call this method if you override it in your child class.

Overrides:

init in class BLObject

Throws:

BLException - indicates a serious error, the BLO can not be initialized.

destroy

protected void destroy()

Free all used by the BLO resources. Call this method if you override it in your child class.

Overrides:

destroy in class BLObject

addUserSessionStateListener

public void addUserSessionStateListener(UserSessionStateListener listener)

Registers the specified listener for user session state events.

Parameters:

listener - instance of your listener which will be receiving the notifications.

removeUserSessionStateListener

public void removeUserSessionStateListener(UserSessionStateListener listener)

Removes the specified listener for user session state events from the internal list of listeners.

Parameters:

listener - instance of the listener to be removed from the notification list.

fireUserLoggedInEvent

protected void fireUserLoggedInEvent(long userId)
                              throws BLException

Call userLoggedIn() method on all registered user session state event listeners.

Parameters:

userId - id of the user logged in.

Throws:

BLException - if any of the listeners threw it on userLoggedIn() method call.

fireUserLoggedOutEvent

protected void fireUserLoggedOutEvent(long userId)
                               throws BLException

Call userLoggedOut() method on all registered user session state event listeners.

Parameters:

userId - id of the user logged out.

Throws:

BLException - if any of the listeners threw it on userLoggedOut() method call.

login

public boolean login(java.lang.String username,
                     java.lang.String password)
              throws BLException

Tries to log in the specified by login name user. If the method returned false use getLastErrors() method to get the reason why login was unsuccessful. Possible error codes this method sets are ERR_INVALID_USERNAME, ERR_INVALID_PASSWORD and ERR_ALREADY_LOGGEDIN.

Use this method only if you implement user authentication/authorization yourself. If you use Servlet Specification security, that is an SecurityAuthenticator implementation - use the SecurityBLI interface instead.

Parameters:

username - login name of the user to log in.

password - password to be used for log in.

Returns:

true if the user was successfully authenticated and logged in.

Throws:

BLException - indicates a serious problem in the system.

logout

public void logout()

Logs out the currently logged in user. The BLO changes to the non-autheticated "guest" mode.

isLoggedIn

public boolean isLoggedIn()

Returns true if a user is authenticated and successfully logged in meaning that the BLO is in authenticated mode.

Returns:

true if the user is logged in.

isInRole

public boolean isInRole(java.lang.String role)

Returns true if currently logged in user is in the specified by name role. If no user is currently logged in this method always returns false. Also, if a user is logged in this method always returns true for role "user".

Parameters:

role - name of the role to check. Note that the role name is case-sensitive.

Returns:

true if the user is in the specified role.

processUserLogin

public void processUserLogin(java.security.Principal principal)
                      throws BLException

Notify the BLO about a user login event. This implementation fetches the user's DM from the database using the configured DAO query (the fetchUserDetailsByLoginNameQN init parameter) and registers the login by a registerLogin method call.

Specified by:

processUserLogin in interface AuthenticationListener

Parameters:

principal - the logged in principal.

Throws:

BLException - if an error happened and the user cannot be logged in.

processUserLogout

public void processUserLogout()

Notify the BLO about a user logout event. This implementation just calls logout.

Specified by:

processUserLogout in interface AuthenticationListener

registerLogin

protected void registerLogin(UserBasicDM dm)
                      throws BLException

Performes all internal BLO operations for a user login action. This implementation sets the loggedInUserDM internal field and fires "user logged in" event by calling fireUserLoggedInEvent protected method.

Parameters:

dm - the logged in user's DM.

Throws:

BLException - if the login could not be processed.