Class next.wo.Request

CLASS DESCRIPTION

Extends:
next.util.NextObject

A Request object typically represents an HTTP request and thus constitutes an event that requires a reaction from a WebObjects application. Request 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 Request object and sends that object to the application (through WebApplication's handleRequest method).

Request 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, Request 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 Request objects, and since you can usually use WebObjects' adaptors without modifications, you probably won't have to create your own instances of Request in your code (although you can if you need to). More typically, your code will obtain information from Request objects as they become available during certain points in the request-response loop. The application supplies Request objects as arguments in the takeValuesFromRequest and invokeAction methods, which are implementable by WebApplication, WebSession, Component, and Element objects. You can also obtain the current Request object at any time during request handling through Context's request method.

Note: Because Request 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 Request objects. A recommended prerequisite therefore is to review the current HTTP specification or HTTP documentation.


URIs and the Parts of a WebObjects URL

Request's uri method returns the Universal Resource Identifier (URI) for the request. 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. The port number, if specified, immediately follows the server host name (if not specified, the port number defaults to 80). For example, if a request is caused by a browser submitting the URL

    http://www.foo.com/cgi-bin/WebObjects/Examples/Java/HelloWorldJava

the request's URI is

    /cgi-bin/WebObjects/Examples/Java/HelloWorldJava

Many Request methods return parts of the URI:

For a graphic depicting the parts of a WebObjects URL, see the description of the Context class.


CONSTRUCTORS

Request

public Request()
public Request(java.lang.String aString, java.lang.String aString, java.lang.String aString, next.util.ImmutableHashtable anImmutableHashtable, next.util.ImmutableBytes anImmutableBytes, next.util.ImmutableHashtable anImmutableHashtable)

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

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


METHODS

adaptorPrefix

public java.lang.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 Request must always have an adaptor prefix.

See Also: applicationHost, applicationName, applicationNumber, contextID, pageName, senderID, sessionID, uri


applicationHost

public java.lang.String applicationHost()

Returns the part of the request's URI that identifies the host server of the particular application instance assigned to handle the request. This attribute is null if any instance of the application can handle the request, which is always the case for the first request in a session.

See Also: adaptorPrefix, applicationName, applicationNumber, contextID, pageName, senderID, sessionID, uri


applicationName

public java.lang.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 Request must always have an application name specified.

See Also: adaptorPrefix, applicationHost, applicationNumber, contextID, pageName, senderID, sessionID, uri


applicationNumber

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 null 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: adaptorPrefix, applicationHost, applicationName, contextID, pageName, senderID, sessionID, uri


content

public next.util.ImmutableBytes content()

Returns the content the Request was initialized with (which defaults to null). 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


contextID

public java.lang.String contextID()

Returns the part of the request's URI that identifies the context (or the transaction) that generated the request page. A Request's context ID will be null if and only if it represents the first request in a session.

See Also: adaptorPrefix, applicationHost, applicationName, applicationNumber, pageName, senderID, sessionID, uri


defaultFormValueEncoding

public int defaultFormValueEncoding()

Returns the default string encoding the Request 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

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


formValueForKey

public java.lang.String formValueForKey(java.lang.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.


formValueKeys

public next.util.ImmutableVector formValueKeys()

Returns an array of Strings 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.


formValuesForKey

public next.util.ImmutableVector formValuesForKey(java.lang.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.


headerForKey

public java.lang.String headerForKey(java.lang.String 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 calls to 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

public next.util.ImmutableVector 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 calls to this method.


headersForKey

public next.util.ImmutableVector headersForKey(java.lang.String aKey)

Returns the values of a particular header that is identified by aKey. The returned object contains Strings 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

public java.lang.String httpVersion()

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


isFormValueEncodingDetectionEnabled

public boolean isFormValueEncodingDetectionEnabled()

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

See Also: setFormValueEncodingDetectionEnabled


isFromClientComponent

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


method

public java.lang.String method()

Returns the method the Request object was initialized with. A Request'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


pageName

public java.lang.String pageName()

Returns the part of the Request's URI that identifies the destination page for the request (that is, the name of the Component representing the page). This name does not include the component directory's ".wo" extension. A request always has a non-null page name.

See Also: adaptorPrefix, applicationHost, applicationName, applicationNumber, contextID, senderID, sessionID, uri


senderID

public java.lang.String senderID()

Returns the part of the Request'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.

See Also: adaptorPrefix, applicationHost, applicationName, applicationNumber, contextID, pageName, sessionID , uri


sessionID

public java.lang.String sessionID()

Returns the part of the request's URI that identifies the session the request belongs to. A request's session ID is null if and only if a request is the first request in a session.

See Also: adaptorPrefix, applicationHost, applicationName, applicationNumber, contextID, pageName, senderID, uri


setDefaultFormValueEncoding

public void setDefaultFormValueEncoding(int anInt)

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 Request 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 Request uses NSISOLatin1StringEncoding.

See Also: defaultFormValueEncoding, setFormValueEncodingDetectionEnabled


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 Request 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 Request uses the default form value encoding for the conversion.

See Also: isFormValueEncodingDetectionEnabled, setDefaultFormValueEncoding


uri

public java.lang.String uri()

Returns the Uniform Resource Identifier (URI) the Request was initialized with. (See "URIs and the Parts of a WebObjects URL," above, for an explanation of URIs.) 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 Request's accessor methods to access particular URI/URL components.

See Also: adaptorPrefix, applicationHost, applicationName, applicationNumber, contextID, pageName, senderID, sessionID


userInfo

public next.util.ImmutableHashtable userInfo()

Returns the value of the user information the receiver was initialized with (null 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.