PATH |
WORequest
Inherits from: WOMessage : Object
Implements: Cloneable
Package: com.webobjects.appserver
Class Description
A WORequest object typically represents an HTTP request and thus constitutes an event that requires a reaction from a WebObjects application. WORequest objects encapsulate the data transmitted to an HTTP server in a request. Requests usually originate from user actions in a browser, such as the submission of a URL or a mouse click on a hyperlink, button, or active image in a page. From the perspective of WebObjects, the URL identifies a WebObjects application and the click on a control usually results in the display of a page of a WebObjects application. Such actions cause the browser to send an HTTP request to an HTTP server, which forwards the request to a WebObjects adaptor, which converts it to a WORequest object and sends that object to the appropriate request handler.
WORequest objects can also be created from HTTP requests sent by client-side components (Java applets specially modified to interact with the server side of a WebObjects application), and from HTTP requests submitted by custom client-side programs that don't use the Java client-side components. As well, WORequest objects can originate from custom adaptors that handle HTTP requests or non-HTTP events. (All the adaptors shipped with WebObjects handle HTTP events only).
Since adaptors usually create WORequest objects, and since you can usually use WebObjects' adaptors without modifications, you probably won't have to create your own instances of WORequest in your code (although you can if you need to). More typically, your code will obtain information from WORequest objects as they become available during certain points in the request-response loop. The application supplies WORequest objects as arguments in the takeValuesFromRequest and invokeActionForRequest methods, which are implementable by WOApplication, WOSession, WOComponent, and WOElement objects. You can also obtain the current WORequest object at any time during request handling through WOContext's request method.
Note: Because WORequest objects usually correspond to HTTP requests, the data they encapsulate is almost the same as what you would find in an HTTP request. Thus an understanding of HTTP requests is important for understanding the data vended by WORequest objects. A recommended prerequisite therefore is to review the current HTTP specification or HTTP documentation. |
Note that WORequest inherits from WOMessage. Of particular interest are those WOMessage methods that allow you to access the request headers (headerForKey, headerKeys, headers, and headersForKey) and content and contentAsDOMDocument, which return the contents of the request.
Programmatically Creating WORequest Objects
As stated above, in most WebObjects applications WORequest objects are created for you; your application is more concerned with interpreting and responding to WORequest objects. However, it is possible to place two WebObjects applications in a peer-to-peer configuration and have them communicate using WORequest and WOResponse objects. In situations like these, your application will need to create the WORequest objects itself and send them to the peer application using WOHTTPConnection.
The methods declared directly on WORequest allow you to extract information from a WORequest object. WORequest inherits a number of methods from WOMessage, however, that allow you to programmatically specify the contents of a request. In particular, the appendContent... and setContent methods in the WOMessage class are designed to do this. For more information, see the WOMessage class specification.
Constants
WORequest declares these constants:
SessionIDKey | This class constant (a String) has the value "wosid" and is the key you use to obtain the session ID from a request (using methods like formValueForKey(String) and cookieValueForKey(String)). |
InstanceKey | This class constant (a String) has the value "woinst" and is the key you use to obtain the application number (instance) from a request (using methods like formValueForKey(String) and cookieValueForKey(String)). |
DataKey | This class constant (a String) has the value "wodata" and is the key you use to obtain from a request another key. You use this second key either to retrieve cached data from the WOResourceManager or to construct a query with which you can obtain a URL to the request data (using WOContext's urlWithRequestHandlerKey() method). Use methods like formValueForKey(String) and cookieValueForKey(String) when querying the request with the DataKey . |
ContextIDKey | This class constant (a String) has the value "wocid" and is used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's context ID. |
SenderIDKey | This class constant (a String) has the value "woeid" and is used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's sender ID. |
PageNameKey | This class constant (a String) has the value "wopage" and is used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's page name. |
SingleInstanceIDString | This class constant contains, as a String , the application number used by applications deployed in single instance mode: "-1". |
SingleInstanceID | This class constant contains, as an int , the application number used by applications deployed in single instance mode: -1. |
Method Types
Constructors WORequest Working with cookies cookieValueForKey cookieValues cookieValuesForKey Form values defaultFormValueEncoding formValueEncoding formValueForKey formValueKeys formValues formValuesForKey isFormValueEncodingDetectionEnabled Request handling requestHandlerKey requestHandlerPath requestHandlerPathArray Form Values setDefaultFormValueEncoding setFormValueEncodingDetectionEnabled Obtaining attributes adaptorPrefix applicationName applicationNumber browserLanguages isFromClientComponent method sessionID uri
Constructors
WORequest
public WORequest( String aMethod, String anURL, String anHTTPVersion, NSDictionary someHeaders, NSData aContent, NSDictionary userInfo)
- aMethod must be either "GET" or "POST"; anything else causes an exception to be thrown.
- aURL must be a valid URL; if the URL is invalid, an exception is thrown.
If either argument is omitted, the constructor throws an exception.
The remaining arguments are optional; if you specify null for these, the constructor substitutes default values or initializes them to null. The someHeaders argument (if not null) should be a dictionary whose String keys correspond to header names and whose values are arrays of one or more strings corresponding to the values of each header. The userInfo dictionary can contain any information that the WORequest object wants to pass along to other objects involved in handling the request.
For more information on each argument, see the description of the corresponding accessor method.
See Also: method, httpVersion (WOMessage class), content (WOMessage class), userInfo (WOMessage class)
Instance Methods
adaptorPrefix
public String adaptorPrefix()
See Also: applicationName, applicationNumber, uri
applicationName
public String applicationName()
See Also: adaptorPrefix, applicationNumber, uri
applicationNumber
public int applicationNumber()
See Also: applicationName, uri
applicationURLPrefix
public String applicationURLPrefix()
browserLanguages
public NSArray browserLanguages()
clone
public Object clone()
cookies
public NSArray cookies()
cookieValueForKey
public String cookieValueForKey(String aKey)
See Also: cookieValues, cookieValuesForKey, WOCookie class specification
cookieValues
public NSDictionary cookieValues()
See Also: cookieValueForKey, cookieValuesForKey, WOCookie class specification
cookieValuesForKey
public NSArray cookieValuesForKey(String aKey)
See Also: cookieValueForKey, cookieValues, WOCookie class specification
defaultFormValueEncoding
public String defaultFormValueEncoding()
See Also: setDefaultFormValueEncoding
formValueEncoding
public String formValueEncoding()
See Also: defaultFormValueEncoding, isFormValueEncodingDetectionEnabled
formValueForKey
public String formValueForKey(String aKey)
formValueKeys
public NSArray formValueKeys()
formValues
public NSDictionary formValues()
formValuesForKey
public NSArray formValuesForKey(String aKey)
isFormValueEncodingDetectionEnabled
public boolean isFormValueEncodingDetectionEnabled()
See Also: setFormValueEncodingDetectionEnabled
isFromClientComponent
public boolean isFromClientComponent()
If you use dynamic elements and write write HTML code in the response, you should check that the request is not from a client-side component before writing into the response.
isSessionIDInRequest
public boolean isSessionIDInRequest()
true
if the session ID can be obtained from the request. Note that the session ID may either be included among the form values or encapsulated within a cookie. Use WORequest's session() method to retrieve the value of the session ID from the request.
method
public String method()
See Also: content (WOMessage class), httpVersion (WOMessage class)
queryString
public String queryString()
requestHandlerKey
public String requestHandlerKey()
requestHandlerPath
public String requestHandlerPath()
requestHandlerPathArray
public NSArray requestHandlerPathArray()
sessionID
public String sessionID()
setDefaultFormValueEncoding
public void setDefaultFormValueEncoding(String anEncoding)
See Also: defaultFormValueEncoding, setFormValueEncodingDetectionEnabled
setFormValueEncodingDetectionEnabled
public void setFormValueEncodingDetectionEnabled(boolean flag)
See Also: isFormValueEncodingDetectionEnabled, setDefaultFormValueEncoding
toString
public String toString()
uri
public String uri()
See Also: adaptorPrefix, applicationName, applicationNumber
© 2001 Apple Computer, Inc. (Last Published April 15, 2001)