lazyj
Class DBSession

java.lang.Object
  lazyj.DBSession

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<java.util.concurrent.Delayed>, java.util.concurrent.Delayed

public final class DBSession
extends java.lang.Object
implements java.io.Serializable, java.util.concurrent.Delayed

Web session wrapper, with a database backend.

This class will take the database settings from the file "dbsessions.properties" that is found in the folder specified by the system property "lazyj.config.folder". So make sure you have given the parameter "-Dlazyj.config.folder=/path/to/the/folder" to your java application. Or, as an alternative, you can set this parameter to a meaningful value at the very begining of your application, before it accesses any class from this framework.

Configuration parameters:

• database.enabled=boolean (default false). If true you also have to include here the options, in DBFunctions format.
• flush.memory=int (default 5). Time in minutes after which an idle session is flushed to DB, if DB backing is enabled.
• flush.memory.nodb=int (default 30). Time in minues after which an idle session is completely removed from memory, if DB backing is disabled.
• flush.db=int (default 120). Time in minutes after which an idle session is completely removed from DB.

Since:

2006-10-13

Author:

costing

See Also:

Serialized Form

Field Summary

static java.lang.String

COOKIE_NAME The cookie name to use for session ids.

Method Summary

static void	clear() Clear cached sessions
int	compareTo(java.util.concurrent.Delayed o) Implementation of Delayed
static byte[]	decodeString(java.lang.String text) Decode a text previously encoded with encodeBytes(byte[]) to the original byte array
static java.lang.String	encodeBytes(byte[] binaryContent) Convert a byte array to a String with only letters
boolean	equals(java.lang.Object o)
java.io.Serializable	get(java.lang.String sKey) Get the object that was previously associated with this key.
int	getApp() Get the application for which this session is valid.
static int	getCacheSize() Statistics function: get the number of sessions that are kept in the memory cache.
java.lang.String	getClientIP() Get the client's IP address
long	getDelay(java.util.concurrent.TimeUnit unit) Implementation of Delayed
java.lang.String	getFullname() Get the full name of the user that is associated with this session.
int	geti(java.lang.String sKey) Get the integer value associated with this key, with the default 0.
int	geti(java.lang.String sKey, int iDefault) Get the integer value associated with this key.
java.lang.String	getID() Get the unique ID for this session.
java.lang.String	getLastPage() This is the last page that the user tried to access.
static java.util.List<java.lang.String>	getPagesList(int iAppId) For statistics, get a list of usernames and the pages that they are currently visiting
java.lang.String	gets(java.lang.String sKey) Get the string value for this key.
static DBSession	getSession(ExtendedServlet tp) This is the entry point for the session engine.
static java.util.List<DBSession>	getSessionsList(int iAppId, boolean bOnlyLogged) For internal statistics, get the list of all active sessions for a given application.
java.lang.String	getUserAgent() Get user's browser
java.lang.String	getUsername() Get the account associated with this session.
int	hashCode()
void	invalidate() This method will delete all the information about this session.
void	put(java.lang.String sKey, java.io.Serializable oValue) Set a session variable, by associating a value with an unique key.
java.lang.Object	readResolve() Overriden method to set the calling page to null when deserializing.
void	setLastPage(java.lang.String s) This method should be used when you want for example to force the user to first authenticate itself then to return it to the page that it tried to access.
void	setUser(java.lang.String sUserAccount, java.lang.String sUserFullname) When the user is authenticated, you should call this method to store the username and the complete name in the session as well in separate fields in the database.
void	setUserAgent(java.lang.String s) If you want to create nice statistics for your site(s) you could track also the user's browser.

Methods inherited from class java.lang.Object

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

Field Detail

COOKIE_NAME

public static final java.lang.String COOKIE_NAME

The cookie name to use for session ids.

See Also:

Constant Field Values

Method Detail

getID

public java.lang.String getID()

Get the unique ID for this session.

Returns:

sessions's unique ID.

setLastPage

public void setLastPage(java.lang.String s)

This method should be used when you want for example to force the user to first authenticate itself then to return it to the page that it tried to access.

Parameters:

s - page to set into the session

See Also:

ExtendedServlet.getCurrentPage()

getLastPage

public java.lang.String getLastPage()

This is the last page that the user tried to access.

Returns:

last page that the user tried to access.

setUserAgent

public final void setUserAgent(java.lang.String s)

If you want to create nice statistics for your site(s) you could track also the user's browser. Not a very useful information, use it only if you think it's meaningful to you.

Parameters:

s - user's browser, you probably want to use request.getHeader("User-Agent") here.

getUserAgent

public java.lang.String getUserAgent()

Get user's browser

Returns:

user's browser identification string.

setUser

public void setUser(java.lang.String sUserAccount,
                    java.lang.String sUserFullname)

When the user is authenticated, you should call this method to store the username and the complete name in the session as well in separate fields in the database. The database info can be later used to check if the user is authenticated from other pieces of code that don't use this code base (PHP? ...)

Parameters:

sUserAccount - account name

sUserFullname - complete name

getUsername

public java.lang.String getUsername()

Get the account associated with this session.

Returns:

account name

getFullname

public java.lang.String getFullname()

Get the full name of the user that is associated with this session.

Returns:

full user name

getApp

public int getApp()

Get the application for which this session is valid.

Returns:

the appliction ID

getClientIP

public java.lang.String getClientIP()

Get the client's IP address

Returns:

the IP address

getSession

public static DBSession getSession(ExtendedServlet tp)

This is the entry point for the session engine. From the page it takes a previously set session id, if any, the application unique id and the client's IP address. With this information the session is first looked up in the internal cache, then in the database, and if it is not find in neither of them a new session ID is generated.

Sessions are cached in memory for up to 5 minutes. After this interval of inactivity, the session is removed from memory but kept in the database for two hours. If at some inactivity time the user tries to access the site and the session is still in the database, the entry will be put again in the memory cache (as expected).

The session is saved in the database only when there is some activity with it. This means that only after any of the fields is touched the following actions are taken:

• the session id actually sent to the client as a session cookie
• the session is put in the memory cache
• the session is saved in database, so it can be seen by 3rd party software and can be used to restore the sessions in the case of software restarts

If the session that is returned by this method is not written, but only checked for some values, then the corresponding object / ID will be dropped as soon as the servlet finishes with it.

Parameters:

tp - the page that is currently beeing executed

Returns:

client's session

invalidate

public void invalidate()

This method will delete all the information about this session. Use this at logout operations.

put

public void put(java.lang.String sKey,
                java.io.Serializable oValue)

Set a session variable, by associating a value with an unique key. When the information is changed the session will be flushed to the database and the client will receive the cookie ID.

Parameters:

sKey - unique key, cannot be null.

oValue - associated value. If null it will just remove a previously set value.

get

public java.io.Serializable get(java.lang.String sKey)

Get the object that was previously associated with this key.

Parameters:

sKey - unique key

Returns:

object associated with this key

gets

public java.lang.String gets(java.lang.String sKey)

Get the string value for this key. If the previously associated object was in fact a String, it is returned as it is. Otherwise the toString() method is called on the existing object. If the entry is null then the empty string is returned to the caller.

Parameters:

sKey - unique key

Returns:

string representation of this key, never null

geti

public int geti(java.lang.String sKey)

Get the integer value associated with this key, with the default 0.

Parameters:

sKey - unique key

Returns:

integer value associated with this key.

geti

public int geti(java.lang.String sKey,
                int iDefault)

Get the integer value associated with this key. If the previously set object is a Number, then intValue() of it is returned. Otherwise the toString() on that object is tried to be parsed into an integer value. If this doesn't succeed then the given default value is returned.

Parameters:

sKey - unique key

iDefault - default value to return in case of an error

Returns:

the previously set integer value, of the default value in case of an error

encodeBytes

public static final java.lang.String encodeBytes(byte[] binaryContent)

Convert a byte array to a String with only letters

Parameters:

binaryContent - array to encode

Returns:

String representation

See Also:

decodeString(String)

decodeString

public static final byte[] decodeString(java.lang.String text)

Decode a text previously encoded with encodeBytes(byte[]) to the original byte array

Parameters:

text - string to decode

Returns:

byte array

getSessionsList

public static final java.util.List<DBSession> getSessionsList(int iAppId,
                                                              boolean bOnlyLogged)

For internal statistics, get the list of all active sessions for a given application. You can specify here if you want all the active sessions or only the ones that have an associated username.

Parameters:

iAppId - application unique id (see ExtendedServlet.getApp()). Can be 0 to retrive all known sessions.

bOnlyLogged - true if you want only the authenticated user, false otherwise

Returns:

a list of active sessions (the ones that are in memory) for this app (or all)

getPagesList

public static final java.util.List<java.lang.String> getPagesList(int iAppId)

For statistics, get a list of usernames and the pages that they are currently visiting

Parameters:

iAppId - application unique id (see ExtendedServlet.getApp()). Can be 0 to retrive info from all applications.

Returns:

a list of strings like username|page for all the in-memory sessions.

getDelay

public long getDelay(java.util.concurrent.TimeUnit unit)

Implementation of Delayed

Specified by:

getDelay in interface java.util.concurrent.Delayed

Parameters:

unit - time unit in which to return the value

Returns:

how much time is left until this entry will expire

compareTo

public int compareTo(java.util.concurrent.Delayed o)

Implementation of Delayed

Specified by:

compareTo in interface java.lang.Comparable<java.util.concurrent.Delayed>

Parameters:

o - object to compare to

Returns:

sorting for these objects, to put in front the ones that expire sooner

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

readResolve

public java.lang.Object readResolve()

Overriden method to set the calling page to null when deserializing. This field will be set at a later time by {getSession(ExtendedServlet)

Returns:

exactly the current object, but with the transient field set to null

clear

public static void clear()

Clear cached sessions

getCacheSize

public static int getCacheSize()

Statistics function: get the number of sessions that are kept in the memory cache.

Returns:

number of session cache entries.