PATH  WebObjects 4.0 Documentation > WebObjects Framework Reference



WOSession

Inherits From:
NSObject

Inherits From:
com.apple.yellow.webobjects


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). 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 string) 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. 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:


Method Types

Constructor
WOSession
Obtaining attributes
isDistributionEnabled
sessionID
storesIDsInCookies
storesIDsInURLs
Setting attributes
setDistributionEnabled
setStoresIDsInCookies
setStoresIDsInURLs
Terminating
terminate
isTerminating
timeOut
setTimeOut
Localization
languages
setLanguages
Managing enterprise objects
defaultEditingContext
setDefaultEditingContext
Handling requests
appendToResponse
awake
context
invokeAction
sleep
takeValuesFromRequest
Statistics
statistics
Page Management
savePage
restorePageForContextID

Constructors


WOSession

public WOSession()

Returns an initialized 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. The isDistributionEnabled flag is set to false, meaning that each transaction will be assigned to an application instance specified in a configuration file for load balancing


Instance Methods


appendToResponse

public void appendToResponse(WOResponse aResponse, 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 and then descriptionForResponse 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: invokeAction, takeValuesFromRequest


awake

public 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

public WOContext context()

Returns the WOContext object for the current transaction.

See also: WOContext class


defaultEditingContext

public com.apple.yellow.eocontrol.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 only one unique EOEditingContext instance per session. The instance is initialized with the default object store coordinator as the parent object store.


invokeAction

public WOElement invokeAction(WORequest aRequest, 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, takeValuesFromRequest


isDistributionEnabled

public boolean isDistributionEnabled()

Returns whether state distribution among multiple application instances is enabled. Returns false by default since the default WOSessionStore (state in the server) does not allow distribution. If this flag is disabled, a specific application instance (whose identifying number is embedded in the URL) is assigned to the session.

See also: setDistributionEnabled


isTerminating

public boolean isTerminating()

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

See also: terminate


languages

public 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. This is initialized from the users's browser preferences unless explicitly set with setLanguages. For details, see "Localization" in the WebObjects programming topics.

See also: setLanguages


restorePageForContextID

public WOComponent restorePageForContextID(java.lang.String contextID)

Returns a page instance stored in the session page cache. The key to the stored instance is its context ID, which derives from the transaction's WOContext or WORequest objects. This method returns null if restoration is impossible.

See also: savePage


savePage

public void savePage(WOComponent aPage)

Saves the page instance aPage in the session page cache. The context ID for the current transaction is made the key for obtaining this instance in the cache using restorePageForContextID.


savePageInPermanentCache

pubic void savePageInPermanentCache(WOComponent aPage)

Puts aPage into a separate page cache. This cache is searched first when attempting to restore the page the next time its requested. This effectively makes aPage live for the duration of the application regardless of the size of your page cache. This is useful whe you are using frames and its possible for a page of controls to be bumped from the page cache.

See also: permanentPageCacheSize (WOApplication), setPermanentPageCacheSize (WOApplication)


sessionID

public java.lang.String sessionID()

Returns the unique, randomly generated string that identifies the session object. The session ID occurs in the URL after the request handler key.


setDefaultEditingContext

public void setDefaultEditingContext(EOEditingContext editingContext)

Sets the editing context to be returned by defaultEditingContext. This can be used to set an editing context initialized with a different parent object store than the default. This is useful when, for instance, each session needs its own login to the database. Once a default editing context has been established, you may not call setDefaultEditingContext: again. Therefore, to provide your own default editing context, you must call setDefaultEditingContext: before ever calling defaultEditingContext since that will lazily establish an editing context.

See also: defaultEditingContext


setDistributionEnabled

public void setDistributionEnabled(boolean aFlag)

Enables or disables the distribution mechanism that effects load balancing among multiple application instances. When disabled (the default), generated URLs include the application instance number; the adaptor uses this number to route the request to the specific application instance based on information in the configuration file. When this flag is enabled, generated URLs do not contain the application instance number, and thus transactions of a session are handled by whatever application instance is available.

See also: isDistributionEnabled


setLanguages

public void setLanguages(NSArray languages)

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 languages.lproj directories for localized strings, images, and component definitions.

See also: languages


setStoresIDsInCookies

public void setStoresIDsInCookies(boolean flag)

Enables or disables the cookie mechanism. Two cookies are created for you when enabled: a session ID cookie with the name "wosid," and an instance ID cookie with the name "woinst." By default, the cookie mechanism is disabled.


setStoresIDsInURLs

public void setStoresIDsInCookies(boolean flag)

Enables or disables the storing of session and instance IDs in URLs. By default, IDs are stored in URLs.


setTimeOut

public void setTimeOut(double seconds)

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 time-out setting, the session will terminate, resulting in the deallocation of the WOSession object. By default, the session time-out is set from the WOApplication method sessionTimeout.

See also: timeOut


sleep

public 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

public 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 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


storesIDsInCookies

public boolean storesIDsInCookies()

Returns whether the cookie mechanism for storing session and instance IDs is enabled. The cookie mechanism is disabled by default.


storesIDsInURLs

public boolean storesIDsInURLs()

Returns whether the URL mechanism for storing session IDs and instance IDs is enabled. The URL mechanism is enabled by default.


takeValuesFromRequest

public void takeValuesFromRequest(WORequest aRequest, 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, 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


Notifications


WOSessionDidCreateNotification

public static final java.lang.String WOSessionDidCreateNotification

Sent at the the end of the session initiation (including awake). The object of the notification is the session instance


WOSessionDidRestoreNotification

public static final java.lang.String WOSessionDidCreateNotification

Sent after the sesion is fully restored (including awake). The object of the notification is the session instance.


WOSessionWillTimeoutNotification

public static final java.lang.String WOSessionDidCreateNotification

Sent when a session times out but before it is released. The session ID is the object of the notification.





Copyright © 1998, Apple Computer, Inc. All rights reserved.