Class WOSession

Inherits From:
NSObject

Adopts:
NSCoding

NSCopying


CLASS AT A GLANCE

Purpose

WOSession objects encapsulate the state of a session--a period during which a user is accessing a WebObjects application. WOSessions are stored between requests from a client, making that state persistent throughout a session. The application stores WOSession objects through a WOSessionStore object.

Principal Attributes

Creation

alloc/init
initWithCoder: -- for unarchiving

Commonly Used Methods

setObject:forKey: Stores an object within the WOSession under a given key.
awake Allows custom session initializations during the start of a request-response cycle.
takeValuesFromRequest:inContext:
invokeActionForRequest:inContext:
appendToResponse:inContext:
These three methods allow custom session logic during the value-extraction, action-invocation, and HTML-generation phases of the request-response loop.
setTimeOut: Sets the session time-out period in seconds.
setLanguages: Sets an ordered list of preferred languages for the client (used in localization).




CLASS DESCRIPTION

WOSession objects represent sessions, periods during which access to a WebObjects application and its resources is granted to a particular client (typically a browser user). An application can have many concurrent sessions, each with its own special "view" of the application and its own set of data values. For instance, one client could be accessing a "catalog" application, where that client is going from page to page, filling a virtual shopping cart with items for purchase. Another client might be accessing the same application at the same time, but that person might have different items in his or her shopping cart.

Perhaps the most important thing a WOSession object does is encapsulate state for a session. After the application handles a request, it stores the WOSession until the next request of the session occurs. All the information that is important for maintaining continuity throughout the session is preserved. And the integrity of session data is maintained as well; the data of a session not only persists between requests but is kept separate from that of all other sessions.

When you develop an application, you identify data with session-wide scope by declaring instance variables in your subclass of WOSession (or, for scripted applications, in Session.wos). Then, before the end of a cycle of the request-response loop, ensure that the instance variables hold current session values.

The application uses a session ID to identify a session object. Upon receiving the first request of a session, the application assigns a session ID (a unique, randomly generated number) to the session. The session ID appears in the URL between the application name and the page name.

At the end of each cycle of the request-response loop, the application stores the WOSession object according to the storage strategy implemented by the chosen WOSessionStore. (The WOSessionStores provided by WebObjects store state in application memory, in the page, and in "cookies.") When the application receives the next request of the session, it restores the WOSession, using the session ID as key.

To be stored and restored according to any WOSessionStore strategy, a WOSession must be convertable to an object archive. WOSessions are therefore asked to serialize and deserialize themselves prior to being archived and unarchived (in either binary or ASCII format). To accomplish this, the WOSession should implement the encodeWithCoder: and initWithCoder: methods of the NSCoding protocol.

Because storage of sessions in application memory can consume large amounts of memory over time, WOSession includes methods for controlling the lifespan of session objects. The setTimeOut: method sets a period of inactivity after which the session is terminated. The terminate method explicitly ends a session.

The WOSession class provides several other methods useful for tasks ranging from localization to database access:



INSTANCE METHODS

appendToResponse:inContext:

- (void)appendToResponse:(WOResponse *)aResponse inContext:(WOContext *)aContext

This method is invoked during the phase of the request-response loop during which the objects associated with a response page append their HTML content to the response. WOSession's default implementation of this method forwards the message to the WOComponent that represents the response page. Then, it records information about the current transaction by sending recordStatisticsForResponse:inContext: and then descriptionForResponse:inContext: to the WOStatisticsStore object.

Compiled or scripted subclasses of WOSession can override this method to replace or supplement the default behavior with custom logic.

See Also: - invokeActionForRequest:inContext:, - takeValuesFromRequest:inContext:


application

- (WOApplication *)application

Returns the WOApplication object that is managing the application.

See Also: - context


awake

- (void)awake

Invoked at the beginning of a WOSession's involvement in a cycle of the request-response loop, giving the WOSession an opportunity to initialize its instance variables or perform setup operations. The default implementation does nothing.

See Also: - sleep


context

- (WOContext *)context

Returns the WOContext object for the current transaction.

See Also: WOContext class, - application


defaultEditingContext

- (EOEditingContext *)defaultEditingContext

Returns the default EOEditingContext object for the session. The method creates the editing context the first time that it is invoked and caches it for subsequent invocations. There is thus only one unique EOEditingContext instance per session. The instance is initialized with the default object store coordinator as the parent object store.


init

- (id)init

Initializes a WOSession object. Session time-out is set by default to a very long period. This method throws exceptions if no session ID has been assigned or if it cannot initialize the object for any other reason. Override init in compiled subclasses to perform custom initializations; as always, invoke the superclass method as the first thing.


invokeActionForRequest:inContext:

- (WOElement *)invokeActionForRequest:(WORequest *)aRequest inContext:(WOContext *)aContext

WOSession objects receive this message during the middle phase of the request-response loop. During this phase, the invokeActionForRequest:inContext: message is propagated through the objects of an application, most importantly, the WOElement objects of the request page. The dynamic element on which the user has acted (by, for example, clicking a button) responds by triggering the method in the request WOComponent that is bound to the action. The default behavior of WOSession is to send the message to the WOComponent object that represents the request. Compiled or scripted subclasses of WOSession can override this method to replace or supplement the default behavior with custom logic.

See Also: - appendToResponse:inContext:, - takeValuesFromRequest:inContext:


isTerminating

- (BOOL)isTerminating

Returns whether the WOSession object will terminate at the end of the current request-response loop.

See Also: - terminate


languages

- (NSArray *)languages

Returns the list of languages supported by the session. The order of language strings (for example, "French") indicates the preferred order of languages. For details, see "Localization" in the description of the WOApplication class.

See Also: - setLanguages:


objectForKey:

- (id)objectForKey:(NSString *)aKey

Returns an object stored in the session under a specific key.

See Also: - setObject:forKey:


sessionID

- (NSString *)sessionID

Returns the unique, randomly generated number that identifies the session object. The session ID occurs in the URL between the application name and the current page name.


setLanguages:

- (void)setLanguages:(NSArray *)someLanguages

Sets the languages for which the session is localized. The ordering of language strings in the array determines the order in which the application will search Language.lproj directories for localized strings, images, and component definitions. Searches can take place at both the application level (.woa) and the component level (.wo). For further details, see "Localization" in the description of the WOApplication class.

See Also: - languages


setObject:forKey:

- (void)setObject:(id)anObject forKey:(NSString *)aKey

Stores an object within the session under a given key (aKey). This method allows a reusable component to add state dynamically to any WOSession object. This method eliminates the need for prior knowledge of the WOSession's instance variables. A suggested mechanism for generating a unique key prefix for a given subcomponent is to concatenate the component's name and its element ID. For a specific component instance, such a prefix should remain unique and invariant within a session.

See Also: - objectForKey:


setTimeOut:

- (void)setTimeOut:(NSTimeInterval)aTimeInterval

Set the session time-out in seconds. When a session remains inactive--that is, the application receives no request for this session--for a period longer than the time-out setting, the session will terminate, resulting in the deallocation of the WOSession object. By default, the session time-out is set to a very long interval.

See Also: - timeOut


sleep

- (void)sleep

Invoked at the conclusion of each request-response loop in which the session is involved, giving the WOSession the opportunity to deallocate objects initialized in the awake method. The default WOSession implementation does nothing.


statistics

- (NSArray *)statistics

Returns a list of the pages accessed by this session, ordered from first accessed to last. For each page, the string stored is obtained by sending descriptionForResponse:inContext: to the WOComponent object. By default, this returns the component's name. If the application keeps a CLFF log file, this list is recorded in the log file when the session terminates.

See Also: - appendToResponse:inContext:


takeValuesFromRequest:inContext:

- (void)takeValuesFromRequest:(WORequest *)aRequest inContext:(WOContext *)aContext

WOSession objects receive this message during the first phase of the request-response loop. During this phase, the dynamic elements associated with the request page extract any user input and assign the values to the appropriate component variables. The default behavior of WOSession is to send the message to the WOComponent object that represents the request. Compiled or scripted subclasses of WOSession can override this method to replace or supplement the default behavior with custom logic.

See Also: - appendToResponse:inContext:, - invokeActionForRequest:inContext:


terminate

- (void)terminate

Causes the session to terminate after the conclusion of the current request-response loop.

See Also: - isTerminating


timeOut

- (NSTimeInterval)timeOut

Returns the timeout interval in seconds.

See Also: - setTimeout: