PATH
Documentation > WebObjects 4.5 >
WebObjects Reference
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 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, 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
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
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.
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
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
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
public WOContext context()
Returns the WOContext object for the current
transaction. See Also: WOContext class
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.
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).
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 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.
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
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
public boolean isTerminating()
Returns whether the WOSession object will terminate
at the end of the current request-response loop.See
Also: terminate
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
public Object objectForKey(String key)
Returns an object stored in the session under
a specific key.See Also: setObjectForKey
public void removeObjectForKey(String key)
Removes the object stored in the session under
the specified key.
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
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.
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)
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.
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
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
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
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
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.
public void setStoresIDsInURLs(boolean flag)
Enables or disables the storing of session and
instance IDs in URLs. By default, IDs are stored in URLs.
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
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.
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
public boolean storesIDsInCookies()
Returns whether the cookie mechanism for storing
session and instance IDs is enabled. The cookie mechanism is disabled
by default.
public boolean storesIDsInURLs()
Returns whether the URL mechanism for storing
session IDs and instance IDs is enabled. The URL mechanism is enabled
by default.
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
public void terminate()
Causes the session to terminate after the conclusion
of the current request-response loop.See
Also: isTerminating
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.