org.jsecurity.authc
Class AbstractAuthenticator

java.lang.Object
  org.jsecurity.authc.AbstractAuthenticator

All Implemented Interfaces:

AuthenticationListenerRegistrar, Authenticator, LogoutAware

Direct Known Subclasses:

ModularRealmAuthenticator

public abstract class AbstractAuthenticator
extends Object
implements Authenticator, LogoutAware, AuthenticationListenerRegistrar

Superclass for almost all Authenticator implementations that performs the common work around authentication attempts.

This class delegates the actual authentication attempt to subclasses but supports notification for successful and failed logins as well as logouts. Notification is sent to one or more registered AuthenticationListeners to allow for custom processing logic when these conditions occur.

In most cases, the only thing a subclass needs to do (via its doAuthenticate(org.jsecurity.authc.AuthenticationToken) implementation) is perform the actual principal/credential verification process for the submitted AuthenticationToken.

Since:

0.1

Author:

Jeremy Haile, Les Hazlewood

Constructor Summary

AbstractAuthenticator()

Method Summary

void	add(AuthenticationListener listener)
AuthenticationInfo	authenticate(AuthenticationToken token) Implementation of the Authenticator interface that functions in the following manner: Calls template doAuthenticate method for subclass execution of the actual authentication behavior.
protected abstract AuthenticationInfo	doAuthenticate(AuthenticationToken token) Template design pattern hook for subclasses to implement specific authentication behavior.
protected void	notifyFailure(AuthenticationToken token, AuthenticationException ae)
protected void	notifyLogout(PrincipalCollection principals)
protected void	notifySuccess(AuthenticationToken token, AuthenticationInfo info)
void	onLogout(PrincipalCollection principals) Callback triggered when a Subject logs out of the system.
boolean	remove(AuthenticationListener listener)
void	setAuthenticationListeners(Collection<AuthenticationListener> listeners)

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractAuthenticator

public AbstractAuthenticator()

Method Detail

setAuthenticationListeners

public void setAuthenticationListeners(Collection<AuthenticationListener> listeners)

Specified by:

setAuthenticationListeners in interface AuthenticationListenerRegistrar

add

public void add(AuthenticationListener listener)

Specified by:

add in interface AuthenticationListenerRegistrar

remove

public boolean remove(AuthenticationListener listener)

Specified by:

remove in interface AuthenticationListenerRegistrar

notifySuccess

protected void notifySuccess(AuthenticationToken token,
                             AuthenticationInfo info)

notifyFailure

protected void notifyFailure(AuthenticationToken token,
                             AuthenticationException ae)

notifyLogout

protected void notifyLogout(PrincipalCollection principals)

onLogout

public void onLogout(PrincipalCollection principals)

Description copied from interface: LogoutAware

Callback triggered when a Subject logs out of the system.

Specified by:

onLogout in interface LogoutAware

Parameters:

principals - the identifying principals of the Subject logging out.

authenticate

public final AuthenticationInfo authenticate(AuthenticationToken token)
                                      throws AuthenticationException

Implementation of the Authenticator interface that functions in the following manner:

1. Calls template doAuthenticate method for subclass execution of the actual authentication behavior.
2. If an AuthenticationException is thrown during doAuthenticate, notify any registered AuthenticationListeners of the exception and then propogate the exception for the caller to handle.
3. If no exception is thrown (indicating a successful login), notify any registered AuthenticationListeners of the successful attempt.
4. Return the AuthenticationInfo

Specified by:

authenticate in interface Authenticator

Parameters:

token - the submitted token representing the subject's (user's) login principals and credentials.

Returns:

the AuthenticationInfo referencing the authenticated user's account data.

Throws:

AuthenticationException - if there is any problem during the authentication process - see the interface's JavaDoc for a more detailed explanation.

See Also:

ExpiredCredentialsException, IncorrectCredentialsException, ExcessiveAttemptsException, LockedAccountException, ConcurrentAccessException, UnknownAccountException

doAuthenticate

protected abstract AuthenticationInfo doAuthenticate(AuthenticationToken token)
                                              throws AuthenticationException

Template design pattern hook for subclasses to implement specific authentication behavior.

Common behavior for most authentication attempts is encapsulated in the authenticate(org.jsecurity.authc.AuthenticationToken) method and that method invokes this one for custom behavior.

N.B. Subclasses should throw some kind of AuthenticationException if there is a problem during authentication instead of returning null. A null return value indicates a configuration or programming error, since AuthenticationExceptions should indicate any expected problem (such as an unknown account or username, or invalid password, etc).

Parameters:

token - the authentication token encapsulating the user's login information.

Returns:

an AuthenticationInfo object encapsulating the user's account information important to JSecurity.

Throws:

AuthenticationException - if there is a problem logging in the user.