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.
WebSession()
WebSession(next.util.Coder) -- for unarchiving
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). |
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:
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
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
Returns the WebApplication object that is managing the application.
See Also: context
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
Returns the Context object for the current transaction.
See Also: Context class, application
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.
Returns an object stored in the session under a specific key.
See Also: put
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
Returns whether the WebSession object will terminate at the end of the current request-response loop.
See Also: terminate
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
Returns an object stored in the session under a specific key.
See Also: setObject
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
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.
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
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
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
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.
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
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
Causes the session to terminate after the conclusion of the current request-response loop.
See Also: isTerminating
Returns the timeout interval in seconds.
See Also: setTimeout