com.uwyn.rife.authentication
Interface SessionManager

All Known Implementing Classes:

DatabaseSessions, MemorySessions, PurgingSessionManager

public interface SessionManager

This interface defines the methods that classes with SessionManager functionalities have to implement.

A SessionManager is reponsible for handling all tasks related to the lifetime of a session in which a user is successfully authenticated.

This kind of session doesn't provide any state persistance across requests and doesn't store any additional business data on the server-side. It merely provides a unique authentication id which can be used to identify a successfully authenticated user.

For safety's sake, sessions time out after a certain period of inactivity and their validity is bound only to a unique user id and a host ip. No assumptions are being made about the actual meaning or structure of a 'user'. A unique numeric identifier is all that's required.

Since:

1.0

Version:

$Revision: 3643 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

See Also:

SessionValidator

Method Summary

boolean	continueSession(String authId) Continues an already active session.
long	countSessions() Counts the number of active sessions.
void	eraseAllSessions() Removes all available sessions.
boolean	eraseSession(String authId) Removes all traces of an authentication session.
boolean	eraseUserSessions(long userId) Removes all traces of all authentication sessions for a particular user.
boolean	getRestrictHostIp() Obtains the restriction policy of the authentication ID with regards to the user's host IP.
long	getSessionDuration() Obtains the maximum time that a user can stay inactive before an active session becomes invalid.
long	getSessionUserId(String authId) Retrieves the id of a user that has access to a particular session.
boolean	isSessionValid(String authId, String hostIp) Verifies if a session is valid and still active.
boolean	listSessions(ListSessions processor) Lists the active sessions.
void	purgeSessions() Removes all sessions that are inactive.
void	setRestrictHostIp(boolean flag) Sets the restriction policy of the authentication ID with regards to the user's host IP.
void	setSessionDuration(long milliseconds) Sets the maximum time that a user can stay inactive before an active session becomes invalid.
String	startSession(long userId, String hostIp, boolean remembered) Starts a new session.
boolean	wasRemembered(String authId) Checks if a session was previously automatically created from remembered data.

Method Detail

getSessionDuration

long getSessionDuration()

Obtains the maximum time that a user can stay inactive before an active session becomes invalid.

Returns:

The maximum time of inactivity in milliseconds.

Since:

1.0

setSessionDuration

void setSessionDuration(long milliseconds)

Sets the maximum time that a user can stay inactive before an active session becomes invalid.

Parameters:

milliseconds - The maximum time of inactivity in milliseconds.

Since:

1.0

getRestrictHostIp

boolean getRestrictHostIp()

Obtains the restriction policy of the authentication ID with regards to the user's host IP.

The default is false, or no restriction.

Returns:

true if the authentication is restricted to one host IP; or

false if the authentication ID can be used with any host IP

Since:

1.0

setRestrictHostIp

void setRestrictHostIp(boolean flag)

Sets the restriction policy of the authentication ID with regards to the user's host IP.

The default is false, or no restriction.

Parameters:

flag - true to activate the host IP restriction; or

false otherwise

Since:

1.0

startSession

String startSession(long userId,
                    String hostIp,
                    boolean remembered)
                    throws SessionManagerException

Starts a new session.

Parameters:

userId - The id that uniquely identifies the user that is allowed to use this session.

hostIp - The ip address of the host from which the user accesses the application.

remembered - Indicates whether the session is started through remember me or from scratch.

Returns:

A String that uniquely identifies the authentication session that was just started.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is started. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

isSessionValid

boolean isSessionValid(String authId,
                       String hostIp)
                       throws SessionManagerException

Verifies if a session is valid and still active.

Parameters:

authId - The unique id of the authentication session that needs to be verified.

hostIp - The ip address of the host from which the user accesses the application.

Returns:

true if a valid active session was found; or

false if this was not possible.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is verified. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

continueSession

boolean continueSession(String authId)
                        throws SessionManagerException

Continues an already active session. This means that the inactivity time-out is reset to the maximal value. This is typically called each time a user accesses an application.

Parameters:

authId - The unique id of the authentication session that needs to be continued.

Returns:

true if the session was successfully continued; or

false if this was not possible (ie. the session couldn't be found).

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is continued. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

eraseSession

boolean eraseSession(String authId)
                     throws SessionManagerException

Removes all traces of an authentication session. This makes the session instantly inactive and invalid.

Parameters:

authId - The unique id of the authentication session that needs to be erased.

Returns:

true if the session was successfully erased; or

false if this was not possible (ie. the session couldn't be found).

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is erased. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

wasRemembered

boolean wasRemembered(String authId)
                      throws SessionManagerException

Checks if a session was previously automatically created from remembered data.

Parameters:

authId - The unique id of the authentication session that needs to be erased.

Returns:

true if the session was created automatically from remembered data; or

false if it was created from full credentials or if the session couldn't be found.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is erased. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

eraseUserSessions

boolean eraseUserSessions(long userId)
                          throws SessionManagerException

Removes all traces of all authentication sessions for a particular user. This makes all sessions of this user instantly inactive and invalid.

Parameters:

userId - The id that uniquely identifies the user whose sessions are to be erased.

Returns:

true if the sessions were successfully erased; or

false if this was not possible (ie. no sessions couldn't be found).

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is erased. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

eraseAllSessions

void eraseAllSessions()
                      throws SessionManagerException

Removes all available sessions. This makes all sessions instantly invalid and inactive for all users.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is erased. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

getSessionUserId

long getSessionUserId(String authId)
                      throws SessionManagerException

Retrieves the id of a user that has access to a particular session.

Parameters:

authId - The unique id of the authentication session for which the user needs to be looked up.

Returns:

A long >= 0 that corresponds to the user id that has access to the session; or

-1 if the session couldn't be found.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when user id of a session is retrieved. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

purgeSessions

void purgeSessions()
                   throws SessionManagerException

Removes all sessions that are inactive. This means that all sessions where the inactivity time has been exceeded, will be removed.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is purged. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

countSessions

long countSessions()
                   throws SessionManagerException

Counts the number of active sessions.

Returns:

The number of active sessions.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when a session is counted. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0

listSessions

boolean listSessions(ListSessions processor)
                     throws SessionManagerException

Lists the active sessions.

Parameters:

processor - The row processor that will be used to list the active sessions.

Returns:

true if active sessions were found; or

false if no session was active.

Throws:

SessionManagerException - An undefined number of exceptional cases or error situations can occur when session are listed. They are all indicated by throwing an instance of SessionManagerException. It's up to the implementations of this interface to give more specific meanings to these exceptions.

Since:

1.0