Package rife.authentication

Interface SessionManager

All Known Implementing Classes:

DatabaseSessions, MemorySessions

public interface SessionManager

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

A SessionManager is responsible 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 persistence 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. 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

See Also:

• SessionValidator

Method Summary

Modifier and Type	Method	Description
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	getRestrictAuthData()	Obtains the restriction policy of the authentication ID in regard to the user's auth data.
long	getSessionDuration()	Obtains the maximum time that a user can stay inactive before an active session becomes invalid.
int	getSessionPurgeFrequency()	Obtains the frequency at which the purging will happen in relationship to the scale.
int	getSessionPurgeScale()	Obtains the scale at which the purging will happen in relationship to the frequency.
long	getSessionUserId(String authId)	Retrieves the id of a user that has access to a particular session.
boolean	isSessionValid(String authId, String authData)	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	setRestrictAuthData(boolean flag)	Sets the restriction policy of the authentication ID in regard to the user's auth data.
void	setSessionDuration(long milliseconds)	Sets the maximum time that a user can stay inactive before an active session becomes invalid.
void	setSessionPurgeFrequency(int frequency)	Set the frequency at which the purging will happen in relationship to the scale.
void	setSessionPurgeScale(int scale)	Set the scale at which the purging will happen in relationship to the frequency.
String	startSession(long userId, String authData, boolean remembered)	Starts a new session.
boolean	wasRemembered(String authId)	Checks if a session was previously automatically created from remembered data.

Method Details

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

getRestrictAuthData

boolean getRestrictAuthData()

Obtains the restriction policy of the authentication ID in regard to the user's auth data.

The default is false, or no restriction.

Returns:

true if the authentication is restricted to one auth data; or

false if the authentication ID can be used with any auth data

Since:

1.0

setRestrictAuthData

void setRestrictAuthData(boolean flag)

Sets the restriction policy of the authentication ID in regard to the user's auth data.

The default is false, or no restriction.

Parameters:

flag - true to activate the auth data restriction; or

false otherwise

Since:

1.0

getSessionPurgeFrequency

int getSessionPurgeFrequency()

Obtains the frequency at which the purging will happen in relationship to the scale.

This defaults to RifeConfig.AuthenticationConfig.getSessionPurgeFrequency().

Returns:

the purge frequency

Since:

1.0

See Also:

• setSessionPurgeFrequency(int)
• getSessionPurgeScale()
• setSessionPurgeScale(int)

setSessionPurgeFrequency

void setSessionPurgeFrequency(int frequency)

Set the frequency at which the purging will happen in relationship to the scale.

By default, the frequency and scale respectively are 20 and 1000, which means that the purging will have once every fifty times the authentication sessions are accessed.

Parameters:

frequency - the purge frequency

Since:

1.0

See Also:

• getSessionPurgeFrequency()
• getSessionPurgeScale()
• setSessionPurgeScale(int)

getSessionPurgeScale

int getSessionPurgeScale()

Obtains the scale at which the purging will happen in relationship to the frequency.

This defaults to RifeConfig.AuthenticationConfig.getSessionPurgeScale().

Returns:

the purge scale

Since:

1.0

See Also:

• getSessionPurgeFrequency()
• setSessionPurgeFrequency(int)
• setSessionPurgeScale(int)

setSessionPurgeScale

void setSessionPurgeScale(int scale)

Set the scale at which the purging will happen in relationship to the frequency.

By default, the frequency and scale respectively are 20 and 1000, which means that the purging will have once every fifty times the authentication sessions are accessed.

Parameters:

scale - the purge scale

Since:

1.0

See Also:

• getSessionPurgeFrequency()
• setSessionPurgeFrequency(int)
• getSessionPurgeScale()

startSession

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

Starts a new session.

Parameters:

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

authData - The authentication data that is associated with the session.

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 authData)
                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.

authData - The authentication data that is associated with the session.

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 (i.e. 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 (i.e. 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 (i.e. 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