Class WOSessionStore

CLASS DESCRIPTION

Inherits From:
NSObject

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 saveSession: 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 restoreSession, 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.

A few private concrete subclasses of WOSessionStore are implemented for the developer's convenience:

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 saveSession: and restoreSession 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:

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.


CLASS METHODS

cookieSessionStoreWithDistributionDomain:secure:

+ (WOSessionStore *)cookieSessionStoreWithDistributionDomain:(NSString *)aDomain secure:(BOOL)aFlag

Returns a WOSessionStore that saves session state in cookies. Cookies are implemented as the HTTP header "Set-Cookie." This header includes several key-value pairs, the most important (and the only required) one being the name of the cookie and its data value. The name is automatically generated from the creation date, while the data consists of the session object, after it's been serialized and archived into an ASCII form. This method lets you modify only two of the other key-value pairs, both of which limit access to the cookie:

Your compiled WOSession subclasses must also conform to the NSCoding protocol to archive and unarchive object state. (If you are storing the entire page in the session object, you should also implement the NSCoding protocol for the WOComponent representing the page.) The necessity for archiving results from how state is stored in cookies. A WebObjects application stores state in the page by first serializing the session object into "raw" binary data (a data object), converting the data object to ASCII, which it then puts in a cookie (an HTTP header). It restores session state by converting the ASCII archive into binary data and then deserializing the data into a WOSession object. (Scripted sessions and components do not need to implement archiving, since this is automatically done for them.)

Unlike state storage in the page, cookies do not require the use of forms. However, they do impose a severe limitation on the size of the archived session object. Cookies cannot be greater that 4000 bytes, and it is recommended that they not exceed 2000 bytes. This limitation is not only inherent in cookies but is exacerbated by the difference in how servers implement the cookie specification. Given this limitation, cookies can be best used for such things as storing keys used to fetch information from a database.


pageSessionStore

+ (WOSessionStore *)pageSessionStore

Returns a WOSessionStore that stores session state in the client, in a hidden field on an HTML page. By this means, a page carries a record of its state at the time of its creation. The hidden field, defined in the HTML specification as an input element of type "hidden," does not display its value but is instead used for passing information between the client and server. In WebObjects, hidden fields are represented by the dynamic element WOStateStorage. If you choose page WOSessionStore as your storage strategy, the page must have a form (WOForm) that contains a WOStateStorage element.

Your compiled WOSession subclasses must also conform to the NSCoding protocol to archive and unarchive object state. (If you are storing the entire page in the session object, you should also implement the NSCoding protocol for the WOComponent representing the page.) The necessity for archiving results from how state is stored in the page. A WebObjects application stores state in the page by first serializing the session object into "raw" binary data (a data object), converting the data object to ASCII, which it then puts in a hidden field in a form. It restores session state by converting the ASCII archive into binary data and then deserializing the data into a WOSession object. (Scripted sessions and components do not need to implement archiving, since this is automatically done for them.)

Page session store has several limitations to keep in mind when you select a storage strategy:



serverSessionStore

+ (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.)

Server session store does have one important drawback: It restricts balancing of the processing load among instances of the same application. Because session state is stored in the memory of a particular application instance, all requests of that session have to be routed to the same application instance.

You may use WOSession's initWithCoder: method to restore session state from the archived data.


INSTANCE METHODS

restoreSession

- (WOSession *)restoreSession

Implemented by a private concrete subclass to restore the current session object from a particular type of storage. You can always find out which session will be restored by asking the WOContext object for the ID of the current session, for example:

    WOContext *aContext = [[WOApplication application].context];

    NSString *sid = [[aContext session] sessionID];

You may use WOSession's initWithCoder: method to restore session state from the archived data.

The default implementation of this method does nothing.


saveSession:

- (void)saveSession:(WOSession *)aSession

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 method encodeWithCoder: to save session state to archived data.

The default implementation of this method does nothing.