com.samskivert.servlet.user
Class UserManager

java.lang.Object
  com.samskivert.servlet.user.UserManager

public class UserManager
extends Object

The user manager provides easy access to user objects for servlets. It takes care of cookie management involved in login, logout and loading a user record during an authenticated session.

Nested Class Summary

static class	UserManager.InsecureAuthenticator A totally insecure authenticator that authenticates any user.
static class	UserManager.PasswordAuthenticator An authenticator that requires that the user-supplied password match the actual user password.

Field Summary

protected Properties	_config Our user manager configuration.
protected String	_loginURL The URL for the user login page.
protected Interval	_pruner The interval for user session pruning.
protected UserRepository	_repository The user repository.
protected String	_userAuthCookie The name of our user authentication cookie.
static Authenticator	AUTH_INSECURE An instance of the insecure authenticator for general-purpose use.
static Authenticator	AUTH_PASSWORD An instance of the password authenticator for general-purpose use.
protected static int	NON_PERSIST_EXPIRE_DAYS Indicates how long (in days) that a "non-persisting" session token should last.
protected static int	PERSIST_EXPIRE_DAYS Indicates how long (in days) that a "persisting" session token should last.
protected static long	SESSION_PRUNE_INTERVAL Prune the session table every hour.
protected static String	USERAUTH_COOKIE The user authentication cookie name.
protected static boolean	USERMGR_DEBUG Change this to true and recompile to debug cookie handling.

Constructor Summary

UserManager()

Method Summary

protected UserRepository	createRepository(ConnectionProvider conprov) Called by the user manager to create the user repository.
void	effectLogin(User user, int expires, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp) If a user is already known to be authenticated for one reason or other, this method can be used to give them the appropriate authentication cookies to effect their login.
UserRepository	getRepository() Returns a reference to the repository in use by this user manager.
void	init(Properties config, ConnectionProvider conprov) Prepares this user manager for operation.
void	init(Properties config, ConnectionProvider conprov, RunQueue pruneQueue) Prepares this user manager for operation.
User	loadUser(javax.servlet.http.HttpServletRequest req) Fetches the necessary authentication information from the http request and loads the user identified by that information.
User	loadUser(String authcode) Loads up a user based on the supplied session authentication token.
User	login(String username, Password password, boolean persist, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, Authenticator auth) Attempts to authenticate the requester and initiate an authenticated session for them.
Tuple<User,String>	login(String username, Password password, int expires, Authenticator auth) Attempts to authenticate the requester and initiate an authenticated session for them.
void	logout(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp) Logs the user out.
boolean	refreshSession(String sessionKey, int expireDays) Validates that the supplied session key is still valid and if so, refreshes it for the specified number of days.
User	requireUser(javax.servlet.http.HttpServletRequest req) Fetches the necessary authentication information from the http request and loads the user identified by that information.
void	shutdown()

Methods inherited from class java.lang.Object

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

Field Detail

AUTH_INSECURE

public static final Authenticator AUTH_INSECURE

An instance of the insecure authenticator for general-purpose use.

AUTH_PASSWORD

public static final Authenticator AUTH_PASSWORD

An instance of the password authenticator for general-purpose use.

_config

protected Properties _config

Our user manager configuration.

_repository

protected UserRepository _repository

The user repository.

_pruner

protected Interval _pruner

The interval for user session pruning.

_loginURL

protected String _loginURL

The URL for the user login page.

_userAuthCookie

protected String _userAuthCookie

The name of our user authentication cookie.

USERAUTH_COOKIE

protected static final String USERAUTH_COOKIE

The user authentication cookie name.

See Also:

Constant Field Values

SESSION_PRUNE_INTERVAL

protected static final long SESSION_PRUNE_INTERVAL

Prune the session table every hour.

See Also:

Constant Field Values

PERSIST_EXPIRE_DAYS

protected static final int PERSIST_EXPIRE_DAYS

Indicates how long (in days) that a "persisting" session token should last.

See Also:

Constant Field Values

NON_PERSIST_EXPIRE_DAYS

protected static final int NON_PERSIST_EXPIRE_DAYS

Indicates how long (in days) that a "non-persisting" session token should last.

See Also:

Constant Field Values

USERMGR_DEBUG

protected static final boolean USERMGR_DEBUG

Change this to true and recompile to debug cookie handling.

See Also:

Constant Field Values

Constructor Detail

UserManager

public UserManager()

Method Detail

init

public void init(Properties config,
                 ConnectionProvider conprov)
          throws PersistenceException

Prepares this user manager for operation. Presently the user manager requires the following configuration information:

• login_url: Should be set to the URL to which to redirect a requester if they are required to login before accessing the requested page. For example:

   login_url = /usermgmt/login.ajsp?return=%R
   

  The %R will be replaced with the URL encoded URL the user is currently requesting (complete with query parameters) so that the login code can redirect the user back to this request once they are authenticated.

Parameters:

config - the user manager configuration properties.

conprov - the database connection provider that will be used to obtain a connection to the user database.

Throws:

PersistenceException

init

public void init(Properties config,
                 ConnectionProvider conprov,
                 RunQueue pruneQueue)
          throws PersistenceException

Prepares this user manager for operation. See init(Properties,ConnectionProvider).

Parameters:

pruneQueue - an optional run queue on which to run our periodic session pruning task.

Throws:

PersistenceException

shutdown

public void shutdown()

getRepository

public UserRepository getRepository()

Returns a reference to the repository in use by this user manager.

loadUser

public User loadUser(javax.servlet.http.HttpServletRequest req)
              throws PersistenceException

Fetches the necessary authentication information from the http request and loads the user identified by that information.

Returns:

the user associated with the request or null if no user was associated with the request or if the authentication information is bogus.

Throws:

PersistenceException

loadUser

public User loadUser(String authcode)
              throws PersistenceException

Loads up a user based on the supplied session authentication token.

Throws:

PersistenceException

requireUser

public User requireUser(javax.servlet.http.HttpServletRequest req)
                 throws PersistenceException,
                        RedirectException

Fetches the necessary authentication information from the http request and loads the user identified by that information. If no user could be loaded (because the requester is not authenticated), a redirect exception will be thrown to redirect the user to the login page specified in the user manager configuration.

Returns:

the user associated with the request.

Throws:

PersistenceException

RedirectException

login

public User login(String username,
                  Password password,
                  boolean persist,
                  javax.servlet.http.HttpServletRequest req,
                  javax.servlet.http.HttpServletResponse rsp,
                  Authenticator auth)
           throws PersistenceException,
                  AuthenticationFailedException

Attempts to authenticate the requester and initiate an authenticated session for them. An authenticated session involves their receiving a cookie that proves them to be authenticated and an entry in the session database being created that maps their information to their userid. If this call completes, the session was established and the proper cookies were set in the supplied response object. If invalid authentication information is provided or some other error occurs, an exception will be thrown.

Parameters:

username - The username supplied by the user.

password - The password supplied by the user.

persist - If true, the cookie will expire in one month, if false, the cookie will expire at the end of the user's browser session.

req - The request via which the login page was loaded.

rsp - The response in which the cookie is to be set.

auth - The authenticator used to check whether the user should be authenticated.

Returns:

the user object of the authenticated user.

Throws:

PersistenceException

AuthenticationFailedException

login

public Tuple<User,String> login(String username,
                                Password password,
                                int expires,
                                Authenticator auth)
                         throws PersistenceException,
                                AuthenticationFailedException

Attempts to authenticate the requester and initiate an authenticated session for them. A session token will be assigned to the user and returned along with the associated User record. It is assumed that the client will maintain the session token via its own means.

Parameters:

username - the username supplied by the user.

password - the password supplied by the user.

expires - the number of days in which this session should expire.

auth - the authenticator used to check whether the user should be authenticated.

Returns:

the user object of the authenticated user.

Throws:

PersistenceException

AuthenticationFailedException

effectLogin

public void effectLogin(User user,
                        int expires,
                        javax.servlet.http.HttpServletRequest req,
                        javax.servlet.http.HttpServletResponse rsp)
                 throws PersistenceException

If a user is already known to be authenticated for one reason or other, this method can be used to give them the appropriate authentication cookies to effect their login.

Parameters:

expires - the number of days in which to expire the session cookie, 0 means expire at the end of the browser session.

Throws:

PersistenceException

logout

public void logout(javax.servlet.http.HttpServletRequest req,
                   javax.servlet.http.HttpServletResponse rsp)

Logs the user out.

refreshSession

public boolean refreshSession(String sessionKey,
                              int expireDays)
                       throws PersistenceException

Validates that the supplied session key is still valid and if so, refreshes it for the specified number of days.

Returns:

true if the session was located and refreshed, false otherwise.

Throws:

PersistenceException

createRepository

protected UserRepository createRepository(ConnectionProvider conprov)
                                   throws PersistenceException

Called by the user manager to create the user repository. Derived classes can override this and create a specialized repository if they so desire.

Throws:

PersistenceException