com.webobjects.appserver
Class WOContext

java.lang.Object
  |
  +--com.webobjects.appserver.WOContext

All Implemented Interfaces:

Cloneable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

Direct Known Subclasses:

WOServletContext

public class WOContext

extends Object

implements Cloneable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

A WOContext object lets you access objects and information that define the context of a transaction. In a typical request-response loop (a transaction), several objects have a hand in what is going on: the WOApplication and WOSession objects, the page involved in the request or response (a WOComponent object), the page's subcomponents (also WOComponents), plus the dynamic elements on the page. The WOContext object passed as an argument in the takeValuesFromRequest, invokeAction, and appendToResponse methods allows access to these objects. A context is identified by the contextID, which appears in the URL after the session ID and page name. Each contextID is an integer that the session increments each time a new context is created.

WOContext objects provide other information and services related to the current transaction. From them you can get the entire URL currently in effect as well as portions of that URL, such as the element ID, the context ID, and the URL up to and including the session ID.

A WOContext object plays a further role behind the scenes. For the benefit of a page's dynamic elements, it keeps track of the current component, that is, the WOComponent associated with the current element in the request-handling cycle. The current component can be the WOComponent that represents one of the page's subcomponents or the page itself. By reference to the current component,accessed through WOContext's component method, a dynamic element can exchange values associatively between itself and the WOComponent that contains it.

See Also:

component(), WOComponent.takeValuesFromRequest(WORequest aRequest, WOContext aContext), WOComponent.invokeAction(WORequest aRequest, WOContext aContext), WOComponent.appendToResponse(WOResponse aResponse, WOContext aContext)

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

WOContext(WORequest aRequest)
Returns a WOContext instance initialized with aRequest.

Method Summary

void	appendElementIDComponent(String aString) Appends a string to the current element ID to create an identifier of an HTML element.
void	appendZeroElementIDComponent() Appends a ".0" to the current element ID to create an identifier of the first "child" HTML element.
static boolean	canAccessFieldsDirectly() WOContext's implementation of this static method returns true, indicating that key/value coding is allowed to access fields in this object if an appropriate method isn't present.
Object	clone()
String	completeURLWithRequestHandlerKey(String requestHandlerKey, String aRequestHandlerPath, String aQueryString, boolean isSecure, int somePort) Returns the complete URL for the specified request handler.
WOComponent	component() Returns the WOComponent that dynamic elements are currently using to push and pull values associatively.
String	componentActionURL() Returns a URL for a component action relative to cgi-bin/WebObjects.
String	contextID() Returns the context ID of the receiver.
static WOContext	contextWithRequest(WORequest aRequest) Deprecated. use WOContext(WORequest aRequest) instead
void	deleteAllElementIDComponents() Deletes all components of the current element ID.
void	deleteLastElementIDComponent() Deletes the last digit --or name-- of the current element ID, along with its dot separator.
String	directActionURLForActionNamed(String anActionName, NSDictionary aQueryDict) Returns a complete URL for the specified action.
String	elementID() Returns an element ID.
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.
boolean	hasSession() Returns true if a session exists for the receiving context, false otherwise.
void	incrementLastElementIDComponent() Increments the last digit of the current element ID.
boolean	isInForm() Used by subclasses of WODynamicElement to determine if the context is in a WOForm element.
WOComponent	page() Returns a WOComponent object that represents either the request or response page.
WORequest	request() Return the context's WORequest object.
WOResponse	response() Return the context's WOResponse object.
String	senderID() Returns the part of the WORequest's URI that identifies the dynamic element on the page (such as a form or an active image) responsible for submitting the request.
WOSession	session() Returns the object representing the receiving context's session, if one exists.
void	setInForm(boolean aFlag) If you write something that behaves like a WOForm, invoke this method with aFlag true in appendToResponse(WOResponse aResponse, WOContext aContext) before calling super.appendToResponse(WOResponse aResponse, WOContext aContext) to notify any contained WODynamicElements that they are in a form.
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.
String	toString()
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).
String	urlWithRequestHandlerKey(String requestHandlerKey, String aRequestHandlerPath, String aQueryString) Returns a URL relative to cgi-bin/WebObjects for the specified request handler.
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

Constructor Detail

WOContext

public WOContext(WORequest aRequest)

Returns a WOContext instance initialized with aRequest.

Parameters:

aRequest - request that initializes the instance

Method Detail

appendElementIDComponent

public void appendElementIDComponent(String aString)

Appends a string to the current element ID to create an identifier of an HTML element. For example, if the current element ID is "0.1.1" and this method is invoked with an argument of "NameField," the element ID for that field becomes "0.1.1.NameField".

Parameters:

aString - String to be appended to the current element ID

See Also:

appendZeroElementIDComponent(), deleteAllElementIDComponents(), deleteLastElementIDComponent(), incrementLastElementIDComponent()

appendZeroElementIDComponent

public void appendZeroElementIDComponent()

Appends a ".0" to the current element ID to create an identifier of the first "child" HTML element. For example, if the current element ID is "0.1.1", after this method is invoked the element ID becomes "0.1.1.0".

See Also:

appendElementIDComponent(String aString), deleteAllElementIDComponents(), deleteLastElementIDComponent(), incrementLastElementIDComponent()

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

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

Returns:

true

clone

public Object clone()

Overrides:

clone in class Object

completeURLWithRequestHandlerKey

public String completeURLWithRequestHandlerKey(String requestHandlerKey,
                                               String aRequestHandlerPath,
                                               String aQueryString,
                                               boolean isSecure,
                                               int somePort)

Returns the complete URL for the specified request handler. The requestHandlerKey is one of the keys registered with WOApplication. The requestHandlerPath is any URL encoded string. The aQueryString is added at the end of the URL behind a "?". If isSecure is true, this method uses "https" instead of "http". If somePort is 0 (zero), this method uses the default port.

Parameters:

requestHandlerKey - one of the keys registered with WOApplication

aRequestHandlerPath - any URL encoded string

aQueryString - added at the end of the URL

isSecure - if true the method uses "https" instead of "http"

somePort - the port on which the request handler is listening if 0 this method uses the default port request handler

Returns:

String with the complete URL for the specified request handler

See Also:

urlWithRequestHandlerKey(String requestHandlerKey, String aRequestHandlerPath, String aQueryString), WOApplication.registeredRequestHandlerKeys()

component

public WOComponent component()

Returns the WOComponent that dynamic elements are currently using to push and pull values associatively. During the takeValuesFromRequestinvokeAction phases of request handling, this will be either the current request, or a subcomponent of that page. During the appendToResponse phase, it will return the response page or a subcomponent.

Returns:

a WOComponent

See Also:

page(), request(), response(), session(), WOComponent

componentActionURL

public String componentActionURL()

Returns a URL for a component action relative to cgi-bin/WebObjects. The exact form of the URL will vary depending on whether the application is caching pages and whether the session ID is being stored in the URL or not.

Returns:

the URL for a component action

contextID

public String contextID()

Returns the context ID of the receiver.

Returns:

the context ID of the receiver

contextWithRequest

public static WOContext contextWithRequest(WORequest aRequest)

Deprecated. use WOContext(WORequest aRequest) instead

Deprecated.

Parameters:

aRequest - WORequest

Returns:

an instance of WOContext initialized with aRequest

deleteAllElementIDComponents

public void deleteAllElementIDComponents()

Deletes all components of the current element ID.

See Also:

appendElementIDComponent(String aString), appendZeroElementIDComponent(), deleteLastElementIDComponent(), incrementLastElementIDComponent()

deleteLastElementIDComponent

public void deleteLastElementIDComponent()

Deletes the last digit --or name-- of the current element ID, along with its dot separator. Thus, after invoking this method, "0.0.1.1" becomes "0.0.1".

See Also:

appendElementIDComponent(String aString), appendZeroElementIDComponent(), deleteAllElementIDComponents(), incrementLastElementIDComponent()

directActionURLForActionNamed

public String directActionURLForActionNamed(String anActionName,
                                            NSDictionary aQueryDict)

Returns a complete URL for the specified action. anActionName can be either an action -- "ActionName" -- or an action on a class -- "ActionClass/ActionName". You can also specify aQueryDict to be an NSDictionary which contains form values as key/value pairs.

Parameters:

anActionName - String action name

aQueryDict - NSDictionary containing query key/value pairs

Returns:

a String containing the URL for the specified action

See Also:

WODirectAction

elementID

public String elementID()

Returns an element ID. This element ID is used by WOElements during the appendToResponse phase of request handling to create URLs, and during the invokeAction phase to determine which element was activated. This element ID will change as appendElementIDComponent etc are invoked.

Returns:

the element ID identifying the current WOElement

See Also:

appendElementIDComponent(String aString), appendZeroElementIDComponent(), deleteAllElementIDComponents(), deleteLastElementIDComponent(), incrementLastElementIDComponent()

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

Following copied from interface: com.webobjects.foundation.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.

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), 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

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

value - the new value which could not be set

key - the name of the property which generated this error

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

hasSession

public boolean hasSession()

Returns true if a session exists for the receiving context, false otherwise.

Returns:

true if a session exists for the receiving context, false otherwise

See Also:

session()

incrementLastElementIDComponent

public void incrementLastElementIDComponent()

Increments the last digit of the current element ID. For example, after this method is invoked, "0.0.1.2" becomes "0.0.1.3".

See Also:

appendElementIDComponent(String aString), appendZeroElementIDComponent(), deleteAllElementIDComponents(), deleteLastElementIDComponent()

isInForm

public boolean isInForm()

Used by subclasses of WODynamicElement to determine if the context is in a WOForm element.

Returns:

returns true when in the context of a WOForm, false otherwise

See Also:

setInForm(boolean flag)

page

public WOComponent page()

Returns a WOComponent object that represents either the request or response page. If this method is called during the takeValuesFromRequestinvokeAction phases of request handling, it will return the request page. If it is called during appendToResponse phase, it will return the response page. During the first two phases, the request page is determined by the context ID in the request -- if one exists, and is restored from the user's session's page cache.

Returns:

a WOComponent object that represents either the request or response page

See Also:

component(), request(), response(), session(), WOSession.restorePageForContextID(String aContextID)

request

public WORequest request()

Return the context's WORequest object.

Returns:

the receiver's WORequest object

See Also:

component(), page(), response(), session()

response

public WOResponse response()

Return the context's WOResponse object.

Returns:

the receiver's WOResponse object

See Also:

component(), page(), response(), session()

senderID

public String senderID()

Returns the part of the WORequest's URI that identifies the dynamic element on the page (such as a form or an active image) responsible for submitting the request. The sender ID is the same as the element ID used to identify the dynamic element. A request's sender ID may be null, as it always is on the first request of a session.

Returns:

the part of the WORequest's URI that identifies a dynamic element on a page

See Also:

request(), WORequest.uri()

session

public WOSession session()

Returns the object representing the receiving context's session, if one exists. If the receiver does not have a session, this method creates a new session object and returns it. Note that not all contexts have a session: Direct Actions, for instance, don't always need a session. use hasSession to determine whether a context has a session associated with it.

In the case of a direct action, if a session could not be restored from a session ID this method attempts to create a new session by calling WOApplication.createSessionForRequest. If createSessionForRequest returns null, this method throws an IllegalStateException (catch it in your direct action to manually handle session creation error).

Returns:

the object representing the receiving context's session

See Also:

component(), page(), request(), response(), hasSession(), WOSession, WOApplication.createSessionForRequest

setInForm

public void setInForm(boolean aFlag)

If you write something that behaves like a WOForm, invoke this method with aFlag true in appendToResponse(WOResponse aResponse, WOContext aContext) before calling super.appendToResponse(WOResponse aResponse, WOContext aContext) to notify any contained WODynamicElements that they are in a form. After super.appendToResponse(WOResponse aResponse, WOContext aContext) is done, revert the change by invoking invoke this method with aFlag false.

Parameters:

aFlag - truenotifies WODynamicElements that they are in a form

See Also:

isInForm()

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

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding

Parameters:

value - the new value for the property named by key

key - identifies the property to change

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

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

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

Following copied from interface: com.webobjects.foundation.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

toString

public String toString()

Overrides:

toString in class Object

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

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

key - the name of the property which generated this error

Throws:

IllegalArgumentException - when it is given a null value for a scalar property

See Also:

NSKeyValueCoding.takeValueForKey(Object value, String key), NSKeyValueCoding.DefaultImplementation

urlWithRequestHandlerKey

public String urlWithRequestHandlerKey(String requestHandlerKey,
                                       String aRequestHandlerPath,
                                       String aQueryString)

Returns a URL relative to cgi-bin/WebObjects for the specified request handler. The requestHandlerKey is one of the keys registered with WOApplication. The aRequestHandlerPath is any URL encoded string. The aQueryString is added at the end of the URL behind a "?".

Parameters:

requestHandlerKey - one of the keys provided by WOApplication

aRequestHandlerPath - any URL encoded string

aQueryString - string added at the end of the URL

Returns:

returns a URL relative to cgi-bin/WebObjects for the specified request handler

See Also:

(String requestHandlerKey, String aRequestHandlerPath, String aQueryString, boolean isSecure,int somePort), WOApplication.registeredRequestHandlerKeys()

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

Following copied from interface: com.webobjects.foundation.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

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

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

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

Following copied from interface: com.webobjects.foundation.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