PATH
Documentation > WebObjects 4.5 >
WebObjects Reference
Inherits
from: NSObject
Declared in: WebObjects/WOSession.h
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:
- WOSession objects can interject custom session
behavior into the request-response loop by implementing the request-handling
methods ( takeValuesFromRequest:inContext:, invokeActionForRequest:inContext:,
and appendToResponse:inContext:) 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 setObject:forKey: 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 NO (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.
Adopted Protocols
NSCoding
- encodeWithCoder:
- initWithCoder:
NSCopying
- copy
- copyWithZone:
Method Types
- Creating
- - init
- Obtaining attributes
- - domainForIDCookies
- - expirationDateForIDCookies
- - isDistributionEnabled
- - sessionID
- - storesIDsInCookies
- - storesIDsInURLs
- Setting attributes
- - setDistributionEnabled:
- - setStoresIDsInCookies:
- - setStoresIDsInURLs:
- Terminating
- - terminate
- - isTerminating
- - timeOut
- - setTimeOut:
- Localization
- - languages
- - setLanguages:
- Managing component state
- - setObject:forKey:
- - objectForKey:
- - removeObjectForKey:
- Managing enterprise objects
- - defaultEditingContext
- - setDefaultEditingContext:
- Handling requests
- - appendToResponse:inContext:
- - awake
- - context
- - invokeActionForRequest:inContext:
- - sleep
- - takeValuesFromRequest:inContext:
- Statistics
- - statistics
- Debugging
- - debugWithFormat:
- Page Management
- - savePage:
- - restorePageForContextID:
Instance Methods
- (void)appendToResponse:(WOResponse
*)aResponse
inContext:(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:inContext: and
then descriptionForResponse:inContext: 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: - invokeActionForRequest:inContext:, - takeValuesFromRequest:inContext:
- (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
- (WOContext *)context
Returns the WOContext object for the current
transaction. See Also: WOContext class
- (void)debugWithFormat:(NSString
*)aFormatString,...
Prints a message to the standard error device
(stderr), if WODebuggingEnabled is YES.
The message can include formatted variable data using printf-style
conversion specifiers, Note that in WebScript, all variables are
objects, so the only conversion specifier allowed is %@.
In compiled Objective-C code, all printf conversion
specifiers are allowed. You control whether this method displays
output with the WODebuggingEnabled user
default option. If WODebuggingEnabled is
YES, then the debugWithFormat: messages
display their output. If WODebuggingEnabled is
NO, the debugWithFormat: messages don't
display their output.
- (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.
- (NSString *)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).
- (NSDate *)expirationDateForIDCookies
Returns when session and instance ID cookies
expire. By default, no expiration date is set and this method returns nil.
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 his browser, the cookie will still be there
when he comes 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.
- (id)init
Initializes a WOSession object. Session timeout
is set from the WOApplication method sessionTimeout. This method throws
exceptions if no session ID has been assigned or if it cannot initialize
the object for any other reason. Override init in
compiled subclasses to perform custom initializations; as always, invoke
the superclass method as the first thing.
- (WOElement *)invokeActionForRequest:(WORequest
*)aRequest
inContext:(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:inContext:, - takeValuesFromRequest:inContext:
- (BOOL)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:
- (BOOL)isTerminating
Returns whether the WOSession object will terminate
at the end of the current request-response loop.See
Also: - terminate
- (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:
- (id)objectForKey:(NSString
*)Key
Returns an object stored in the session under
a specific key.See Also: - setObject:forKey:
- (void)removeObjectForKey:(NSString
*)key
Removes the object stored in the session under
the specified key.
- (WOComponent *)restorePageForContextID:(NSString
*)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 nil if restoration
is impossible.See Also: - savePage:
- (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:.
- (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)
- (NSString *)sessionID
Returns the unique, randomly generated string
that identifies the session object. The session ID occurs in the
URL after the request handler key.
- (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
- (void)setDistributionEnabled:(BOOL)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
- (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
- (void)setObject:(id)anObject
forKey:(NSString *)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:
- (void)setStoresIDsInCookies:(BOOL)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.
- (void)setStoresIDsInURLs:(BOOL)flag
Enables or disables the storing of session and
instance IDs in URLs. By default, IDs are stored in URLs.
- (void)setTimeOut:(NSTimeInterval)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
- (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.
- (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:inContext: 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:inContext:
- (BOOL)storesIDsInCookies
Returns whether the cookie mechanism for storing
session and instance IDs is enabled. The cookie mechanism is disabled
by default.
- (BOOL)storesIDsInURLs
Returns whether the URL mechanism for storing
session IDs and instance IDs is enabled. The URL mechanism is enabled
by default.
- (void)takeValuesFromRequest:(WORequest
*)aRequest
inContext:(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:inContext:, - invokeActionForRequest:inContext:
- (void)terminate
Causes the session to terminate after the conclusion
of the current request-response loop.See
Also: - isTerminating
- (NSTimeInterval)timeOut
Returns the timeout interval in seconds.See
Also: - setTimeOut: