|
WebObjects 5.2 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.webobjects.appserver.WOMessage | +--com.webobjects.appserver.WORequest
A request object represents an event that requires a reaction from a WebObjects application. In fact, a WebObjects application can be defined as something that receives request objects, handles them, and returns appropriate responses.
Usually, request objects are generated when users performs actions in their web browsers such as entering the URL of a WebObjects application or clicking on a hyperlink, button, or image map in a WebObjects application page. Such actions causes the browser to send an HTTP request to an HTTP server, which forwards that HTTP request to a WebObjects adaptor, which converts it to a request object and sends that to the application. Request objects can also be created from HTTP requests sent by client-side components, Java applets, or applications that use the Java classes supplied with WebObjects to interact with a WebObjects application -- and from HTTP requests submitted by custom written client-side programs that don't use the Java client-side component classes. Finally, but more rarely, request objects can be created by custom written adaptors that handle HTTP requests or non-HTTP events. All the adaptors shipped with WebObjects handle HTTP events only.
Since request objects are usually created by an adaptor, and since you will
usually be able to use WebObjects adaptors without modifications, you will
probably not have to create instances of WORequest or its subclasses
in your code, though you can if you need to. More typically, your code
will be obtaining information from request objects provided to it by the
WebObjects Framework. 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. Request objects can also be obtained at any time
during request handling through methods on WOContext. See these classes
for more details.
Note: 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.
As stated above, in most WebObjects applications WORequest objects are created for user; the 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, the 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 the user to extract
information from a WORequest object. WORequest inherits a number of
methods from WOMessage, however, that allow the user to programmatically
specify the contents of a request. In particular, the appendContent
and setContent
methods in the WOMessage class are designed to do this.
WOContext.request()
,
WOMessage.headerForKey(Object aKey)
,
WOMessage.headerKeys()
,
WOMessage.headers()
,
WOMessage.headersForKey(Object aKey)
,
WOMessage.content()
,
WOMessage
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 |
Field Summary | |
static String |
ContextIDKey
String used by the WOComponentRequestHandler to store and retrieve the request's context ID from an NSDictionary. |
static String |
DataKey
String key used to obtain a key from another request. |
static String |
InstanceKey
String key used to obtain the application instance number from a request using methods like formValueForKey(String) and cookieValueForKey(String) . |
static String |
PageNameKey
String used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's page name. |
static String |
SenderIDKey
String used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's sender ID. |
static String |
SessionIDKey
String key used to obtain the session ID from a request using methods like formValueForKey(String) and cookieValueForKey(String) . |
static int |
SingleInstanceID
int, containing the application number used by applications deployed in single instance mode. |
static String |
SingleInstanceIDString
String containing the application number used by applications deployed in single instance mode. |
Fields inherited from class com.webobjects.appserver.WOMessage |
HTTP_STATUS_FORBIDDEN, HTTP_STATUS_FOUND, HTTP_STATUS_INTERNAL_ERROR, HTTP_STATUS_MOVED_PERMANENTLY, HTTP_STATUS_NO_CONTENT, HTTP_STATUS_NOT_FOUND, HTTP_STATUS_OK, TheDefaultResponseEncoding |
Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding |
NullValue |
Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions |
KeyPathSeparator |
Constructor Summary | |
WORequest(String aMethod,
String aURL,
String anHTTPVersion,
NSDictionary someHeaders,
NSData aContent,
NSDictionary aDictionary)
Returns a WORequest object initialized with the specified parameters. |
Method Summary | |
String |
adaptorPrefix()
Returns a String containing the part of the request's URI that is specific to a particular adaptor. |
String |
applicationName()
Returns a String containing the name of the application taken from the URI. |
int |
applicationNumber()
Returns a String containing the part of the request's URI indicating the specific application instance this request is intended for. |
String |
applicationURLPrefix()
Return the prefix of the URL used to access the application instance up to and including the application number. |
NSArray |
browserLanguages()
Returns an NSArray containing the language preference list as sent by the client, generally a browser. |
Object |
clone()
|
InputStream |
contentInputStream()
Returns the content of this request, represented as an InputStream, if the content has not been accessed in any other manner. |
NSArray |
cookies()
Returns an NSArray containing all cookies packaged as WOCookie objects. |
String |
cookieValueForKey(String aKey)
Returns the first value in the request for the given cookie name as specified by aKey . |
NSDictionary |
cookieValues()
Returns an NSDictionary containing the values for all cookies in the request. |
NSArray |
cookieValuesForKey(String aKey)
Returns all values for the given cookie name specified by aKey . |
NSTimestamp |
dateFormValueForKey(String aKey,
NSTimestampFormatter dateFormatter)
Method to return an NSTimestamp for a form value from the request for a specific name (key). |
String |
defaultFormValueEncoding()
Returns the default string encoding the WORequest object uses for converting form values from ASCII to Unicode. |
String |
formValueEncoding()
Returns the encoding last used to convert form values from ASCII to Unicode. |
Object |
formValueForKey(String aKey)
Return an Object representing the form value for aKey . |
NSArray |
formValueKeys()
Returns an NSArray containing the names (or keys) used to access the values in a form. |
NSDictionary |
formValues()
Returns an NSDictionary containing all of the form data with names for keys and NSArrays containing the value(s) associated with those keys for values. |
NSArray |
formValuesForKey(String aKey)
Returns an NSArray containing the String form values associated with the given key. |
boolean |
isFormValueEncodingDetectionEnabled()
Return whether or not automatic detection of form value encoding is enabled. |
boolean |
isFromClientComponent()
Deprecated. isFromClientComponent() is deprecated as the Client Side Components Feature are not supported anymore |
boolean |
isMultipartFormData()
Returns true if this WORequest represents multipart form data. |
boolean |
isSessionIDInRequest()
Returns 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. |
boolean |
isUsingWebServer()
Returns true if the request is using a
webserver, false otherwise. |
String |
method()
A WORequest's method defines where it will look for form values. |
WOMultipartIterator |
multipartIterator()
Returns the WOMultipartIterator for this request. |
Number |
numericFormValueForKey(String aKey,
NSNumberFormatter numericFormatter)
Method to return a Number for a form value from the request for a specific name (key). |
String |
queryString()
Returns, as a String, the query string of the URI. |
String |
requestHandlerKey()
Returns a String identifying the request handler that will process the request. |
String |
requestHandlerPath()
Returns a String containing the part of the URL which identifies, for a given request handler, which information is requested. |
NSArray |
requestHandlerPathArray()
Returns an NSArray containing the request handler path decomposed into elements. |
String |
sessionID()
Returns the session ID if there is one. |
void |
setDefaultFormValueEncoding(String anEncoding)
Sets the default string encoding for the receiver to use when converting its form values from ASCII to Unicode. |
void |
setFormValueEncodingDetectionEnabled(boolean aFlag)
Enables or disables automatic detection of the best encoding for the receiver to use when it converts form values from ASCII to Unicode. |
String |
stringFormValueForKey(String aKey)
Method to return a String form value from the request for a specific name (key). |
String |
toString()
Returns a string version of the receiver for use when debugging. |
String |
uri()
Returns the Uniform Resource Identifier (URI) the WORequest was initialized with. |
Methods inherited from class java.lang.Object |
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final String ContextIDKey
public static final String DataKey
urlWithRequestHandlerKey
method). Use Methods
like formValueForKey(String)
and cookieValueForKey(String)
when querying the request with the DataKey.public static final String InstanceKey
formValueForKey(String)
and cookieValueForKey(String)
.public static final String PageNameKey
public static final String SenderIDKey
public static final String SessionIDKey
formValueForKey(String)
and cookieValueForKey(String)
.public static final int SingleInstanceID
public static final String SingleInstanceIDString
Constructor Detail |
public WORequest(String aMethod, String aURL, String anHTTPVersion, NSDictionary someHeaders, NSData aContent, NSDictionary aDictionary)
aMethod
must be either "GET", "POST" or "HEAD". Additional methods
can be allowed by using a custom subclass.aURL
a URL.anHTTPVersion
the HTTP version string. Typically "HTTP/1.0" or "HTTP/1.1".If any of the above three arguments are omitted, the constructor throws an exception.
The remaining arguments are optional; if null
is specified,
the constructor will either substitute default values or initialize
them to null
. If not null
, the someHeaders
argument should be a dictionary whose String keys correspond
to header field-names and whose values are arrays of one or more strings
corresponding to the field-value(s) of each header. The aDictionary
dictionary can contain any information that the WORequest object wants to
pass along to other objects involved in handling the request.
aMethod
- a "GET", "POST" or "HEAD", may not be null. If null, or not one of the allowed
methods, an IllegalArgumentException will be thrown.aURL
- a URL, may not be null or an IllegalArgumentException will be thrown.anHTTPVersion
- the version of HTTP used when sending the message, may not be null
or an IllegalArgumentException will be thrown.someHeaders
- 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 headeraContent
- the HTML contentaDictionary
- contain any information that the
WORequest object wants to pass along to other objectsmethod()
,
WOMessage.httpVersion()
,
WOMessage.content()
,
WOMessage.userInfo()
,
WOMessage.headers()
Method Detail |
public String adaptorPrefix()
A WORequest must always have an adaptor prefix specified: if the application is
contacted using direct connect and an adaptor prefix is not supplied, the
value returned by WOApplication's cgiAdaptorURL
method will be used.
applicationName()
,
applicationNumber()
,
queryString()
,
requestHandlerKey()
,
requestHandlerPath()
,
uri()
,
WOApplication.cgiAdaptorURL()
public String applicationName()
name
method will be used.adaptorPrefix()
,
applicationNumber()
,
queryString()
,
requestHandlerKey()
,
requestHandlerPath()
,
uri()
,
WOApplication.name()
public int applicationNumber()
adaptorPrefix()
,
applicationName()
,
queryString()
,
requestHandlerKey()
,
requestHandlerPath()
,
uri()
public String applicationURLPrefix()
adaptorPrefix
,
the applicationName
, and the applicationNumber
.adaptorPrefix()
,
applicationName()
,
applicationNumber()
public NSArray browserLanguages()
public Object clone()
clone
in class WOMessage
public InputStream contentInputStream()
content
or contentData
have been invoked previously, this method will return null.
This method will also return null if :
1. This WORequest is of type multipart/form-data, AND
2. either formValues
or the multipartIterator
were called previously.
To be able to use this method in a Direct Action, you must access the Direct Action through
the streamActionRequestHandlerKey() defined in WOApplication. This key defaults
to "wis"
. In addition, the session (if any) can only be located in the URL or the cookies
of the request, never in the form values. Because this API is expected to
supercede all other methods of accessing the content of the request, do not expect the
content to be parsed in any way.
public String cookieValueForKey(String aKey)
aKey
. Names are case sensitive. For more information about cookies, please see the Netscape cookie specification at: http://www.netscape.com/newsref/std/cookie_spec.html
aKey
- cookie name whose values are being queriedaKey
cookieValues()
,
cookieValuesForKey(String aKey)
,
WOCookie
public NSDictionary cookieValues()
For more information about cookies, please see the Netscape cookie specification at: http://www.netscape.com/newsref/std/cookie_spec.html
cookieValueForKey(String aKey)
,
cookieValuesForKey(String aKey)
,
WOCookie
public NSArray cookieValuesForKey(String aKey)
aKey
. Names are case sensitive. For more information about cookies, please see the Netscape cookie specification at: http://www.netscape.com/newsref/std/cookie_spec.html
aKey
- cookie name whose values are being requestedaKey
cookieValues()
,
cookieValueForKey(String aKey)
,
WOCookie
public NSArray cookies()
cookies
in class WOMessage
public NSTimestamp dateFormValueForKey(String aKey, NSTimestampFormatter dateFormatter)
null
if it can't cast the form value into a valid
NSTimestamp or if the key can't be found.aKey
- the form value to check fordateFormatter
- the formatter used to coerce the form value to a date value.formValueForKey(String aKey)
,
formValuesForKey(String aKey)
,
stringFormValueForKey( String aKey )
,
numericFormValueForKey( String aKey, NSNumberFormatter numericFormatter )
public String defaultFormValueEncoding()
defaultEncoding
is used.setDefaultFormValueEncoding(String anEncoding)
,
WOMessage.defaultEncoding()
public String formValueEncoding()
defaultFormValueEncoding()
,
setDefaultFormValueEncoding(String anEncoding)
,
isFormValueEncodingDetectionEnabled()
public Object formValueForKey(String aKey)
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 (keys) that you know occur only once in
the name/value pairs of form data.aKey
- name of the form valueaKey
formValueKeys()
,
formValuesForKey(String aKey)
,
stringFormValueForKey( String aKey )
public NSArray formValueKeys()
formValueForKey(String aKey)
,
formValuesForKey(String aKey)
public NSDictionary formValues()
If this request represents multipart form data, this method behaves differently.
In particular, when invoked, it parses the content (using a WOMultipartIterator)
until it reaches the first file upload, indicated by the presence of a "filename"
sub-header in the content-disposition form headers. It will place that form part
into the form values. If that file has been read into memory or the content read
in some other way, it continues iterating. Otherwise, it stops there.
Subsequent calls to formValues
will continue the parsing, when possible.
When contentInputStream
is invoked before this method, and
this WORequest represents multipart form data, an IllegalStateException is thrown.
The original behavior of this method, which is to read the entire request content into
memory and parse it for form values, can be restored by setting the System property
"WOUseLegacyMultipartParser"
to true
. In this case, the
WOMultipartIterator will not be accessible, and all the form values will be parsed
completely the first time this method is called.
IllegalStateException
- when the content of a multipart request has been accessed through some other means.formValueForKey(String aKey)
,
formValuesForKey(String aKey)
public NSArray formValuesForKey(String aKey)
aKey
- name of the form valueaKey
formValueKeys()
,
formValueForKey(String aKey)
public boolean isFormValueEncodingDetectionEnabled()
true
if detection of form-value encoding is allowed to
take place when form values are obtained, false
otherwisedefaultFormValueEncoding()
,
setFormValueEncodingDetectionEnabled(boolean flag)
public boolean isFromClientComponent()
public boolean isMultipartFormData()
true
if this WORequest represents multipart form data.
Essentially, it checks the value of the content-type header for the type "multipart/form-data".true
this WORequest is multipart/form-data.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. WORequest's session()
method is used
to retrieve the value of the session ID from the request.true
if the session ID can be obtained from the form values or a cookie.public boolean isUsingWebServer()
true
if the request is using a
webserver, false
otherwise.public String method()
WOMessage.content()
,
WOMessage.httpVersion()
public WOMultipartIterator multipartIterator()
null
; otherwise
if contentInputStream
has been called previously, this method returns null
.public Number numericFormValueForKey(String aKey, NSNumberFormatter numericFormatter)
null
if it can't cast the form value into a Number or if the key
can't be found.aKey
- the form value to check fornumericFormatter
- the formatter used to coerce the form value to a numeric value.formValueForKey(String aKey)
,
formValuesForKey(String aKey)
,
dateFormValueForKey( String aKey , NSTimestampFormatter dateFormatter )
,
stringFormValueForKey( String aKey )
public String queryString()
null
if there is no query string.adaptorPrefix()
,
applicationName()
,
applicationNumber()
,
requestHandlerKey()
,
requestHandlerPath()
,
uri()
public String requestHandlerKey()
null
. The requestHandlerKey
occurs in the URI after the applicationName
and
applicationNumber
, if one exists.adaptorPrefix()
,
applicationName()
,
applicationNumber()
,
queryString()
,
requestHandlerPath()
,
uri()
,
WOApplication.requestHandlerForKey(String aKey)
,
WORequestHandler
public String requestHandlerPath()
requestHandlerKey
and the queryString
.adaptorPrefix()
,
applicationName()
,
applicationNumber()
,
queryString()
,
requestHandlerKey()
,
requestHandlerPathArray()
,
uri()
public NSArray requestHandlerPathArray()
requestHandlerKey
and the queryString
. This String is broken into tokens using
'/' as a delimiter.adaptorPrefix()
,
applicationName()
,
applicationNumber()
,
queryString()
,
requestHandlerKey()
,
requestHandlerPath()
,
uri()
public String sessionID()
null
if no session ID is foundpublic void setDefaultFormValueEncoding(String anEncoding)
defaultEncoding
.anEncoding
- String the default String encodingdefaultFormValueEncoding()
,
setFormValueEncodingDetectionEnabled(boolean flag)
,
WOMessage.defaultEncoding()
public void setFormValueEncodingDetectionEnabled(boolean aFlag)
aFlag
- enables or disables automatic detection of the best
encoding for the receiver to usedefaultFormValueEncoding()
,
setDefaultFormValueEncoding(String anEncoding)
,
isFormValueEncodingDetectionEnabled()
public String stringFormValueForKey(String aKey)
null
.aRequest
- the WORequest with the form valuesaKey
- the form value to check forformValueForKey(String aKey)
,
formValuesForKey(String aKey)
,
dateFormValueForKey( String aKey , NSTimestampFormatter dateFormatter )
,
numericFormValueForKey( String aKey, NSNumberFormatter numericFormatter )
public String toString()
toString
in class WOMessage
public String uri()
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.
adaptorPrefix()
,
applicationName()
,
applicationNumber()
,
queryString()
,
requestHandlerKey()
,
requestHandlerPathArray()
|
Last updated Fri Feb 21 13:15:00 PST 2003. | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |