WOSessionStore

Inherits from:
Object

Package:
com.webobjects.appserver

Class Description

WOSessionStore, an abstract superclass, offers an object abstraction for storing client state per session. The application object (WOApplication) uses an instance of a concrete WOSessionStore subclass to implement a strategy for storing and retrieving session state. You typically set the WOSessionStore during application initialization through WOApplication's setSessionStore method.

An application first creates a session (WOSession) when it receives a request without a session ID. When this first request has been handled, the application stores the WOSession object under a randomly generated session ID by invoking its own saveSessionForContext method. This method by default forwards the message to the chosen WOSessionStore and that WOSessionStore takes care of the details of saving session state. When the next request comes in for that session, the application restores the session by sending itself restoreSessionWithID, which by default is forwarded to the application's WOSessionStore. The WOSessionStore then asks the WOContext of the transaction for the session ID of the session. Based on the implementation of the WOSessionStore, the session object is located and returned.

There is one subclass of WOSessionStore implemented for the developer's convenience. A server WOSessionStore (the default) stores session state in the server, in application memory. The serverSessionStore method returns this WOSessionStore.

See the chapter "Managing State" in the WebObjects Developers Guide for the purposes, mechanisms, and limitations of session store in the server, page, and cookies.

You can create a custom session store by making a subclass of WOSessionStore. The subclass should properly implement the saveSessionForContext and restoreSessionWithID methods (using the session ID as the key for storage) and should have a public method that the application object can use to obtain an instance. Some interesting session stores could be:

A database session store that stores session data in a database as blobs, with the session ID as the primary key. This kind of WOSessionStore can be shared by many instances of the same WebObjects application, thus distributing the load (requests) among the instances.
An adaptive session store that stores session state either in cookies or on the server, depending on what the client supports.

If you create your own WOSessionStore class that generates persistent objects, you should implement an algorithm that cleans up session state after the session is inactive for a long time. The server WOSessionStore provided by WebObjects performs this clean-up properly, but the API is not yet public.

Method Types

Obtaining a session store
serverSessionStore
Checking a session in and out
checkInSessionForContext
checkOutSessionWithID
Session utilities
allSessionIDs
allSessionIDsCheckedOut
isSessionIDCheckedOut
removeSessionWithID
Saving and restoring a context
restoreSessionWithID
saveSessionForContext

Constructors

WOSessionStore

public WOSessionStore()

Description forthcoming.

Static Methods

serverSessionStore

public static WOSessionStore serverSessionStore()

Returns a WOSessionStore object that stores session state in application memory. Since this is the default storage strategy, you do not need to explicitly set the session store during application initialization if this is the strategy you want.

State storage in the server is the most secure and is the easiest to implement. You can also easily manage the amount of storage consumed by setting session timeouts, limiting the size of the page-instance cache, and page uniquing. (See "Managing State" in the WebObjects Developers Guide for details on these techniques.)

You may use the coding constructor for the session (WOSession(NSCoder)) to restore session state from the archived data.

Instance Methods

allSessionIDs

public abstract NSArray allSessionIDs()

This method should be implemented by WOSessionStore subclasses to return an NSArray containing the IDs of all sessions stored within the session store. WOSessionStore's implementation simply throws a RuntimeException.

allSessionIDsCheckedOut

public NSArray allSessionIDsCheckedOut()

Returns an NSArray containing the session IDs for all sessions currently checked out of the session store.

checkInSessionForContext

public void checkInSessionForContext(WOContext aContext)

This method calls saveSessionForContext (implemented in the concrete subclass) to save the session referred to by aContext using whatever storage technique is supported by the receiver. This method also "checks in" the session so that pending (and future) requests for the same session may procede. This method is called by WOApplication to save the session even if the session was not previously checked out via checkOutSessionWithID (that is, the session is a new session which was just created and, therefore, not restored).

checkOutSessionWithID

public WOSession checkOutSessionWithID( String aSessionID, WORequest aRequest)

This method returns a session for aSessionID if one is stored. This method calls restoreSessionWithID (implemented in the concrete subclass) to do the actual session restoration using whatever storage technique is supported by the receiver. If the session is located and restored, this method also "checks out" aSessionID so that simultaneous access to the same session is precluded. If the session is not restored, the aSessionID is not checked out.

isSessionIDCheckedOut

public boolean isSessionIDCheckedOut(String sessionID)

Returns true if the specified session ID is checked out of the session store.

removeSessionWithID

public abstract WOSession removeSessionWithID(String sessionID)

This method should be implemented by WOSessionStore subclasses to remove and return the specified session. WOSessionStore's implementation simply throws a RuntimeException.

restoreSessionWithID

public abstract WOSession restoreSessionWithID( String aSessionID, WORequest aRequest)

Implemented by a private concrete subclass to restore the current session object from a particular type of storage.

The default implementation of this method does nothing

saveSessionForContext

public abstract void saveSessionForContext(WOContext aContext)

Implemented by a private concrete subclass to save the current session object using a particular strategy for state storage. The default implementation of this method does nothing.

You may use the NSCoding interface method encodeWithCoder: to save session state to archived data.

toString

public String toString()

Returns a String containing a string representation of the receiver.