next.wo.WebSession

Extends:
next.util.NextObject

Implements:
next/util/Coding


CLASS AT A GLANCE

Purpose

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

Principal Attributes

Creation

WebSession()
WebSession(next.util.Coder) -- for unarchiving

Commonly Used Methods

setObject Stores an object within the WebSession under a given key.
awake Allows custom session initializations during the start of a request-response cycle.
takeValuesFromRequest
invokeAction
appendToResponse
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 next.wo.WebSession

CLASS DESCRIPTION

WebSession 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 WebSession object does is encapsulate state for a session. After the application handles a request, it stores the WebSession 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 WebSession (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 WebSession object according to the storage strategy implemented by the chosen SessionStore. (The SessionStores 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 WebSession, using the session ID as key.

To be stored and restored according to any SessionStore strategy, a WebSession must be convertable to an object archive. WebSessions are therefore asked to serialize and deserialize themselves prior to being archived and unarchived (in either binary or ASCII format). To accomplish this, the WebSession should implement the encodeWithCoder method of the Coding interface and the WebSession(next.util.Coder) constructor.

Because storage of sessions in application memory can consume large amounts of memory over time, WebSession 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 WebSession class provides several other methods useful for tasks ranging from localization to database access:



CONSTRUCTORS

WebSession

public WebSession()
public WebSession(next.util.Coder aCoder)

Initializes and returns a WebSession object. Session time out is set by default to a very long period. This constructor throws exceptions if no session ID has been assigned or if it cannot initialize the object for any other reason. Override WebSession() in compiled subclasses to perform custom initializations; as always, invoke super's default constructor as the first thing.

The WebSession(next.util.Coder) constructor returns a WebSession object after initializing it from an object archive. You can override this constructor to unarchive and reinitialize the state of instances derived from custom WebSession subclasses. This constructor, which decodes archived state, must, be implemented in conjunction with the encodeWithCoder interface method (next.util.Coding), which you must implement to encode the archived state. Decoding of objects and other data must follow the same sequence as was used in encoding. Use next.util.Coder methods to do the encoding and decoding.

See Also: Coder class, Coding interface


METHODS

appendToResponse

public void appendToResponse(next.wo.Response aResponse, next.wo.Context 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. WebSession's default implementation of this method forwards the message to the Component that represents the response page. Then, it records information about the current transaction by sending recordStatisticsForResponse and then descriptionForResponse to the StatisticsStore object.

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

See Also: invokeAction, takeValuesFromRequest


application

public next.wo.WebApplication application()

Returns the WebApplication object that is managing the application.

See Also: context


awake

public void awake()

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

See Also: sleep


context

public next.wo.Context context()

Returns the Context object for the current transaction.

See Also: Context class, application


defaultEditingContext

public next.eo.EditingContext 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.


get

public java.lang.Object get(java.lang.String aString)

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

See Also: put


invokeAction

public next.wo.Element invokeAction(next.wo.Request aRequest, next.wo.Context aContext)

WebSession objects receive this message during the middle phase of the request-response loop. During this phase, the invokeAction message is propagated through the objects of an application, most importantly, the Element 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 Component that is bound to the action. The default behavior of WebSession is to send the message to the Component object that represents the request. Compiled or scripted subclasses of WebSession can override this method to replace or supplement the default behavior with custom logic. (Scripted subclasses must use the Objective-C form of this method: invokeActionForRequest:inContext:).)

See Also: appendToResponse, takeValuesFromRequest


isTerminating

public boolean isTerminating()

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

See Also: terminate


languages

public next.util.ImmutableVector 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 WebApplication class.

See Also: setLanguages


objectForKey

public java.lang.Object objectForKey(java.lang.String aString)

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

See Also: setObject


put

public void put(java.lang.String aKey, java.lang.Object anObject)

Stores an object within the session under a given key (aKey). This method allows a reusable component to add state dynamically to any session object. This method eliminates the need for prior knowledge of the WebSession'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: get


sessionID

public java.lang.String 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

public void setLanguages(next.util.ImmutableVector anImmutableVector)

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 WebApplication class.

See Also: languages


setObject

public void setObject(java.lang.Object anObject, java.lang.String aKey)

Stores an object within the session under a given key (aKey). This method allows a reusable component to add state dynamically to any WebSession object. This method eliminates the need for prior knowledge of the WebSession'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

public void setTimeOut(double aDouble)

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

See Also: timeOut


sleep

public void sleep()

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


statistics

public next.util.ImmutableVector 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 to the Component 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


takeValuesFromRequest

public void takeValuesFromRequest(next.wo.Request aRequest, next.wo.Context aContext)

WebSession 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 WebSession is to send the message to the Component object that represents the request. Compiled or scripted subclasses of WebSession can override this method to replace or supplement the default behavior with custom logic. (Scripted subclasses must use the Objective-C form of this method: takeValuesFromRequest:inContext:).

See Also: appendToResponse, invokeAction


terminate

public void terminate()

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

See Also: isTerminating


timeOut

public double timeOut()

Returns the timeout interval in seconds.

See Also: setTimeout