PATH |
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()
public WOSession(String aSessionID)
Static Methods
canAccessFieldsDirectly
public static boolean canAccessFieldsDirectly()
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)
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)
int i = 500; float f = 2.045; WOApplication.logString("Amount = " + i + ", Rate = " + f ", Total = " + i*f);
Instance Methods
allowedToViewStatistics
public boolean allowedToViewStatistics()
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()
appendToResponse
public void appendToResponse( WOResponse aResponse, WOContext aContext)
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()
See Also: sleep
clone
public Object clone()
context
public WOContext context()
See Also: WOContext class
defaultEditingContext
public com.webobjects.eocontrol.EOEditingContext defaultEditingContext()
domainForIDCookies
public String domainForIDCookies()
expirationDateForIDCookies
public NSTimestamp expirationDateForIDCookies()
finalize
public void finalize() throws Throwable
handleQueryWithUnboundKey
public Object handleQueryWithUnboundKey(String key)
handleTakeValueForUnboundKey
public void handleTakeValueForUnboundKey(Object value, String key)
invokeAction
public WOActionResults invokeAction( WORequest aRequest, WOContext aContext)
See Also: appendToResponse, takeValuesFromRequest
isDistributionEnabled
public boolean isDistributionEnabled()
See Also: setDistributionEnabled
isTerminating
public boolean isTerminating()
See Also: terminate
languages
public NSArray languages()
See Also: setLanguages
objectForKey
public Object objectForKey(String key)
See Also: setObjectForKey
removeObjectForKey
public void removeObjectForKey(String key)
restorePageForContextID
public WOComponent restorePageForContextID(String contextID)
See Also: savePage
savePage
public void savePage(WOComponent aPage)
savePageInPermanentCache
pubic void savePageInPermanentCache(WOComponent aPage)
See Also: permanentPageCacheSize (WOApplication), setPermanentPageCacheSize (WOApplication)
sessionID
public String sessionID()
setDefaultEditingContext
public void setDefaultEditingContext( com.webobjects.eocontrol.EOEditingContext editingContext)
See Also: defaultEditingContext
setDistributionEnabled
public void setDistributionEnabled(boolean aFlag)
See Also: isDistributionEnabled
setLanguages
public void setLanguages(NSArray languages)
See Also: languages
setObjectForKey
public void setObjectForKey(Object anObject, String key)
See Also: objectForKey
setStoresIDsInCookies
public void setStoresIDsInCookies(boolean flag)
setStoresIDsInURLs
public void setStoresIDsInURLs(boolean flag)
setTimeOut
public void setTimeOut(double seconds)
See Also: timeOut
sleep
public void sleep()
statistics
public NSArray statistics()
See Also: appendToResponse
storesIDsInCookies
public boolean storesIDsInCookies()
storesIDsInURLs
public boolean storesIDsInURLs()
takeValueForKey
public void takeValueForKey(Object value, String key)
takeValueForKeyPath
public void takeValueForKeyPath(Object value, String keyPath)
takeValuesFromRequest
public void takeValuesFromRequest( WORequest aRequest, WOContext aContext)
See Also: appendToResponse, invokeAction
terminate
public void terminate()
See Also: isTerminating
timeOut
public double timeOut()
See Also: setTimeOut
timeOutForIDCookies
public int timeOutForIDCookies()
timeOutMillis
public long timeOutMillis()
toString
public String toString()
unableToSetNullForKey
public void unableToSetNullForKey(String key)
validateEventsLogin
public void validateEventsLogin ( String password, String username)
validateStatisticsLogin
public void validateStatisticsLogin ( String password, String username)
validationFailedWithException
public void validationFailedWithException ( Throwable aThrowable, Object value, String keyPath, WOComponent aComponent)
valueForKey
public Object valueForKey(String key)
valueForKeyPath
public Object valueForKeyPath(String keyPath)
Notifications
WOSessionDidCreateNotification
public static final String WOSessionDidCreateNotification
WOSessionDidRestoreNotification
public static final String WOSessionDidRestoreNotification
WOSessionDidTimeOutNotification
public static final String WOSessionDidTimeOutNotification
© 2001 Apple Computer, Inc. (Last Published April 15, 2001)