WebObjects 5.2

com.webobjects.appserver
Class WOSessionStore

java.lang.Object
  |
  +--com.webobjects.appserver.WOSessionStore
Direct Known Subclasses:
WOServletSessionStore

public abstract class WOSessionStore
extends Object

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. 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 method 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.

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

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.

See Also:
saveSessionForContext(WOContext), restoreSessionWithID(String, WORequest), serverSessionStore(), WOApplication.setSessionStore(WOSessionStore)

Constructor Summary
WOSessionStore()
          Creates a default WOSessionStore.
 
Method Summary
 void checkInSessionForContext(WOContext context)
          Checks in the session in context so that pending (and future) requests for the same session may proceed.
 WOSession checkOutSessionWithID(String id, WORequest aRequest)
          Checks out a session using id, which is the session id associated with the session.
 void finalize()
          Inherited finalize() method from java.lang.Object.
abstract  WOSession removeSessionWithID(String sessionID)
          Removes a WOSession instance from storage in order to make it eligible for garbage collection.
abstract  WOSession restoreSessionWithID(String sessionID, WORequest aRequest)
          Restores a WOSession associated with sessionID from storage.
abstract  void saveSessionForContext(WOContext context)
          Saves the current WOSession in context into storage.
static WOSessionStore serverSessionStore()
          Gets the default WOSessionStore object that saves and restores session states using application memory.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WOSessionStore

public WOSessionStore()
Creates a default WOSessionStore. Since WOSessionStore is an abstract class, this constructor will not be called directly but rather by subclasses.
Method Detail

checkInSessionForContext

public final void checkInSessionForContext(WOContext context)
Checks in the session in context so that pending (and future) requests for the same session may proceed. 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).

Internally, this method calls saveSessionForContext (implemented in the concrete subclass) to save the session in context using whatever storage technique is supported by the subclass.

Parameters:
context - the WOContext to retrieve the current session to be checked in
See Also:
saveSessionForContext(WOContext), checkOutSessionWithID(String, WORequest)

checkOutSessionWithID

public final WOSession checkOutSessionWithID(String id,
                                             WORequest aRequest)
Checks out a session using id, which is the session id associated with the session. This method calls restoreSessionWithID (implemented in the concrete subclass) to do the actual session restoration using whatever storage technique is supported by the subclass. If the session is located and restored, this method ensures that simultaneous access to the same session is precluded. The session should have been checked in using checkInSessionForContext.
Parameters:
id - the session id associated with the session to be checked out
aRequest - the input HTTP request for the session restoration
Returns:
the restored and checked out session if found; null otherwise
See Also:
restoreSessionWithID(String, WORequest), checkInSessionForContext(WOContext)

finalize

public void finalize()
              throws Throwable
Inherited finalize() method from java.lang.Object.
Overrides:
finalize in class Object
Throws:
the - Exception raised by this method

removeSessionWithID

public abstract WOSession removeSessionWithID(String sessionID)
Removes a WOSession instance from storage in order to make it eligible for garbage collection.

This method should be implemented by concrete WOSessionStore subclasses.

Parameters:
sessionID - the session id associated with the WOSession to be removed
Returns:
the specified WOSession if found; null otherwise

restoreSessionWithID

public abstract WOSession restoreSessionWithID(String sessionID,
                                               WORequest aRequest)
Restores a WOSession associated with sessionID from storage. This method is called from checkOutSessionWithID and is to be implemented by a concrete WOSessionStore subclass. The subclass is free to decide on the kind of suitable storage and the algorithm for restoration.

The default implementation does nothing.

Parameters:
sessionID - the session id associated with the WOSession to be restored
aRequest - the input HTTP request for session restoration
Returns:
a restored WOSession if found; null otherwise
See Also:
checkOutSessionWithID(String, WORequest)

saveSessionForContext

public abstract void saveSessionForContext(WOContext context)
Saves the current WOSession in context into storage. This method is called from checkInSessionForContext and is to implemented by a concrete WOSessionStore subclass. The subclass is free to decided on the kind of suitable storage and the algorithm for saving.

The default implementation does nothing.

Parameters:
context - the WOContext to retrieve the current session to be saved
See Also:
checkInSessionForContext(WOContext)

serverSessionStore

public static WOSessionStore serverSessionStore()
Gets the default WOSessionStore object that saves and restores session states using 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's application memory is the easiest strategy and is usually good enough for most general use. 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.

Returns:
the default WOSessionStore object that uses application memory for storage

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.