org.locomotive.loco
Class Session

java.lang.Object
  |
  +--org.locomotive.loco.Session

public class Session
extends java.lang.Object
implements javax.servlet.http.HttpSession

The Locomotive is able to keep track of a user from one page-view to the next, by sending a cookie to that user's browser and then using that cookie to identify that user. A session is an object which represents a continuous series of page-views by the same user. Since it needs to be persistent, it is stored in the database (in the loco_sessions table). A unique session is associated with a user's unique cookie. The session's ID is logged to the Server Log and the Event Log, so that the session can be used to track the user. The Session for this user is passed into all Handlers via the Handler.handleRequest (HandlerData hd) method. It is set up by the Locomotive, which finds the session in the database that is associated with the unique cookie from a user's browser. This version has changes by David Warnock. Changes are marked by //dw comments. Queries are marked by //dwq The changes are to move out all persistance logic. This class gets an instance of SessionStore from StoreFactory for the currently configured persistance store


Constructor Summary
Session()
          create a temporary anonymous session (no database persistance) with a default expiration time of one hour.
Session(java.sql.Connection conn, long session_id)
          Loads a Session from the session database using the session id.
Session(java.sql.Connection conn, java.lang.String cookie_string)
          instantiates a session using session data stored persistantly in the session database.
Session(int exp_seconds)
          create a temporary anonymous session (no database persistance)
Session(int exp_seconds, java.sql.Connection conn)
          creates a persistant session, with corresponding db entry
 
Method Summary
 void associateUser(java.sql.Connection conn, User user)
          associate a user with this session, persistantly.
 void expire(java.sql.Connection conn)
          expires this session, in both the object and the database returns false if the operation failed
 java.lang.String generateCookieString()
          returns a string suitable for usage in a HTTP cookie naming of the cookie is handled externally
 long getCreationTime()
          Returns the time in milliseconds, since 1/1/1970, when this session was created/
 java.lang.String getId()
          returns the session id (sid) of the session
 long getID()
          returns the session id (sid) of the session
 long getLastAccessedTime()
          Returns the time in milliseconds since the last request assigned to this session
 int getMaxInactiveInterval()
          Returns the maximum amount of time the session can be inactive before it is expired, in seconds.
 javax.servlet.http.HttpSessionContext getSessionContext()
          Deprecated. as the SessionContext object is thought to be a security risk.
 int getUserId()
          returns the userid of this session
 java.lang.Object getValue(java.lang.String name)
          returns a stored object keyed by the name.
 java.lang.String[] getValueNames()
          Returns an array of Strings representing the names to all the Objects stored with this session
protected static void initialize()
          Initializes static variables, like the config object and the session_objects hash.
 void invalidate()
          Expires this session
 boolean isAnonymous()
          returns a true if this session does not have a specific user associated with it.
 boolean isExpired()
          True if session has expired
 boolean isNew()
          true if the browser has not been sent by some notification about the session.
 boolean isTemporary()
          Deprecated. in favor of isNew()
 void putValue(java.lang.String name, java.lang.Object value)
          Stores the object persistently, keyed by the name.
 void removeObjects(java.sql.Connection conn)
          Removes the objects for this session, either from the cache, if it's being used, or from the database
 void removeValue(java.lang.String name)
          Removes the object keyed by the name from the persistent store.
 void resetExpiration(java.sql.Connection conn, int exp_seconds)
          Advances the expiration time of the session by exp_seconds if the session is persistant, the new time will be committed to the session database
 void setMaxInactiveInterval(int interval)
          Sets the expire time for this session to the number of seconds into the future specified by the interval.
 void storeObjects(java.sql.Connection conn)
          Stores the session_objects table in the database.
protected static void storeSessionObjects(java.sql.Connection conn)
          Clean up the session objects cache- save all the session info that is currently cached to the DB.
 java.lang.String toString()
          returns the Session cookie string
 void updateBrowserCookie(Response resp)
          takes the input response object and places in it an outbound cookie to update the browser's knowledge of the current session
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Session

public Session()
create a temporary anonymous session (no database persistance) with a default expiration time of one hour.

Session

public Session(int exp_seconds)
create a temporary anonymous session (no database persistance)
Parameters:
exp_seconds - - the time from instantiation this session will expire

Session

public Session(int exp_seconds,
               java.sql.Connection conn)
        throws FailedSessionException
creates a persistant session, with corresponding db entry
Parameters:
exp_seconds - the time, in seconds from "now" that the session will be expired
conn - a JDBC database connection with access to the Loco tables
Throws:
FailedSessionException - if there is a database error

Session

public Session(java.sql.Connection conn,
               java.lang.String cookie_string)
        throws FailedSessionException
instantiates a session using session data stored persistantly in the session database.
Parameters:
conn - a JDBC connection, opened to the session db
cookie_string - the cookie session string, as generated by generateCookieString()
Throws:
FailedSessionException - if there is a cookie parse error or database load problem

Session

public Session(java.sql.Connection conn,
               long session_id)
        throws FailedSessionException
Loads a Session from the session database using the session id.
Parameters:
conn - a JDBC connection, opened
session_id - the numerical session id.
Throws:
FailedSessionException - if the session can't be found or database load problem occurs
Method Detail

generateCookieString

public java.lang.String generateCookieString()
returns a string suitable for usage in a HTTP cookie naming of the cookie is handled externally

updateBrowserCookie

public void updateBrowserCookie(Response resp)
takes the input response object and places in it an outbound cookie to update the browser's knowledge of the current session

getUserId

public int getUserId()
returns the userid of this session

isAnonymous

public boolean isAnonymous()
returns a true if this session does not have a specific user associated with it. @see org.locomotive.loco.User.isAnonymous().

getID

public long getID()
returns the session id (sid) of the session

isTemporary

public boolean isTemporary()
Deprecated. in favor of isNew()

true if this session is temporary, not stored persistantly in the db Temporary sessions cannot have users associated with them.

isExpired

public boolean isExpired()
True if session has expired

toString

public java.lang.String toString()
returns the Session cookie string
Overrides:
toString in class java.lang.Object

getId

public java.lang.String getId()
returns the session id (sid) of the session
Specified by:
getId in interface javax.servlet.http.HttpSession

isNew

public boolean isNew()
true if the browser has not been sent by some notification about the session. New sessions cannot have users associated with them.
Specified by:
isNew in interface javax.servlet.http.HttpSession

getCreationTime

public long getCreationTime()
Returns the time in milliseconds, since 1/1/1970, when this session was created/
Specified by:
getCreationTime in interface javax.servlet.http.HttpSession

getLastAccessedTime

public long getLastAccessedTime()
Returns the time in milliseconds since the last request assigned to this session
Specified by:
getLastAccessedTime in interface javax.servlet.http.HttpSession

getMaxInactiveInterval

public int getMaxInactiveInterval()
Returns the maximum amount of time the session can be inactive before it is expired, in seconds.
Specified by:
getMaxInactiveInterval in interface javax.servlet.http.HttpSession

getSessionContext

public javax.servlet.http.HttpSessionContext getSessionContext()
Deprecated. as the SessionContext object is thought to be a security risk.

Returns the context in which this session is bound.
Specified by:
getSessionContext in interface javax.servlet.http.HttpSession

invalidate

public void invalidate()
Expires this session
Specified by:
invalidate in interface javax.servlet.http.HttpSession

putValue

public void putValue(java.lang.String name,
                     java.lang.Object value)
Stores the object persistently, keyed by the name. Notifies the object, if it is an HttpSessionBindingListener.
Specified by:
putValue in interface javax.servlet.http.HttpSession

getValue

public java.lang.Object getValue(java.lang.String name)
returns a stored object keyed by the name. Returns null if no object is stored by the key.
Specified by:
getValue in interface javax.servlet.http.HttpSession

getValueNames

public java.lang.String[] getValueNames()
Returns an array of Strings representing the names to all the Objects stored with this session
Specified by:
getValueNames in interface javax.servlet.http.HttpSession

removeValue

public void removeValue(java.lang.String name)
Removes the object keyed by the name from the persistent store. Notifies the object, if it is an HttpSessionBindingListener.
Specified by:
removeValue in interface javax.servlet.http.HttpSession

setMaxInactiveInterval

public void setMaxInactiveInterval(int interval)
Sets the expire time for this session to the number of seconds into the future specified by the interval.
Specified by:
setMaxInactiveInterval in interface javax.servlet.http.HttpSession
Returns:
the new exipre time

associateUser

public void associateUser(java.sql.Connection conn,
                          User user)
                   throws FailedSessionException
associate a user with this session, persistantly. Authentication should be handled externally
Parameters:
conn - a JDBC connection with access to the Loco tables
user - the user to be associated
Throws:
FailedSessionException - if there is a database storage problem

expire

public void expire(java.sql.Connection conn)
            throws FailedSessionException
expires this session, in both the object and the database returns false if the operation failed
Parameters:
conn - a JDBC connection with access to the Loco session tables
Throws:
FailedSessionException - if the session cannot be marked in the database

storeObjects

public void storeObjects(java.sql.Connection conn)
                  throws java.sql.SQLException
Stores the session_objects table in the database. Does nothing if caching is being used Should be called to store the session's resources after the session has been used for a request, if caching is not being used.

removeObjects

public void removeObjects(java.sql.Connection conn)
                   throws FailedSessionException
Removes the objects for this session, either from the cache, if it's being used, or from the database

resetExpiration

public void resetExpiration(java.sql.Connection conn,
                            int exp_seconds)
                     throws FailedSessionException
Advances the expiration time of the session by exp_seconds if the session is persistant, the new time will be committed to the session database
Parameters:
exp_seconds - the timespan in seconds to advance the expire time
conn - a JDBC connection with access to the Loco session tables
Throws:
FailedSessionException - if there is a database error

initialize

protected static void initialize()
Initializes static variables, like the config object and the session_objects hash. This needs to be run to decide how to cache the session objects. If the config var PERSISTENT_SESSION_OBJECTS is set to TRUE, then the session objects are retrieved from the database at the beginning of each request, and saved to the database at the end of each request. If set to FALSE, they are kept in a static hashtable and will disappear as soon as the VM is shut down.

storeSessionObjects

protected static void storeSessionObjects(java.sql.Connection conn)
Clean up the session objects cache- save all the session info that is currently cached to the DB. If we're not using the cache, return.