com.webobjects.appserver
Class WOSession

java.lang.Object
  com.webobjects.appserver.WOSession

All Implemented Interfaces:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, Serializable, Cloneable

public class WOSession
extends Object
implements Cloneable, Serializable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

WOSession objects represent periods of user interaction 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 example: one client can be accessing a "catalog" application, navigating from page to page and filling a virtual shopping cart with items for purchase. Another client can be accessing the same application at the same time, but visiting different pages and placing different items in his or her shopping cart. Neither client will see anything to indicate that they are not the only person using the application.

Perhaps the most important purpose of a WOSession object is to encapsulate state for a user session. After the application handles a request, it stores the WOSession until the next request in the session occurs. All of the information that is important for maintaining continuity throughout the session is preserved, as is the integrity of session data. This data not only persists between requests but is kept separate from that of all other sessions.

The application uses a session ID to identify a session object. Upon receiving a request that is not identified with a session ID, the application creates a new session and assigns it a session ID -- a unique, randomly generated string. This session ID will appear in the URL between the application name and the page name.

When you develop an application, you identify data with session-wide scope by declaring instance variables in your subclass of WOSession. As the client interacts with the application, before the end of each cycle of the request-response loop, you should ensure that the instance variables hold the current session values.

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 in a given session, it restores the WOSession, using the session ID stored in the request as key. To be stored and restored according to any WOSessionStore strategy, a WOSession must be convertible to a stream. To accomplish this, WOSession implements the interface java.io.Serializable; any custom subclasses should also do so.

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:

• subclasses of WOSession 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 a WOSession holds in order to store session values. Using the key-value coding methods setObjectForKey and objectForKey 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 session. 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 can affect load balancing with the setDistributionEnabled method. If the flag set by this method is false, transactions of the session are restricted to a single application instance. If this is the case, the application instance number as well as the application host name are appended to the URL.

See Also:

WOSession.setTimeOut(double seconds), WOSession.terminate(), WOSession.takeValuesFromRequest(WORequest aRequest, WOContext aContext), WOSession.invokeAction(WORequest aRequest, WOContext aContext), WOSession.appendToResponse(WOResponse aResponse, WOContext aContext), WOSession.awake(), WOSession.sleep(), WOSession.defaultEditingContext(), WOSession.setObjectForKey(Object anObject, String key), WOSession.objectForKey(String key), WOSession.setLanguages(NSArray languages), WOSession.languages(), WOSession.setDistributionEnabled(boolean aFlag), WOSessionStore, Serialized Form

Nested Class Summary

static class

WOSession.PageFragmentCache Used primarily in Ajax style page caching.

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static String	SessionDidCreateNotification Sent at the end of session creation (including awake).
static String	SessionDidRestoreNotification Sent after the session is fully restored (including awake).
static String	SessionDidTimeOutNotification Sent when a session times out but before it is released.

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

WOSession()
Creates a WOSession with a randomly generated session ID and a session time-out of WOApplication.sessionTimeOut() seconds.

WOSession(String aSessionID)
Creates a WOSession with session ID aSessionId and a session time-out of WOApplication.sessionTimeOut() seconds.

Method Summary

boolean	allowedToViewEvents() Returns whether or not the session is allowed to view the WOEvents* pages.
boolean	allowedToViewStatistics() Returns whether or not the session is allowed to view the WOStats page.
void	appendToResponse(WOResponse aResponse, WOContext aContext) Invoked on the WOSession object during the final phase of the request-response loop.
void	awake() Invoked on the WOSession object 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.
static boolean	canAccessFieldsDirectly() Return true in all cases, indicating that key-value coding is allowed to access fields in this object if an appropriate accessor method isn't present.
Object	clone()
WOContext	context() Returns the WOContext object for the current transaction.
static void	debugString(String string) Deprecated. use com.webobjects.foundation.NSLog instead
EOEditingContext	defaultEditingContext() Returns the default EOEditingContext for the receiver.
String	domainForIDCookies() Returns the path that will be used when creating the rendevous cookie for the application to use with the cookie mechanism for storing session and instance IDs This path is lazily created the first time this method is called using the current request's adaptorPrefix and the application name, including the .woa extension.
NSTimestamp	expirationDateForIDCookies() Deprecated. this method is deprecated should not be used
protected WOComponent	getPageFromPageCacheForContextID(String aContextID) Gets the page from the Page Cache.
protected WOComponent	getPageFromPageFragmentCacheForContextID(String contextID) Gets the page from the Page Fragment Cache.
Object	handleQueryWithUnboundKey(String key) Invoked from valueForKey when it finds no property binding for key.
void	handleTakeValueForUnboundKey(Object value, String key) Invoked from takeValueForKey when it finds no property binding for key.
WOActionResults	invokeAction(WORequest aRequest, WOContext aContext) Invoked on the WOSession object during the middle phase of the request-response loop.
boolean	isDistributionEnabled() Returns false by default, since the default WOSessionStore does not support distributed sessions.
boolean	isTerminating() Returns whether or not the receiver is in the process of terminating.
Enumeration	keyEnumerator() Returms an enumerator of the keys in the component state dictionary.
Set	keySet() Returms a keys sets in the component state dictionary.
NSArray	languages() Returns an NSArray of languages for which the session is localized.
boolean	lockDefaultEditingContext() Return true if we lock the default editing context in the awake/sleep phases.
static void	logString(String string) Deprecated. use com.webobjects.foundation.NSLog instead
EOEditingContext	newDefaultEditingContext() Create a new editing context.
Object	objectForKey(String aKey) Returns an Object stored in the session under a given key.
void	removeObjectForKey(String aKey) Removes the Object stored in the session under a given key.
WOComponent	restorePageForContextID(String aContextID) This method attempts to restore an existing page.
void	savePage(WOComponent aPage) Saves the page instance aPage in the session's page cache.
protected void	savePageInPageCache(WOComponent aPage) Saves the page instance aPage in the session's page cache.
protected void	savePageInPageFragmentCache(WOComponent page) Saves the page instance aPage in the session's page fragment cache.
void	savePageInPermanentCache(WOComponent aPageComponent) Puts aPageComponent into the permanent page cache.
String	sessionID() Return the receivers sessionID.
void	setDefaultEditingContext(EOEditingContext editingContext) Sets the editing context to be returned by defaultEditingContext.
void	setDistributionEnabled(boolean aFlag) Enables or disables the distribution mechanism that effects load balancing among multiple application instances.
void	setLanguages(NSArray someLanguages) Sets the languages for which the session is localized.
void	setObjectForKey(Object anObject, String aKey) Stores an Object within the session under a given key.
void	setStoresIDsInCookies(boolean aFlag) Enables or disables the use of cookies for storing the session and instance IDs.
void	setStoresIDsInURLs(boolean aFlag) Enables or disables the use of URLs for storing the session and instance IDs.
void	setTimeOut(double aTimeInterval) Set the session time-out in seconds.
void	sleep() Invoked at the conclusion of each request-response loop in which the session is involved, giving the WOSession the opportunity to clean up objects initialized in the awake method.
NSArray	statistics() Returns a list of pages accessed by this session, ordered from first to most recently accessed.
boolean	storesIDsInCookies() Returns whether the cookie mechanism for storing session and instance IDs is enabled.
boolean	storesIDsInURLs() Returns whether the URL mechanism for storing session and instance IDs is enabled.
void	takeValueForKey(Object value, String key) Sets the value for the property identified by key to value.
void	takeValueForKeyPath(Object value, String keyPath) Sets the value for the property identified by keyPath to value.
void	takeValuesFromRequest(WORequest aRequest, WOContext aContext) Invoked on the WOSession object during the first phase of the the request-response loop.
void	terminate() Causes the session to terminate after the conclusion of the current request-response loop.
double	timeOut() Returns the interval in seconds during which the session can remain idle before it times out.
int	timeOutForIDCookies() Deprecated. this method is deprecated should not be used
long	timeOutMillis() Returns the interval in milliseconds during which the session can remain idle before it times out.
String	toString() Returns a string representation of the receiver, including the session ID, the session time-out and a number of the more important state fields.
void	unableToSetNullForKey(String key) Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float).
void	validateEventsLogin(String password, String username) Validates the username and password used to access the WOEvents* pages.
void	validateStatisticsLogin(String password, String username) Validates the username and password used to access the WOStats page.
void	validationFailedWithException(Throwable t, Object value, String keyPath, WOComponent component) Handle an exception thrown as a result of validation failure.
Object	valueForKey(String key) Retrieves the value of the property named by key.
Object	valueForKeyPath(String keyPath) Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2").

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SessionDidTimeOutNotification

public static final String SessionDidTimeOutNotification

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

See Also:

Constant Field Values

SessionDidRestoreNotification

public static final String SessionDidRestoreNotification

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

See Also:

Constant Field Values

SessionDidCreateNotification

public static final String SessionDidCreateNotification

Sent at the end of session creation (including awake). The object of the notification is the session instance.

See Also:

Constant Field Values

Constructor Detail

WOSession

public WOSession()

Creates a WOSession with a randomly generated session ID and a session time-out of WOApplication.sessionTimeOut() seconds. The isDistributionEnabled flag is set to false, meaning that each request in the session will be handled by the same application instance.

See Also:

WOSession.isDistributionEnabled(), WOSession.setDistributionEnabled(boolean aFlag), WOApplication.sessionTimeOut()

WOSession

public WOSession(String aSessionID)

Creates a WOSession with session ID aSessionId and a session time-out of WOApplication.sessionTimeOut() seconds. The isDistributionEnabled flag is set to false, meaning that each request in the session will be handled by the same application instance.

Parameters:

aSessionID - the session ID provided

See Also:

WOSession.isDistributionEnabled(), WOSession.setDistributionEnabled(boolean aFlag), WOApplication.sessionTimeOut()

Method Detail

clone

public Object clone()

Overrides:

clone in class Object

toString

public String toString()

Returns a string representation of the receiver, including the session ID, the session time-out and a number of the more important state fields. Intended for use in debugging.

Overrides:

toString in class Object

Returns:

String description of the receiver

sessionID

public String sessionID()

Return the receivers sessionID. This ID may be stored in the URL, or in a cookie. If it is in the URL, it will apear after the request handler key.

The sessionID does not change during the life of the session.

Unless the receiver is a copy of another session, or was created with a specified sessionID, the sessionID will be a unique randomly generated String.

Returns:

String which uniquely identifies the receiver

setDistributionEnabled

public void setDistributionEnabled(boolean aFlag)

Enables or disables the distribution mechanism that effects load balancing among multiple application instances.

When false, generated URLs include the application instance number. The web server adaptor then uses this number to route the request to a specific application instance.

When true, generated URLs do not contain the application instance number, and the transactions in a session are distributed among application instances based on whichever load balancing algorithm is in use. Returns false

Parameters:

aFlag - false if generated URLs should include the application instance number, true otherwise

See Also:

WOSession.isDistributionEnabled()

isDistributionEnabled

public boolean isDistributionEnabled()

Returns false by default, since the default WOSessionStore does not support distributed sessions.

When false, generated URLs include the application instance number. The web server adaptor then uses this number to route the request to a specific application instance.

When true, generated URLs do not contain the application instance number, and the transactions in a session are distributed among application instances based on whichever load balancing algorithm is in use.

Returns:

false if generated URLs should include the application instance number, true otherwise

See Also:

WOSession.setDistributionEnabled(boolean aFlag)

setStoresIDsInCookies

public void setStoresIDsInCookies(boolean aFlag)

Enables or disables the use of cookies for storing the session and instance IDs.

If aFlag is true, two cookies are created to store session information: a session ID cookie with the name WORequest.SessionIDKey, and an instance ID cookie with the name WORequest.InstanceKey.

By default, this mechanism is disabled.

Parameters:

aFlag - true if the session ID should be stored using cookies, false otherwise

See Also:

WOSession.storesIDsInCookies(), WOSession.storesIDsInURLs(), WOSession.setStoresIDsInURLs(boolean aFlag)

storesIDsInCookies

public boolean storesIDsInCookies()

Returns whether the cookie mechanism for storing session and instance IDs is enabled.

If true, two cookies are created to store session information: a session ID cookie with the name WORequest.SessionIDKey, and an instance ID cookie with the name WORequest.InstanceKey.

Returns false by default.

Returns:

true if the session ID should be stored using cookies, false otherwise

See Also:

WOSession.setStoresIDsInCookies(boolean aFlag), WOSession.storesIDsInURLs(), WOSession.setStoresIDsInURLs(boolean aFlag)

expirationDateForIDCookies

@Deprecated
public NSTimestamp expirationDateForIDCookies()

Deprecated. this method is deprecated should not be used

Returns:

null in all cases

timeOutForIDCookies

@Deprecated
public int timeOutForIDCookies()

Deprecated. this method is deprecated should not be used

Returns:

-1 in all cases

setStoresIDsInURLs

public void setStoresIDsInURLs(boolean aFlag)

Enables or disables the use of URLs for storing the session and instance IDs.

By default, this mechanism is enabled.

Parameters:

aFlag - true if the session ID should be stored in the URL, false otherwise

See Also:

WOSession.storesIDsInCookies(), WOSession.setStoresIDsInCookies(boolean aFlag), WOSession.storesIDsInURLs()

storesIDsInURLs

public boolean storesIDsInURLs()

Returns whether the URL mechanism for storing session and instance IDs is enabled.

Returns true by default.

Returns:

true if the session ID should be stored in the URL, false otherwise

See Also:

WOSession.storesIDsInCookies(), WOSession.setStoresIDsInCookies(boolean aFlag), WOSession.setStoresIDsInURLs(boolean aFlag)

domainForIDCookies

public String domainForIDCookies()

Returns the path that will be used when creating the rendevous cookie for the application to use with the cookie mechanism for storing session and instance IDs This path is lazily created the first time this method is called using the current request's adaptorPrefix and the application name, including the .woa extension.

Returns:

String path that is passed when creating a rendezvous cookie for the application

See Also:

WOSession.storesIDsInCookies(), WOSession.setStoresIDsInCookies(boolean aFlag), WORequest.adaptorPrefix()

terminate

public void terminate()

Causes the session to terminate after the conclusion of the current request-response loop.

See Also:

WOSession.isTerminating()

isTerminating

public boolean isTerminating()

Returns whether or not the receiver is in the process of terminating. If true, the session will terminate after the conclusion of the current request-response loop.

Returns:

true if the receiver will terminate at the end of the current request-response loop, false otherwise

See Also:

WOSession.terminate()

setTimeOut

public void setTimeOut(double aTimeInterval)

Set the session time-out in seconds. When the application receives no request from this session's client for a period longer than the time-out setting, the session will terminate, resulting in the garbage collection of the session object.

By default, the session time-out is set to the value returned by WOApplication.sessionTimeOut().

Parameters:

aTimeInterval - the number of seconds the session should remain idle before it times out

See Also:

WOSession.timeOut(), WOApplication.sessionTimeOut()

timeOut

public double timeOut()

Returns the interval in seconds during which the session can remain idle before it times out.

Returns:

the timeout interval in seconds as a double

See Also:

WOSession.setTimeOut(double aTimeInterval)

timeOutMillis

public long timeOutMillis()

Returns the interval in milliseconds during which the session can remain idle before it times out.

Returns:

the session timeout in milliseconds as a long

savePageInPermanentCache

public void savePageInPermanentCache(WOComponent aPageComponent)

Puts aPageComponent into the permanent page cache. The permanent page cache is designed to hold components which are frequently accessed. This is useful when you are using frames, since the number of component instances active in a frameset would dramatically reduce the size of the standard page cache. Objects can fall out of the permanent page cache if the permanent page cache's size is exceeded. Note that the best place to call this method is in your component class' constructor to avoid calling it multiple times for the same object. The latest place this method should ever invoke is the beginning of the component's appendToResponse method.

Parameters:

aPageComponent - any WOComponent

See Also:

WOSession.restorePageForContextID(java.lang.String), WOSession.savePage(com.webobjects.appserver.WOComponent), WOApplication.permanentPageCacheSize(), WOApplication.setPermanentPageCacheSize(int anUnsigned), WOComponent.appendToResponse(com.webobjects.appserver.WOResponse, com.webobjects.appserver.WOContext)

restorePageForContextID

public WOComponent restorePageForContextID(String aContextID)

This method attempts to restore an existing page. It will search the session's page cache first, then the permanent page cache. If the page is found, its awake method is called and it is returned; otherwise, null is returned.

The key to the stored instance is its contextID, which derives from the transaction's WOContext or WORequest objects. Note: If you wish to use this method to restore a page generated by WOLongResponse, you must be sure to use the sessionID retrieved during the WOLongResponse's appendToResponse.

Parameters:

aContextID - the key to the stored instance

Returns:

a page instance stored in the session page cache, or null if restoration is impossible

See Also:

WOSession.savePage(WOComponent aPage), WOSession.savePageInPermanentCache(WOComponent aPageComponent), WOSession.sessionID(), WOContext.contextID()

getPageFromPageCacheForContextID

protected WOComponent getPageFromPageCacheForContextID(String aContextID)

Gets the page from the Page Cache.

Parameters:

aContextID - the key to the stored instance

Returns:

a page instance stored in the session page cache.

getPageFromPageFragmentCacheForContextID

protected WOComponent getPageFromPageFragmentCacheForContextID(String contextID)

Gets the page from the Page Fragment Cache.

Parameters:

aContextID - the key to the stored instance

Returns:

a page instance stored in the session page fragment cache.

Since:

5.4

savePage

public void savePage(WOComponent aPage)

Saves the page instance aPage in the session's page cache. Invoked automatically if the WOApplication subclass' pageCacheSize is non-zero. The context ID for the current transaction should be used as the key for retrieving this instance from the cache using restorePageForContextID. This method will take into account the value shouldNotStorePageInBacktrackCachein the WOContext and store the page either in the backtrack cache or the page fragment cache.

Parameters:

aPage - the page instance

See Also:

WOSession.restorePageForContextID(String aContextID), WOSession.savePageInPermanentCache(WOComponent aPageComponent), WOContext.contextID(), WOContext.shouldNotStorePageInBacktrackCache()

savePageInPageCache

protected void savePageInPageCache(WOComponent aPage)

Saves the page instance aPage in the session's page cache. Invoked automatically if the WOApplication subclass' pageCacheSize is non-zero. The context ID for the current transaction should be used as the key for retrieving this instance from the cache using restorePageForContextID.

Parameters:

aPage - the page instance

Since:

5.4

See Also:

WOSession.restorePageForContextID(String aContextID), WOSession.savePageInPermanentCache(WOComponent aPageComponent), WOContext.contextID()

savePageInPageFragmentCache

protected void savePageInPageFragmentCache(WOComponent page)

Saves the page instance aPage in the session's page fragment cache. Invoked automatically if the WOApplication subclass' pageCacheSize is non-zero. The context ID for the current transaction should be used as the key for retrieving this instance from the cache using restorePageForContextID. Page fragments are identified by the pageFragementID, as only one copy of each fragment is stored in the cache.

Parameters:

page - the page instance

Since:

5.4

See Also:

WOSession.restorePageForContextID(String aContextID), WOSession.savePageInPermanentCache(WOComponent aPageComponent), WOContext.contextID(), WOContext.pageFragementID()

setLanguages

public void setLanguages(NSArray someLanguages)

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 .lproj directories for localized strings, images, and component definitions.

Parameters:

someLanguages - the array of languages for the application

See Also:

WOSession.languages()

languages

public NSArray languages()

Returns an NSArray of languages for which the session is localized. The order of language strings returned indicates the preferred order of languages. This is initialized from the user's browser preferences unless explicitly set with setLanguages.

Returns:

NSArray of languages supported by the session, in order of preference

See Also:

WOSession.setLanguages(NSArray languages)

setObjectForKey

public void setObjectForKey(Object anObject,
                            String aKey)

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.

Parameters:

anObject - Object to be stored in the current session

aKey - String key under which to store the object

See Also:

WOSession.objectForKey(String aKey), WOSession.removeObjectForKey(String aKey)

objectForKey

public Object objectForKey(String aKey)

Returns an Object stored in the session under a given key.

Parameters:

aKey - the key under which the object is stored

Returns:

Object stored in the session under the specified key

See Also:

WOSession.setObjectForKey(Object anObject, String aKey), WOSession.removeObjectForKey(String aKey)

keySet

public Set keySet()

Returms a keys sets in the component state dictionary.

Returns:

keys set

Since:

5.4

keyEnumerator

public Enumeration keyEnumerator()

Returms an enumerator of the keys in the component state dictionary.

Returns:

keys enumerator

Since:

5.4

removeObjectForKey

public void removeObjectForKey(String aKey)

Removes the Object stored in the session under a given key.

Parameters:

aKey - String key under which the Object is stored

See Also:

WOSession.objectForKey(String aKey), WOSession.setObjectForKey(Object anObject, String aKey)

context

public WOContext context()

Returns the WOContext object for the current transaction.

Returns:

WOContext object for the current transaction

See Also:

WOContext

awake

public void awake()

Invoked on the WOSession object 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:

WOSession.sleep()

takeValuesFromRequest

public void takeValuesFromRequest(WORequest aRequest,
                                  WOContext aContext)

Invoked on the WOSession object during the first phase of the 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 invoke takeValuesFromRequest on the WOComponent object that represents the request.

Subclasses of WOSession can override this method to replace or supplement the default behavior with custom logic.

Parameters:

aRequest - the request to be processed

aContext - the current context of the transaction

See Also:

WOSession.appendToResponse(WOResponse aResponse, WOContext aContext), WOSession.invokeAction(WORequest aRequest, WOContext aContext)

invokeAction

public WOActionResults invokeAction(WORequest aRequest,
                                    WOContext aContext)

Invoked on the WOSession object during the middle phase of the request-response loop. During this phase, the invokeAction method 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 invoke invokeAction on the WOComponent object that represents the request.

Subclasses of WOSession can override this method to replace or supplement the default behavior with custom logic.

Parameters:

aRequest - the WORequest being processed

aContext - the WOContext context in which the request is being processed

Returns:

a WOActionResults

See Also:

WOSession.appendToResponse(WOResponse aResponse, WOContext aContext), WOSession.takeValuesFromRequest(WORequest aRequest, WOContext aContext)

appendToResponse

public void appendToResponse(WOResponse aResponse,
                             WOContext aContext)

Invoked on the WOSession object during the final phase of the request-response loop. During this phase the objects associated with a response page append their HTML content to the response. WOSession's default implementation of this method invokes appendToResponse on the WOComponent that represents the response page. Then it records information about the current transaction by invoking recordStatisticsForResponse and then descriptionForResponse on the WOStatisticsStore object.

Subclasses of WOSession can override this method to replace or supplement the default behavior with custom logic. Note This method is not called during a direct action request-response loop.

Parameters:

aResponse - the WOResponse

aContext - the WOContext of the transaction

See Also:

WOSession.invokeAction(WORequest aRequest, WOContext aContext), WOSession.takeValuesFromRequest(WORequest aRequest, WOContext aContext), WOStatisticsStore.recordStatisticsForResponse(WOResponse aResponse , WOContext aContext), WOStatisticsStore.descriptionForResponse(WOResponse aResponse , WOContext aContext)

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 clean up objects initialized in the awake method.

The default WOSession implementation does nothing.

See Also:

WOSession.awake()

statistics

public NSArray statistics()

Returns a list of pages accessed by this session, ordered from first to most recently accessed. For each page, the String stored is obtained by sending descriptionForResponse to its 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.

Returns:

NSArray of the pages accessed by this session

See Also:

WOSession.appendToResponse(WOResponse aResponse, WOContext aContext), WOComponent.descriptionForResponse(WOResponse aResponse, WOContext aContext)

allowedToViewStatistics

public boolean allowedToViewStatistics()

Returns whether or not the session is allowed to view the WOStats page. 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, this method returns false.

Returns:

true if clients are allowed to view session statistics

See Also:

WOSession.validateStatisticsLogin(String password, String username), WOSession.allowedToViewEvents(), WOSession.validateEventsLogin(String password, String username)

validateStatisticsLogin

public void validateStatisticsLogin(String password,
                                    String username)

Validates the username and password used to access the WOStats page. By default, validation will fail unless a password has been specified; this can be done by setting a password on the application's WOStatisticsStore in code, or by using the WOStatisticsPassword property.

By default, the username is ignored.

Subclasses of WOSession can override this method to provide application specific login behavior.

Parameters:

password - input password

username - input user's name

See Also:

WOSession.allowedToViewStatistics(), WOSession.allowedToViewEvents(), WOSession.validateEventsLogin(String password, String username)

validationFailedWithException

public void validationFailedWithException(Throwable t,
                                          Object value,
                                          String keyPath,
                                          WOComponent component)

Handle an exception thrown as a result of validation failure.

By default, this method invokes your application class' validationFailedWithException method.

Subclasses of WOSession can override this method to provide application specific behavior.

Parameters:

t - the exception that was thrown

value - the value that was being set

keyPath - the derived path that was being accessed

component - the component that was being used

See Also:

WOApplication.validationFailedWithException(Throwable t, Object value, String keyPath, WOComponent component, WOSession session)

allowedToViewEvents

public boolean allowedToViewEvents()

Returns whether or not the session is allowed to view the WOEvents* pages. If a password must be supplied prior to viewing the events pages and the client hasn't supplied the proper password, this method returns false.

This method returns false by default.

Returns:

true if the session is allowed to view the WOEvents* pages

See Also:

WOSession.validateEventsLogin(String password, String username), WOSession.allowedToViewStatistics(), WOSession.validateStatisticsLogin(String password, String username)

validateEventsLogin

public void validateEventsLogin(String password,
                                String username)

Validates the username and password used to access the WOEvents* pages. By default, validation will fail unless a password has been specified. This can be done by setting a password on EOEventCenter in code, or by using the WOEventsPassword property.

By default, the username is ignored.

Subclasses of WOSession can override this method to provide application specific login behavior.

Parameters:

password - input password

username - input user's name

See Also:

WOSession.allowedToViewEvents(), WOSession.allowedToViewStatistics(), WOSession.validateStatisticsLogin(String password, String username)

logString

@Deprecated
public static void logString(String string)

Deprecated. use com.webobjects.foundation.NSLog instead

Parameters:

string - String to be logged

debugString

@Deprecated
public static void debugString(String string)

Deprecated. use com.webobjects.foundation.NSLog instead

Parameters:

string - String to be logged

defaultEditingContext

public EOEditingContext defaultEditingContext()

Returns the default EOEditingContext for the receiver. This method creates the editing context the first time that it is invoked and caches it for subsequent invocations.

There is only one unique editing context instance per session.

The instance's parent object store is initialized to the default parent object store.

Returns:

the default EOEditingContext object for the session

See Also:

WOSession.setDefaultEditingContext(EOEditingContext editingContext)

newDefaultEditingContext

public EOEditingContext newDefaultEditingContext()

Create a new editing context. Sub classes can override this method to customize the editing context created. If the session locks teh default editing context this context must be returned unlocked.

Returns:

editing context.

setDefaultEditingContext

public 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, setDefaultEditingContext may not be called again. Therefore, to provide your own default editing context, setDefaultEditingContext must be called before ever calling defaultEditingContext since that will lazily establish an editing context.

Parameters:

editingContext - the EOEditingContext to be used as the default

See Also:

WOSession.defaultEditingContext()

lockDefaultEditingContext

public boolean lockDefaultEditingContext()

Return true if we lock the default editing context in the awake/sleep phases.

Returns:

boolean true if we lock the default editing context in the awake/sleep phases

Since:

5.4

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

Return true in all cases, indicating that key-value coding is allowed to access fields in this object if an appropriate accessor method isn't present.

Returns:

true in all cases

valueForKey

public Object valueForKey(String key)

Description copied from interface: NSKeyValueCoding

Retrieves the value of the property named by key.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName, lastName, or isLastName.
2. If a public accessor method is not found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", the method looks for a method named _getLastName, _lastName, or _isLastName
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, the method searches for a field based on key and returns its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If neither an accessor method nor a field is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property to retrieve

Returns:

the value of the property identified by key. Depending on the object you invoke this method upon, null may be replaced with NullValue

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Description copied from interface: NSKeyValueCoding

Sets the value for the property identified by key to value.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method of the form setKey, and invokes it if there is one.
2. If a public accessor method is not found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, searches for a field based on key and sets its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If the type of the value argument is not compatible with the underlying field or method parameter, the default implementation will make an effort to convert between different Java numeric types (Integer, Double, BigDecimal, etc) as well as between Boolean and Number (true = 1, false = 0). If any other conversion would be necessary, an exception is thrown.
5. If neither an accessor method nor a field is found, it is an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding.UnknownKeyException if the object does not.

Note: : The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding. DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

value - the new value for the property named by key

key - identifies the property to change

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey, NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from valueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfokey) in the user info. An NSKeyValueCoding.ErrorHandling class can override this method to handle the query in some other way. The method can return a value, in which case that value is returned by the corresponding valueForKey invocation.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - the property name which generated this error

Returns:

any Object or null that the custom implementation desires. The default implementation throws an exception instead.

See Also:

NSKeyValueCoding.valueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfoKey) in the user info dictionary of the exception. An NSKeyValueCoding.ErrorHandling class can override this method to handle the error in some other way.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

value - the new value which could not be set

key - the name of the property which generated this error

See Also:

NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float). The default implementation throws an IllegalArgumentException. You might want to implement the method (or override the inherited implementation) to handle the request in some other way, such as by substituting new Integer(0) or a sentinel value and invoking takeValueForKey again.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - the name of the property which generated this error

See Also:

NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.DefaultImplementation

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2"). A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and returns the result of a valueForKey message to the final object.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - the keypath to evaluate

Returns:

the value for the derived property identified by keyPath

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Sets the value for the property identified by keyPath to value. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and sends the final object a takeValueForKey message with value and property.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

value - the property identified by keyPath is set to this

keyPath - identifies the property of an object

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation