PATH  WebObjects 4.0 Documentation > WebObjects Framework Reference



WORequest

Inherits From:
NSObject

Declared in: WebObjects/WORequest.h


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 a HTTP server in a request. Requests 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. More rarely, 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:inContext: and invokeActionForRequest:inContext: 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.


Adopted Protocols

NSCopying
- copy
- copyWithZone:

Method Types

Working with cookies
- cookieValueForKey:
- cookieValues
- cookieValuesForKey:
Form values
- defaultFormValueEncoding
- formValueEncoding
- formValueForKey:
- formValueKeys
- formValues
- formValuesForKey:
- isFormValueEncodingDetectionEnabled
Headers
- headerForKey:
- headerKeys
- headersForKey:
Request handling
- requestHandlerKey
- requestHandlerPath
- requestHandlerPathArray
Form Values
- setDefaultFormValueEncoding:
- setFormValueEncodingDetectionEnabled:
Obtaining attributes
- adaptorPrefix
- applicationName
- applicationNumber
- browserLanguages
- content
- httpVersion
- isFromClientComponent
- initWithMethod:uri:httpVersion:headers:content:userInfo:
- method
- uri
- userInfo

Instance Methods


adaptorPrefix

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


applicationName

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


applicationNumber

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


browserLanguages

- (NSArray *)browserLanguages

Returns the language preference list from the user's browser.


content

- (NSData *)content

Returns the content the WORequest was initialized with (which defaults to nil ). The format of the data is undefined, but you can usually identify it by the value of the "content-type" header.

See also: - httpVersion , - method


cookieValueForKey:

- (NSString *)cookieValueForKey: (NSString *)aKey

Returns a string value for the cookie key specified by aKey.

See also: - cookieValues , - cookieValuesForKey: , WOCookie class specification


cookieValues

- (NSDictionary *)cookieValues

Returns a dictionary of cookie values and cookie keys.

See also: - cookieValueForKey: , - cookieValuesForKey: , WOCookie class specification


cookieValuesForKey:

- (NSArray *)cookieValuesForKey: (NSString *)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


defaultFormValueEncoding

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


formValueEncoding

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


formValueForKey:

- id formValueForKey: (NSString *)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.


formValueKeys

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


formValues

- (NSDictionary *)formValues

Returns an NSDictionary containing all of the form data name/value pairs.


formValuesForKey:

- (NSArray *)formValuesForKey: (NSString *)aKey

Returns an array of all values (as NSStrings) 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.


headerForKey:

- (NSString *)headerForKey: (NSString *)aKey

Returns one value of a particular header in the header dictionary the request was initialized with. This will be a string corresponding to one of the values of the header whose name is passed in as the key argument. If the specified header has multiple values, only one of these values is returned, and which one of them this is is not defined. However, on successive invocations of this method, the same value will always be returned. This method is intended to be used for headers that are known to have only one value.


headerKeys

- (NSArray *)headerKeys

Returns an array of the keys of the header dictionary the request was initialized with (which default to an empty dictionary). This will be an array of strings corresponding to the headers' names. The array is not sorted in any particular order, and not necessarily sorted in the same order on successive invocations of this method.


headersForKey:

- (NSArray *)headersForKey: (NSString *)aKey

Returns the values of a particular header that is identified by aKey. The returned object contains NSStrings sorted in no particular order, but which will always be sorted in the same order on successive invocations of this method. Use this method for headers that you know have (or can have) multiple values.


httpVersion

- (NSString *)httpVersion

Returns the HTTP version the request was initialized with. An application uses the WORequest's HTTP version to initialize the HTTP version of the response that is generated by request handling. The WORequest's HTTP version typically derives from the HTTP version of the client (for example, the browser) that initiated the request.


initWithMethod:uri:httpVersion:headers:content:userInfo:

- (id)initWithMethod: (NSString *)aMethod uri: (NSString *)aURL httpVersion: (NSString *)anHTTPVersion headers: (NSDictionary *)someHeaders content: (NSData *)aContent userInfo: (NSDictionary *)userInfo

Returns a WORequest object initialized with the specified parameters. The first two arguments are required:

If either argument is omitted, an exception is raised.

The remaining arguments are optional; if you specify nil for these, the designated initializer substitutes default values or initializes them to nil . The someHeaders argument (if not nil ) should be a dictionary whose NSString 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.


isFormValueEncodingDetectionEnabled

- (BOOL)isFormValueEncodingDetectionEnabled

Returns whether detection of form-value encoding is allowed to take place when form values are obtained.

See also: - setFormValueEncodingDetectionEnabled:


isFromClientComponent

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


method

- (NSString *)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 , - httpVersion


requestHandlerKey

- (NSString *)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.


requestHandlerPath

- (NSString *)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.


requestHandlerPathArray

- (NSArray *)requestHandlerPathArray

Returns the request handler path decomposed into elements.


sessionID

- (NSString *)sessionID

Returns the session ID, or nil 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.


setDefaultFormValueEncoding:

- (void)setDefaultFormValueEncoding: (NSStringEncoding)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:


setFormValueEncodingDetectionEnabled:

- (void)setFormValueEncodingDetectionEnabled: (BOOL)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:


uri

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


userInfo

- (NSDictionary *)userInfo

Returns the value of the user information the receiver was initialized with (nil by default). WebObjects imposes no restrictions on the format or content of the user information dictionary. In fact, WebObjects classes do not themselves use the dictionary, but just pass it around as the request is handled. Custom adaptors, for example, could initialize the dictionary with special information for other objects of an application.





Copyright © 1998, Apple Computer, Inc. All rights reserved.