WOSession

Inherits from:
Object

Implements:
Cloneable
Serializable
NSKeyValueCoding
NSKeyValueCoding.ErrorHandling NSKeyValueCodingAdditions

Package:
com.webobjects.appserver

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 convertible 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.

Interfaces Implemented

NSKeyValueCoding
takeValueForKey
valueForKey

NSKeyValueCodingAdditions
takeValueForKeyPath
valueForKeyPath

NSKeyValueCoding.ErrorHandling
handleQueryWithUnboundKey
handleTakeValueForUnboundKey
unableToSetNullForKey

Method Types

Constructor
WOSession
Obtaining attributes
domainForIDCookies
expirationDateForIDCookies
isDistributionEnabled
sessionID
storesIDsInCookies
storesIDsInURLs
Setting attributes
allowedToViewStatistics
setDistributionEnabled
setStoresIDsInCookies
setStoresIDsInURLs
Terminating
terminate
isTerminating
timeOut
timeOutMillis
setTimeOut
Localization
languages
setLanguages
Managing component state
setObjectForKey
objectForKey
removeObjectForKey
Managing enterprise objects
defaultEditingContext
setDefaultEditingContext
Handling requests
appendToResponse
awake
context
finalize
invokeAction
sleep
takeValuesFromRequest
Statistics
statistics
Debugging
debugString
logString
Page Management
savePage
restorePageForContextID
Validation
validateEventsLogin
validateStatisticsLogin
validationFailedWithException
Other
allowedToViewEvents
canAccessFieldsDirectly
timeOutForIDCookies

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

public WOSession(String aSessionID)

This constructor initializes a newly-instantiated session object with the provided session ID (pass the session ID as a String). This constructor throws a RuntimeException if a session ID isn't provided or if the session object cannot be properly initialized.

Static Methods

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

WOSession's implementation of this static method returns true, indicating that key/value coding is allowed to access fields in this object if an appropriate method isn't present.

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

allowedToViewStatistics

public boolean allowedToViewStatistics()

Returns true if clients of this session are allowed to view session statistics. If statistics aren't being gathered, or if a password must be supplied prior to viewing those statistics and the client hasn't supplied the proper password, this method returns false. By default, sessions don't allow statistics to be viewed.

allowedToViewEvents

public boolean allowedToViewEvents()

Description forthcoming.

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

clone

public Object clone()

Conformance to Cloneable.

context

public WOContext context()

Returns the WOContext object for the current transaction.

See Also: WOContext class

defaultEditingContext

public com.webobjects.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 NSTimestamp expirationDateForIDCookies()

This method is deprecated. Do not use it.

finalize

public void finalize() throws Throwable

WOSession's finalizer. This method disposes of the session's editing context, if it has one. It throws Throwable if a non-recoverable error occurs during the disposal of the editing context.

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value, String key)

Conformance to NSKeyValueCoding.ErrorHandling.

invokeAction

public WOActionResults 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 when 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 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.webobjects.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.

takeValueForKey

public void takeValueForKey(Object value, String key)

Conformance to NSKeyValueCoding.

takeValueForKeyPath

public void takeValueForKeyPath(Object value, String keyPath)

Conformance to NSKeyValueCodingAdditions.

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