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.
| 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.
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
public WORequest(
String aMethod,
String anURL,
String anHTTPVersion,
NSDictionary someHeaders,
NSData aContent,
NSDictionary userInfo)
Returns a WORequest object initialized with
the specified parameters. The first two arguments are required:
- 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
public String adaptorPrefix()
Returns the part of the request's URI that is
specific to a particular adaptor. This is typically a URL ending
in "/WebObjects", "/WebObjects.exe", "/WebObjects.dll",
or uppercase versions of these strings. WebObjects uses a request's
adaptor prefix to set the adaptor prefix in the generated response's URL.
A WORequest must always have an adaptor prefix.See
Also: applicationName, applicationNumber, uri
public String applicationName()
Returns the part of the request's URI that identifies
the application the request is intended for. This name does not
include the ".woa" extension of an application directory.
A WORequest must always have an application name specified.See
Also: adaptorPrefix, applicationNumber, uri
public int applicationNumber()
Returns the part of the request's URI that identifies
the particular application instance the request is intended for.
This attribute is -1 if the request can be handled by any instance
of the application, which is always the case for the first request
in a session.See Also: applicationName, uri
public NSArray browserLanguages()
Returns the language preference list from the
user's browser.
public String cookieValueForKey(String aKey)
Returns a string value for the cookie key specified
by aKey.See
Also: cookieValues, cookieValuesForKey, WOCookie class specification
public NSDictionary cookieValues()
Returns a dictionary of cookie values and cookie
keys.See Also: cookieValueForKey, cookieValuesForKey, WOCookie class specification
public NSArray cookieValuesForKey(String aKey)
Returns an array of values for the cookie key
specified by aKey. Use this method
to retrieve information stored in a cookie in an HTTP header. Valid
keys are specified in the cookie specification.See
Also: cookieValueForKey, cookieValues, WOCookie class specification
public int defaultFormValueEncoding()
Returns the default string
encoding the WORequest object uses for converting form values from
ASCII to Unicode. It uses the default encoding only when it can
detect no encoding from the ASCII form values or if encoding detection
is disabled. If no default form-value encoding is set, NSISOLatin1StringEncoding
is used.See Also: setDefaultFormValueEncoding
public int formValueEncoding()
Returns the encoding last used to convert form
values from ASCII to Unicode. This encoding is either the result
of an earlier detection of form-value encoding or the default form
value encoding.See Also: defaultFormValueEncoding, isFormValueEncodingDetectionEnabled
public Object formValueForKey(String aKey)
Returns a form value identified by the name aKey.
If there are multiple form values identified by the same name,
only one of the values is returned, and which of these values is
not defined. You should use this method for names that you know
occur only once in the name/value pairs of form data.
public NSArray formValueKeys()
Returns an array of NSStrings corresponding
to the names (or keys) used to access values of a form. The array
is not sorted in any particular order, and is not necessarily sorted
in the same order on successive invocations of this method.
public NSDictionary formValues()
Returns an NSDictionary containing all of the
form data name/value pairs.
public NSArray formValuesForKey(String aKey)
Returns an array of all values (as Strings)
of the form identified by the name aKey.
This array is not sorted in any particular order, and is not necessarily
sorted in the same order on successive invocations of this method.
You should use this method when you know that a name (key) used
for accessing form data can be matched with more than one value.
public boolean isFormValueEncodingDetectionEnabled()
Returns whether detection of form-value encoding
is allowed to take place when form values are obtained.See
Also: setFormValueEncodingDetectionEnabled
public boolean isFromClientComponent()
Returns whether the request originated from
an event in a client-side component (that is, a Java applet that
can interact with the server side of a WebObjects application).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.
public String method()
Returns the method the WORequest object was
initialized with. A WORequest's method defines where it will look
for form values. The only currently supported methods are "GET"
and "PUT", which have the same meaning as the HTTP request
method tokens of the same name.See Also: content ( WOMessage class), httpVersion ( WOMessage class)
public String requestHandlerKey()
Returns the part of the request's URI which
identifies the request handler. This identifies the request handle
which will process the reuquest and cannot be null
public String requestHandlerPath()
Returns the part of the URL which identifies,
for a given request handler, which information is requested. Different
request handlers use this part of the URL in different ways.
public NSArray requestHandlerPathArray()
Returns the request handler path decomposed
into elements.
public String sessionID()
Returns the session ID, or null if no session
ID is found. This method first looks for the session ID in the URL,
then checks the form values, and finally checks to see if the session
ID is stored in a cookie.
public void setDefaultFormValueEncoding(int anEncoding)
Sets the default string encoding for the receiver
to use when converting its form values from ASCII to Unicode. The
default string encoding is called into play if the WORequest cannot
detect an encoding from the ASCII form values or if encoding detection
is disabled. If no default form value encoding is explicitly set,
the WORequest uses NSISOLatin1StringEncoding.See
Also: defaultFormValueEncoding, setFormValueEncodingDetectionEnabled
public void setFormValueEncodingDetectionEnabled(boolean flag)
Enables or disables automatic detection of the
best encoding for the receiver to use when it converts form values
from ASCII to Unicode. When detection is enabled, a WORequest
object scans the ASCII form values and applies heuristics to decide
which is the best encoding to use. If no specific encoding is discernible,
or if detection is disabled, the WORequest uses the default form
value encoding for the conversion.See Also: isFormValueEncodingDetectionEnabled, setDefaultFormValueEncoding
public String uri()
Returns the Uniform Resource Identifier (URI)
the WORequest was initialized with. For a session's first request,
the URI indicates the resource that the request is seeking (such
as a WebObjects application); for subsequent requests in the session,
the URI indicates which page of the application should handle the
request. If the request was caused (as is usually the case) by a
web browser submitting a URL to an HTTP server, the URI is that
part of the URL that follows the port number. Because the format
of WebObjects URLs and the corresponding request URI might change
between different versions of WebObjects, you should not attempt
to parse the URI returned by this method. Instead, use WORequest's
accessor methods to access particular URI/URL components.See
Also: adaptorPrefix, applicationName, applicationNumber
