WebObjects 5.2.3

com.webobjects.appserver
Class WOContext

java.lang.Object
  extended bycom.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)

Nested Class Summary
 
Nested classes inherited from class com.webobjects.foundation.NSKeyValueCoding
NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor
 
Nested classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions
NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility
 
Field Summary
 
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()

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
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(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
Parameters:
value - the new value which could not be set
key - the name of the property which generated this error
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(WORequest request). If createSessionForRequest(WORequest request) 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(WORequest request)

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
Parameters:
value - the new value for the property named by key
key - identifies the property to change
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
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()

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(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
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)

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

Last updated Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.