[an error occurred while processing this directive] PATH Documentation > WebObjects 4.5 > WebObjects Reference

WOSession

Inherits from: NSObject

Package: 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 their 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:

WOSession objects can interject custom session behavior into the request-response loop by implementing the request-handling methods ( takeValuesFromRequest, invokeAction, and appendToResponse) as well as awake and sleep.
For database access, the defaultEditingContext method gives each WOSession object in an application its own Enterprise Objects editing context.
An object in an application doesn't have to know which instance variables its WOSession holds in order to store session values. With the setObjectForKey and objectForKey methods it can store and retrieve values as needed. This mechanism is especially useful for reusable components.
An application's WOSession objects also play a role in localization. Through the setLanguages method you can store a list of the languages supported by the application. The sequence of language strings in the list indicates the order of language preference for a particular session. Several resource-access methods in WOResourceManager, WOApplication, and WOComponent refer to the languages array when they locate such things as localized strings, images, and sounds.
WOSession objects also allow you to affect load balancing with the setDistributionEnabled method; if the flag set by this method is false (the default), transactions of the session are restricted to a single application instance. If this the case, the application instance number as well as the application host name are appended to the URL.

Method Types

Constructor

WOSession

Obtaining attributes

domainForIDCookies

expirationDateForIDCookies

isDistributionEnabled

sessionID

storesIDsInCookies

storesIDsInURLs

Setting attributes

setDistributionEnabled

setStoresIDsInCookies

setStoresIDsInURLs

Terminating

terminate

isTerminating

timeOut

setTimeOut

Localization

languages

setLanguages

Managing component state

setObjectForKey

objectForKey

removeObjectForKey

Managing enterprise objects

defaultEditingContext

setDefaultEditingContext

Handling requests

appendToResponse

awake

context

invokeAction

sleep

takeValuesFromRequest

Statistics

statistics

Debugging

debugString

logString

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

Static Methods

debugString

public static void debugString(String aFormatString)

Prints a message to the standard error device (stderr), if WODebuggingEnabled is true. The message can include formatted variable data using String's concatenation feature.

You control whether this method displays output with the WODebuggingEnabled user default option. If WODebuggingEnabled is true, then the debugString messages display their output. If WODebuggingEnabled is false, the debugString messages don't display their output.

logString

public static void logString(String aString)

Prints a message to the standard error device (stderr). The message can include formatted variable data using String's concatenation feature, for example:

int i = 500;
float f = 2.045;
WOApplication.logString("Amount = " + i + ", Rate = " + f ", Total = " + i*f);

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's parent object store is initialized to the default parent object store.

domainForIDCookies

public String domainForIDCookies()

Returns the path that is passed when creating a rendezvous cookie for the application. This path is lazily created the first time it is used from the current request's adaptorPrefix and the application name (including the ".woa" extension).

expirationDateForIDCookies

public NSDate expirationDateForIDCookies()

Returns when session and instance ID cookies expire. By default, no expiration date is set and this method returns null. Override this method if you want to return some other time, such as the session expiration date.

Different applications can override this method to enforce different behavior:

A typical online banking application might use cookies and set the timeout to a very short amount of time (two minutes, for example), so that if the client doesn't interact with the browser and no request is made of the server, the client's session is timed out. This could be easily enforced on both the client-by setting the cookie timeout-and on the server from within the session object.
A site wishing to personalize its pages based upon a user ID might set the timeout far into the distant future so that even when a client shuts down their browser, the cookie will still be there when they come back with a bookmarked URL.
Sites that want you to log in each time you visit could store the user ID in a cookie and then set the expiration date on the cookie to nil so that the cookie will go away whenever the client quits their browser.

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

objectForKey

public Object objectForKey(String key)

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

See Also: setObjectForKey

removeObjectForKey

public void removeObjectForKey(String key)

Removes the object stored in the session under the specified key.

restorePageForContextID

public WOComponent restorePageForContextID(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.

sessionID

public 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(com.apple.yellow.eocontrol.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

setObjectForKey

public void setObjectForKey(Object anObject, String key)

Stores an object within the session under a given key. 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

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 setStoresIDsInURLs(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 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 String WOSessionDidRestoreNotification

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

WOSessionDidTimeOutNotification

public static final String WOSessionDidTimeOutNotification

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