org.pajes.security
Class AccessPermission

java.lang.Object
  org.pajes.servlet.PajesContextListener
      org.pajes.security.AccessPermission

All Implemented Interfaces:

java.util.EventListener, javax.servlet.ServletContextListener

Direct Known Subclasses:

DefaultAccessPermission

public abstract class AccessPermission

extends PajesContextListener

The abstract AccessPermission is sub-classed by classes that determine whether a user has access to servlet resources, and how to process a login request.

The sub-class should be defined as a <listener> in the web application deployment descriptor.

Field Summary

static java.lang.String	J_PASSWORD Name of text input field that contains the password
static java.lang.String	J_USERNAME Name of text input field that contains the user name

Constructor Summary

AccessPermission()

Method Summary

void	contextDestroyed(javax.servlet.ServletContextEvent sce) Notification that the servlet context is about to be shut down.
void	contextInitialized(javax.servlet.ServletContextEvent sce) Notification that the web application is ready to process requests.
void	destroy() Called to destroy this AccessPermission instance.
java.sql.Connection	getDBConnection() Convenience method to return a free database connection from the default connection pool.
java.sql.Connection	getDBConnection(java.lang.String poolName) Convenience method to return a free database connection from the named connection pool.
ConnectionManager	getDBConnectionPoolManager() Convenience method to return the ConnectionManager that manages the defined connection pools available in this ServletContext.
java.lang.Integer	getLoginAttempts(javax.servlet.http.HttpSession session) Returns the current number of times an attempt has been made to login without success.
javax.servlet.RequestDispatcher	getLoginAttemptsExceededPage() Deprecated. Use #getLoginAttemptsExceededPage(HttpServletRequest)
javax.servlet.RequestDispatcher	getLoginAttemptsExceededPage(javax.servlet.http.HttpServletRequest request) Returns the page to which the user will be forwarded when the maximum number of login attempts is exceeded.
javax.servlet.RequestDispatcher	getLoginFailedPage() Deprecated. Use #getLoginFailedPage(HttpServletRequest)
javax.servlet.RequestDispatcher	getLoginFailedPage(javax.servlet.http.HttpServletRequest request) Returns the page to which the user will be forwarded when authentication fails.
javax.servlet.RequestDispatcher	getLoginPage() Deprecated. Use #getLoginPage(HttpServletRequest)
javax.servlet.RequestDispatcher	getLoginPage(javax.servlet.http.HttpServletRequest request) Returns the login page to which the user will be forwarded if they have not yet been authenticated.
javax.servlet.RequestDispatcher	getLoginSuccessPage(javax.servlet.http.HttpServletRequest request) Returns the page to which the user will be forwarded when authentication succeeds.
int	getMaximumLoginAttempts() Returns the maximum number of times an attempt may be made to login without success.
javax.servlet.ServletContext	getServletContext() Returns a reference to the ServletContext from which this instance was initialised.
abstract java.security.Principal	getUserPrincipal(PajeServlet servlet, javax.servlet.http.HttpServletRequest request) Determines whether the specified request should be allowed to access the specified servlet.
abstract PrincipalRoles	getUserPrincipalRoles(java.security.Principal user) Returns a list of valid roles for a specific user.
void	init() AccessPermission sub-class initialisation.
void	init(javax.servlet.ServletContext context) Main AccessPermission initialisation.
boolean	isInitialised() Determines if
boolean	isInvalid(java.security.Principal principal, javax.servlet.http.HttpServletRequest request) Called to determine if the Principal requires revalidation.
boolean	isPermitted(AuthenticatedPajeServlet servlet, java.security.Principal principal, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Called by the AuthenticatedPajeServlet.isPermitted(java.security.Principal, org.pajes.security.AccessPermission, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) method to provide additional access checking before allowing the request to be serviced.
javax.servlet.RequestDispatcher	loginFailed(javax.servlet.http.HttpServletRequest request, java.lang.Integer attempts) Called by AuthenticatedPajeServlet to handle a failed login attempt, and determine the next page to be displayed to the user.
void	loginSucceeded(javax.servlet.http.HttpSession session, java.security.Principal principal) Called by Login to handle a successful login attempt.
javax.servlet.RequestDispatcher	logout(javax.servlet.http.HttpServletRequest request) Called by Logout to revoke authentication, and determine the next page to be displayed to the user.
protected void	postLoginProcessing(javax.servlet.http.HttpSession session, java.security.Principal principal) Called immediately after successful login.
protected void	preLogoutProcessing(javax.servlet.http.HttpServletRequest request) Called immediately before logout.
protected void	resetLoginAttempts(javax.servlet.http.HttpSession session) Resets the login attempts count to null.
java.lang.Integer	setLoginAttempts(javax.servlet.http.HttpSession session) Sets the number of logins that have been attempted.
protected void	setLoginAttemptsExceededPage(javax.servlet.RequestDispatcher dispatcher) Sets the page to which the user will be forwarded when the maximum number of login attempts is exceeded.
protected void	setLoginFailedPage(javax.servlet.RequestDispatcher dispatcher) Sets the page to which the user will be forwarded when authentication fails.
protected void	setLoginPage(javax.servlet.RequestDispatcher dispatcher) Sets the login page to which the user will be forwarded if they have not yet been authenticated.
protected void	setLoginSuccessPage(javax.servlet.RequestDispatcher dispatcher) Sets the page to which the user will be forwarded when authentication succeeds.
protected void	setMaximumLoginAttempts(int attempts) Sets the maximum number of times an attempt may be made to login without success.

Methods inherited from class org.pajes.servlet.PajesContextListener

getContext

Methods inherited from class java.lang.Object

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

Field Detail

J_PASSWORD

public static final java.lang.String J_PASSWORD

Name of text input field that contains the password

See Also:

Constant Field Values

J_USERNAME

public static final java.lang.String J_USERNAME

Name of text input field that contains the user name

See Also:

Constant Field Values

Constructor Detail

AccessPermission

public AccessPermission()

Method Detail

contextDestroyed

public final void contextDestroyed(javax.servlet.ServletContextEvent sce)

Notification that the servlet context is about to be shut down.

Specified by:

contextDestroyed in interface javax.servlet.ServletContextListener

Overrides:

contextDestroyed in class PajesContextListener

Parameters:

sce - the event class for notifications about changes to the servlet context of a web application.

See Also:

destroy()

contextInitialized

public final void contextInitialized(javax.servlet.ServletContextEvent sce)

Notification that the web application is ready to process requests.

Specified by:

contextInitialized in interface javax.servlet.ServletContextListener

Overrides:

contextInitialized in class PajesContextListener

Parameters:

sce - the event class for notifications about changes to the servlet context of a web application.

getDBConnection

public java.sql.Connection getDBConnection()
                                    throws java.sql.SQLException

Convenience method to return a free database connection from the default connection pool.

Returns:

a database Connection object.

Throws:

java.sql.SQLException - if an error occurs accessing the database.

getDBConnection

public java.sql.Connection getDBConnection(java.lang.String poolName)
                                    throws java.sql.SQLException

Convenience method to return a free database connection from the named connection pool.

Parameters:

poolName - the name of the connection pool to use.

Returns:

a database Connection object.

Throws:

java.sql.SQLException - if an error occurs accessing the database.

getDBConnectionPoolManager

public ConnectionManager getDBConnectionPoolManager()

Convenience method to return the ConnectionManager that manages the defined connection pools available in this ServletContext.

Returns:

the ConnectionManager instance.

getLoginAttempts

public java.lang.Integer getLoginAttempts(javax.servlet.http.HttpSession session)

Returns the current number of times an attempt has been made to login without success.

Parameters:

session - the session object.

Returns:

the current number of times an attempt has been made to login without success. Will be null if no attempts have been made.

getLoginAttemptsExceededPage

public javax.servlet.RequestDispatcher getLoginAttemptsExceededPage()

Deprecated. Use #getLoginAttemptsExceededPage(HttpServletRequest)

Deprecated.

Returns:

The loginAttemptsExceededPage value

getLoginAttemptsExceededPage

public javax.servlet.RequestDispatcher getLoginAttemptsExceededPage(javax.servlet.http.HttpServletRequest request)

Returns the page to which the user will be forwarded when the maximum number of login attempts is exceeded.

The default implementation returns the RequestDispatcher set by the setLoginAttemptsExceededPage(javax.servlet.RequestDispatcher) method. However, sub-classes may over-ride this method to provide alternate destinations depending upon the request object.

Parameters:

request - the request object.

Returns:

the page to which the user will be forwarded when authentication fails maximum times.

getLoginFailedPage

public javax.servlet.RequestDispatcher getLoginFailedPage()

Deprecated. Use #getLoginFailedPage(HttpServletRequest)

Deprecated.

Returns:

The loginFailedPage value

getLoginFailedPage

public javax.servlet.RequestDispatcher getLoginFailedPage(javax.servlet.http.HttpServletRequest request)

Returns the page to which the user will be forwarded when authentication fails.

The default implementation returns the RequestDispatcher set by the setLoginFailedPage(javax.servlet.RequestDispatcher) method. However, sub-classes may over-ride this method to provide alternate destinations depending upon the request object.

Parameters:

request - the request object.

Returns:

the page to which the user will be forwarded when authentication fails.

getLoginPage

public javax.servlet.RequestDispatcher getLoginPage()

Deprecated. Use #getLoginPage(HttpServletRequest)

Deprecated.

Returns:

The loginPage value

getLoginPage

public javax.servlet.RequestDispatcher getLoginPage(javax.servlet.http.HttpServletRequest request)

Returns the login page to which the user will be forwarded if they have not yet been authenticated.

The default implementation returns the RequestDispatcher set by the setLoginPage(javax.servlet.RequestDispatcher) method. However, sub-classes may over-ride this method to provide alternate destinations depending upon the request object.

Parameters:

request - the request object.

Returns:

the login page to which the user will be forwarded if they have not yet been authenticated.

getLoginSuccessPage

public javax.servlet.RequestDispatcher getLoginSuccessPage(javax.servlet.http.HttpServletRequest request)

Returns the page to which the user will be forwarded when authentication succeeds.

The default implementation returns the RequestDispatcher set by the setLoginSuccessPage(javax.servlet.RequestDispatcher) method. However, sub-classes may over-ride this method to provide alternate destinations depending upon the request object.

Parameters:

request - the request object.

Returns:

the page to which the user will be forwarded when authentication succeeds.

getMaximumLoginAttempts

public int getMaximumLoginAttempts()

Returns the maximum number of times an attempt may be made to login without success.

Returns:

the maximum number of times an attempt may be made to login without success.

getServletContext

public javax.servlet.ServletContext getServletContext()

Returns a reference to the ServletContext from which this instance was initialised.

Returns:

ServletContext the ServletContext object passed to this object by the init method

See Also:

init(ServletContext)

getUserPrincipal

public abstract java.security.Principal getUserPrincipal(PajeServlet servlet,
                                                         javax.servlet.http.HttpServletRequest request)

Determines whether the specified request should be allowed to access the specified servlet.

Parameters:

servlet - the servlet to which access is requested.

request - the request object.

Returns:

the Principal object representing the user if access should be permitted, or null if user authentication fails.

getUserPrincipalRoles

public abstract PrincipalRoles getUserPrincipalRoles(java.security.Principal user)

Returns a list of valid roles for a specific user.

Parameters:

user - Description of Parameter

Returns:

the object representing a list of valid roles for a specific user.

isInitialised

public final boolean isInitialised()

Determines if

Returns:

true if the AccessPermission has been initialised. init(ServletContext) method has been run.

destroy

public void destroy()

Called to destroy this AccessPermission instance.

The default implementation does nothing.

See Also:

contextDestroyed(javax.servlet.ServletContextEvent), Initialisation.destroy()

init

public final void init(javax.servlet.ServletContext context)
                throws AccessPermissionException

Main AccessPermission initialisation.

Called the first time that authentication services are required.

Parameters:

context - the ServletContext object that contains context information about this web application

Throws:

AccessPermissionException - if a security related exception occurs.

isInvalid

public boolean isInvalid(java.security.Principal principal,
                         javax.servlet.http.HttpServletRequest request)

Called to determine if the Principal requires revalidation.

The default implementation always returns false.

Parameters:

principal - the authenticated user principal.

request - the request object.

Returns:

true if the Principal requires revalidation, or false if no revalidation is required.

isPermitted

public boolean isPermitted(AuthenticatedPajeServlet servlet,
                           java.security.Principal principal,
                           javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response)

Called by the AuthenticatedPajeServlet.isPermitted(java.security.Principal, org.pajes.security.AccessPermission, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) method to provide additional access checking before allowing the request to be serviced.

This method will only be called if the user has been succesfully authenticated (i.e. the Principal has been established).

The default implementation simply returns true.

Parameters:

servlet - the servlet to which access is being requested.

principal - the authenticated principal object.

request - the object that contains the request the client made of the servlet.

response - the object that contains the response the servlet will return to the client.

Returns:

true if the request is to be serviced.

init

public void init()
          throws AccessPermissionException

AccessPermission sub-class initialisation.

This method is called by init(ServletContext), and the default implementation does nothing.

Sub-classes should over-ride this method and call the protected set methods to correctly configure access permissions.

Throws:

AccessPermissionException - if a security related exception occurs.

See Also:

setLoginAttemptsExceededPage(javax.servlet.RequestDispatcher), setLoginFailedPage(javax.servlet.RequestDispatcher), setLoginPage(javax.servlet.RequestDispatcher), setLoginSuccessPage(javax.servlet.RequestDispatcher), setMaximumLoginAttempts(int)

loginFailed

public final javax.servlet.RequestDispatcher loginFailed(javax.servlet.http.HttpServletRequest request,
                                                         java.lang.Integer attempts)

Called by AuthenticatedPajeServlet to handle a failed login attempt, and determine the next page to be displayed to the user.

Parameters:

request - the request object.

attempts - the number of logins attempted by this session.

Returns:

the RequestDispatcher to which the request should be forwarded.

loginSucceeded

public final void loginSucceeded(javax.servlet.http.HttpSession session,
                                 java.security.Principal principal)

Called by Login to handle a successful login attempt.

Parameters:

session - the session object.

principal - the authenticated user principal.

logout

public final javax.servlet.RequestDispatcher logout(javax.servlet.http.HttpServletRequest request)

Called by Logout to revoke authentication, and determine the next page to be displayed to the user.

Parameters:

request - the request object.

Returns:

the RequestDispatcher to which the request should be forwarded after authentication.

setLoginAttempts

public java.lang.Integer setLoginAttempts(javax.servlet.http.HttpSession session)

Sets the number of logins that have been attempted. If no attempts, have yet been made, the number will be set to zero. Otherwise, it will be incremented by one.

Parameters:

session - the session object.

Returns:

the current number of times an attempt has been made to login without success. Will be zero if no attempts have been made.

setLoginAttemptsExceededPage

protected void setLoginAttemptsExceededPage(javax.servlet.RequestDispatcher dispatcher)
                                     throws AccessPermissionException

Sets the page to which the user will be forwarded when the maximum number of login attempts is exceeded.

Parameters:

dispatcher - the page to which the user will be forwarded when authentication fails maximum times.

Throws:

AccessPermissionException - if a null dispatcher is passed.

setLoginFailedPage

protected void setLoginFailedPage(javax.servlet.RequestDispatcher dispatcher)
                           throws AccessPermissionException

Sets the page to which the user will be forwarded when authentication fails.

Parameters:

dispatcher - the page to which the user will be forwarded when authentication fails.

Throws:

AccessPermissionException - if a null dispatcher is passed.

setLoginPage

protected void setLoginPage(javax.servlet.RequestDispatcher dispatcher)
                     throws AccessPermissionException

Sets the login page to which the user will be forwarded if they have not yet been authenticated.

Parameters:

dispatcher - the login page to which the user will be forwarded if they have not yet been authenticated.

Throws:

AccessPermissionException - if a null dispatcher is passed.

setLoginSuccessPage

protected void setLoginSuccessPage(javax.servlet.RequestDispatcher dispatcher)
                            throws AccessPermissionException

Sets the page to which the user will be forwarded when authentication succeeds.

NOTE: Some servlet containers do not correctly save the session if a redirect is done after authentication. It is recommended that only a realRequestDispatcher, rather than a PAJES RequestRedirector be used on login success.

Parameters:

dispatcher - the page to which the user will be forwarded when authentication succeeds.

Throws:

AccessPermissionException - if a null dispatcher is passed.

setMaximumLoginAttempts

protected void setMaximumLoginAttempts(int attempts)

Sets the maximum number of times an attempt may be made to login without success. If not set explicitly, the default is 3.

Parameters:

attempts - the maximum number of times an attempt may be made to login without success.

postLoginProcessing

protected void postLoginProcessing(javax.servlet.http.HttpSession session,
                                   java.security.Principal principal)

Called immediately after successful login.

Sub-classes may over-ride this method to perform any application specific login processing. The default implementation does nothing.

Parameters:

session - the session object.

principal - the authenticated user principal.

preLogoutProcessing

protected void preLogoutProcessing(javax.servlet.http.HttpServletRequest request)

Called immediately before logout.

Sub-classes may over-ride this method to perform any application specific logout processing. The default implementation does nothing.

Parameters:

request - the request object.

resetLoginAttempts

protected void resetLoginAttempts(javax.servlet.http.HttpSession session)

Resets the login attempts count to null.

Parameters:

session - the session object.