com.webobjects.appserver
Class WORequest

java.lang.Object
  com.webobjects.appserver.WOMessage
      com.webobjects.appserver.WORequest

All Implemented Interfaces:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, Cloneable

public class WORequest
extends WOMessage
implements Cloneable

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.

See Also:

WOContext.request(), WOMessage.headerForKey(Object aKey), WOMessage.headerKeys(), WOMessage.headers(), WOMessage.headersForKey(Object aKey), WOMessage.content(), WOMessage

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static String	ApplicationInstanceKey Deprecated.
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 Deprecated.
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	ServerPortHeader Defaults to SERVER_PORT
static String	ServerPortHeaderX Defaults to x-webobjects-server-port
static String	ServerPortSecureValue Defaults to 443
static String	SessionIDKey Deprecated.
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, map, TheDefaultResponseEncoding

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

protected	WORequest()
	WORequest(String aMethod, String aURL, String anHTTPVersion, Map someHeaders, NSData aContent, Map aUserInfoDictionary) 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.
static String	ajaxFormSubmitKey() Return the key used in the form values to identify a AJAX form sumit.
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.
protected String	contentType() Gets the value of the content type header.
WOContext	context() Return the context for the request.
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) Deprecated. since5.4
NSTimestamp	dateFormValueForKey(String aKey, SimpleDateFormat 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.
protected String	detectFormValuesEncoding(String content) Return detected encoding for form values
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.
protected NSDictionary	getFormValuesFromMultipartFormData() Returns the form values from the multipart iterator.
protected NSDictionary	getFormValuesFromURLEncoding()
boolean	isAjaxSubmit() Returns true if the request is using an AJAX request, false otherwise.
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.
protected boolean	isRequestFromFormSubmission() Checks is the request is the result of a Form submission.
boolean	isSecure() Returns the secure state of the request
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.
protected boolean	isWhitespaceOrNull(char value) Detect if a char is a whitespace or null character
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).
WOAdaptor	originatingAdaptor() Returns the adaptor that originated this request or null if this request was not created by an Adaptor.
String	queryString() Returns, as a String, the query string of the URI.
protected String	removeCRLF(String value) Process given string with CRLF chars removed
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.
static void	setAjaxFormSubmitKey(String value) Set the key in the form values used to identify a AJAX form sumit.
void	setContext(WOContext value) Sets the context for the request.
void	setDefaultFormValueEncoding(String anEncoding) Sets the default string encoding for the receiver to use when converting its form values from ASCII to Unicode.
protected void	setFormValueEncoding(String value) Sets the form value encoding
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.
protected boolean	useLegacyMultipart()

Methods inherited from class com.webobjects.appserver.WOMessage

addCookie, appendContentCharacter, appendContentData, appendContentDOMDocumentFragment, appendContentHTMLAttributeValue, appendContentHTMLString, appendContentString, appendHeader, appendHeaders, canAccessFieldsDirectly, content, contentAsDOMDocument, contentEncoding, contentString, defaultEncoding, defaultHeaderEncoding, defaultURLEncoding, equals, handleQueryWithUnboundKey, handleTakeValueForUnboundKey, hasHeaderForKey, headerForKey, headerForKey, headerKeys, headers, headersForKey, httpVersion, removeCookie, removeHeadersForKey, requiresHTMLEscaping, setContent, setContent, setContent, setContent, setContentDOMDocument, setContentEncoding, setDefaultEncoding, setDefaultHeaderEncoding, setDefaultURLEncoding, setHeader, setHeaders, setHeaders, setHTTPVersion, setStorePageInBacktrackCache, setUserInfo, setUserInfoForKey, storePageInBacktrackCache, stringByEscapingHTMLAttributeValue, stringByEscapingHTMLString, takeValueForKey, takeValueForKeyPath, unableToSetNullForKey, userInfo, userInfoForKey, valueForKey, valueForKeyPath

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SessionIDKey

@Deprecated
public static final String SessionIDKey

Deprecated.

String key used to obtain the session ID from a request using methods like formValueForKey(String) and cookieValueForKey(String).

Since:

5.4

See Also:

WOApplication.sessionIdKey(), Constant Field Values

InstanceKey

@Deprecated
public static final String InstanceKey

Deprecated.

String key used to obtain the application instance number from a request using methods like formValueForKey(String) and cookieValueForKey(String).

Since:

5.4

See Also:

WOApplication.instanceIdKey(), Constant Field Values

ApplicationInstanceKey

@Deprecated
public static final String ApplicationInstanceKey

Deprecated.

String key used to obtain the application unique instance identifier from a request using methods like formValueForKey(String) and cookieValueForKey(String).

Since:

5.4

See Also:

WOApplication.sessionIdKey(), Constant Field Values

DataKey

public static final String DataKey

String key used to obtain a key from another request. 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 urlWithRequestHandlerKeymethod). Use Methods like formValueForKey(String) and cookieValueForKey(String) when querying the request with the DataKey.

See Also:

Constant Field Values

ContextIDKey

public static final String ContextIDKey

String used by the WOComponentRequestHandler to store and retrieve the request's context ID from an NSDictionary.

See Also:

Constant Field Values

SenderIDKey

public static final String SenderIDKey

String used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's sender ID.

See Also:

Constant Field Values

PageNameKey

public static final String PageNameKey

String used by the WOComponentRequestHandler to store to and retrieve from an NSDictionary the request's page name.

See Also:

Constant Field Values

SingleInstanceIDString

public static final String SingleInstanceIDString

String containing the application number used by applications deployed in single instance mode.

See Also:

Constant Field Values

SingleInstanceID

public static final int SingleInstanceID

int, containing the application number used by applications deployed in single instance mode.

See Also:

Constant Field Values

ServerPortHeader

public static final String ServerPortHeader

Defaults to SERVER_PORT

Since:

5.4

See Also:

Constant Field Values

ServerPortHeaderX

public static final String ServerPortHeaderX

Defaults to x-webobjects-server-port

Since:

5.4

See Also:

Constant Field Values

ServerPortSecureValue

public static final String ServerPortSecureValue

Defaults to 443

Since:

5.4

See Also:

Constant Field Values

Constructor Detail

WORequest

public WORequest(String aMethod,
                 String aURL,
                 String anHTTPVersion,
                 Map someHeaders,
                 NSData aContent,
                 Map aUserInfoDictionary)

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

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

Parameters:

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 header

aContent - the HTML content

aUserInfoDictionary - java.util.Map that contains any information that the WORequest object wants to pass along to other objects

See Also:

WORequest.method(), WOMessage.httpVersion(), WOMessage.content(), WOMessage.userInfo(), WOMessage.headers()

WORequest

protected WORequest()

Method Detail

isSecure

public boolean isSecure()

Returns the secure state of the request

Returns:

true if the request appears to have been made over a secure connection

context

public WOContext context()

Return the context for the request. Note this create the context it it was not already initialized.

Returns:

WOContext context request is set to

Since:

5.4

setContext

public void setContext(WOContext value)

Sets the context for the request.

Parameters:

value - WOContext to set

Since:

5.4

originatingAdaptor

public WOAdaptor originatingAdaptor()

Returns the adaptor that originated this request or null if this request was not created by an Adaptor.

Returns:

originating adaptor

Since:

5.4

clone

public Object clone()

Overrides:

clone in class WOMessage

toString

public String toString()

Returns a string version of the receiver for use when debugging. The returned String includes the URI, information on how the form values are encoded, and the form values themselves.

Overrides:

toString in class WOMessage

Returns:

String representation of the WORequest

contentInputStream

public InputStream contentInputStream()

Returns the content of this request, represented as an InputStream, if the content has not been accessed in any other manner. Thus, if content or contentData have been invoked previously, this method will return null.
In general, this means that this will only be useful for some DirectActions.

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.

Returns:

InputStream backing the WORequest content or null

method

public String method()

A WORequest's method defines where it will look for form values. The only currently supported methods are "GET", "POST" and "HEAD", which have the same meaning as the HTTP request method tokens of the same name.

Returns:

the method the WORequest object was initialized with

See Also:

WOMessage.content(), WOMessage.httpVersion()

uri

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.

Returns:

the URI the WORequest was initialized with

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.applicationNumber(), WORequest.queryString(), WORequest.requestHandlerKey(), WORequest.requestHandlerPathArray()

requestHandlerKey

public String requestHandlerKey()

Returns a String identifying the request handler that will process the request. This String cannot be null. The requestHandlerKey occurs in the URI after the applicationName and applicationNumber, if one exists.

Returns:

String part of the request's URI which identifies the request handler

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.applicationNumber(), WORequest.queryString(), WORequest.requestHandlerPath(), WORequest.uri(), WOApplication.requestHandlerForKey(String aKey), WORequestHandler

requestHandlerPathArray

public NSArray requestHandlerPathArray()

Returns an NSArray containing the request handler path decomposed into elements. The request handler path is everything in the URI between the requestHandlerKey and the queryString. This String is broken into tokens using '/' as a delimiter.

Returns:

NSArray containing the request handler path decomposed into elements

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.applicationNumber(), WORequest.queryString(), WORequest.requestHandlerKey(), WORequest.requestHandlerPath(), WORequest.uri()

browserLanguages

public NSArray browserLanguages()

Returns an NSArray containing the language preference list as sent by the client, generally a browser.

Returns:

the language preference list from the user's browser

adaptorPrefix

public String adaptorPrefix()

Returns a String containing 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 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.

Returns:

String part of the request's URI that is specific to a particular adaptor

See Also:

WORequest.applicationName(), WORequest.applicationNumber(), WORequest.queryString(), WORequest.requestHandlerKey(), WORequest.requestHandlerPath(), WORequest.uri(), WOApplication.cgiAdaptorURL()

applicationName

public String applicationName()

Returns a String containing the name of the application taken from the URI. This name does not include the ".woa" extension of an application directory. A WORequest must always have an application name specified: If the application is contacted using direct connect and an application name is not supplied, the value returned by WOApplication's name method will be used.

Returns:

String part of the request's URI that identifies the application the request is intended for

See Also:

WORequest.adaptorPrefix(), WORequest.applicationNumber(), WORequest.queryString(), WORequest.requestHandlerKey(), WORequest.requestHandlerPath(), WORequest.uri(), WOApplication.name()

applicationNumber

public int applicationNumber()

Returns a String containing the part of the request's URI indicating the specific application instance this 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, or for applications contacted using direct connect.

Returns:

String part of the request's URI identifying the application instance the request is intended for

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.queryString(), WORequest.requestHandlerKey(), WORequest.requestHandlerPath(), WORequest.uri()

requestHandlerPath

public String requestHandlerPath()

Returns a String containing 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. The request handler path is everything in the URI between the requestHandlerKey and the queryString.

Returns:

String part of the URI containing the request handler path

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.applicationNumber(), WORequest.queryString(), WORequest.requestHandlerKey(), WORequest.requestHandlerPathArray(), WORequest.uri()

queryString

public String queryString()

Returns, as a String, the query string of the URI. This contains everything appearing in the URI after a '?'. Returns null if there is no query string.

Returns:

String part of the URI containing the query string

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.applicationNumber(), WORequest.requestHandlerKey(), WORequest.requestHandlerPath(), WORequest.uri()

setDefaultFormValueEncoding

public void setDefaultFormValueEncoding(String 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 used if the WORequest cannot detect an encoding from the ASCII form values or if encoding detection is disabled. The current set of encodings supported is detailed in http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html If no default form value encoding is explicitly set, the WORequest uses WOMessage's defaultEncoding.

Parameters:

anEncoding - String the default String encoding

See Also:

WORequest.defaultFormValueEncoding(), WORequest.setFormValueEncodingDetectionEnabled(boolean flag), WOMessage.defaultEncoding()

defaultFormValueEncoding

public String 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. The current set of encodings supported is detailed in http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html If no default form-value encoding is set, WOMessage's defaultEncoding is used.

Returns:

the default string encoding the WORequest object uses for converting form values from ASCII to Unicode

See Also:

WORequest.setDefaultFormValueEncoding(String anEncoding), WOMessage.defaultEncoding()

setFormValueEncodingDetectionEnabled

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

Parameters:

aFlag - enables or disables automatic detection of the best encoding for the receiver to use

See Also:

WORequest.defaultFormValueEncoding(), WORequest.setDefaultFormValueEncoding(String anEncoding), WORequest.isFormValueEncodingDetectionEnabled()

isFormValueEncodingDetectionEnabled

public boolean isFormValueEncodingDetectionEnabled()

Return whether or not automatic detection of form value encoding is enabled. 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.

Returns:

true if detection of form-value encoding is allowed to take place when form values are obtained, false otherwise

See Also:

WORequest.defaultFormValueEncoding(), WORequest.setFormValueEncodingDetectionEnabled(boolean flag)

formValueEncoding

public String 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.

Returns:

the encoding last used to convert form values from ASCII to Unicode

See Also:

WORequest.defaultFormValueEncoding(), WORequest.setDefaultFormValueEncoding(String anEncoding), WORequest.isFormValueEncodingDetectionEnabled()

setFormValueEncoding

protected void setFormValueEncoding(String value)

Sets the form value encoding

Parameters:

value - form value encoding to be used

Since:

5.4

formValueKeys

public NSArray formValueKeys()

Returns an NSArray containing the names (or keys) used to access the values in a form. The returned array is not sorted in any particular order, and is not necessarily sorted in the same order on successive invocations of this method.

Returns:

NSArray of Strings containing the names used to access values of a form

See Also:

WORequest.formValueForKey(String aKey), WORequest.formValuesForKey(String aKey)

formValuesForKey

public NSArray formValuesForKey(String aKey)

Returns an NSArray containing the String form values associated with the given key. The returned 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.

Parameters:

aKey - name of the form value

Returns:

NSArray of all values (as Strings) of the form identified by the name aKey

See Also:

WORequest.formValueKeys(), WORequest.formValueForKey(String aKey)

formValueForKey

public Object formValueForKey(String aKey)

Return an Object representing the form value for 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.

Parameters:

aKey - name of the form value

Returns:

a form value identified by the name aKey

See Also:

WORequest.formValueKeys(), WORequest.formValuesForKey(String aKey), WORequest.stringFormValueForKey( String aKey )

stringFormValueForKey

public String stringFormValueForKey(String aKey)

Method to return a String form value from the request for a specific name (key). This method looks for a particular key and only returns a string value if the form value has a length greater than zero. Otherwise it returns null.

Parameters:

aKey - the form value to check for

Returns:

the form value as a String, or null

See Also:

WORequest.formValueForKey(String aKey), WORequest.formValuesForKey(String aKey), WORequest.dateFormValueForKey( String aKey , NSTimestampFormatter dateFormatter ), WORequest.numericFormValueForKey( String aKey, NSNumberFormatter numericFormatter )

numericFormValueForKey

public Number numericFormValueForKey(String aKey,
                                     NSNumberFormatter numericFormatter)

Method to return a Number for a form value from the request for a specific name (key). This convenince method looks for a particular key and coerces the value into the proper numeric format using the NSNumberFormatter provided. It will return null if it can't cast the form value into a Number or if the key can't be found.

Parameters:

aKey - the form value to check for

numericFormatter - the formatter used to coerce the form value to a numeric value.

Returns:

the Number representation for the value or null.

See Also:

WORequest.formValueForKey(String aKey), WORequest.formValuesForKey(String aKey), WORequest.dateFormValueForKey( String aKey , NSTimestampFormatter dateFormatter ), WORequest.stringFormValueForKey( String aKey )

dateFormValueForKey

@Deprecated
public NSTimestamp dateFormValueForKey(String aKey,
                                                  NSTimestampFormatter dateFormatter)

Deprecated. since5.4

Method to return an NSTimestamp for a form value from the request for a specific name (key). This convenience method looks for a particular key and coerces the value into the proper time format using the NSTimestampFormatter provided. It will return null if it can't cast the form value into a valid NSTimestamp or if the key can't be found.

Parameters:

aKey - the form value to check for

dateFormatter - the formatter used to coerce the form value to a date value.

Returns:

the NSTimestamp representation for the value or null.

See Also:

WORequest.formValueForKey(String aKey), WORequest.formValuesForKey(String aKey), WORequest.stringFormValueForKey( String aKey ), WORequest.numericFormValueForKey( String aKey, NSNumberFormatter numericFormatter )

dateFormValueForKey

public NSTimestamp dateFormValueForKey(String aKey,
                                       SimpleDateFormat dateFormatter)

Method to return an NSTimestamp for a form value from the request for a specific name (key). This convenience method looks for a particular key and coerces the value into the proper time format using the NSTimestampFormatter provided. It will return null if it can't cast the form value into a valid NSTimestamp or if the key can't be found.

Parameters:

aKey - the form value to check for

dateFormatter - the formatter used to coerce the form value to a date value.

Returns:

the NSTimestamp representation for the value or null.

See Also:

WORequest.formValueForKey(String aKey), WORequest.formValuesForKey(String aKey), WORequest.stringFormValueForKey( String aKey ), WORequest.numericFormValueForKey( String aKey, NSNumberFormatter numericFormatter )

cookieValuesForKey

public NSArray cookieValuesForKey(String aKey)

Returns all values for the given cookie name specified by 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

Parameters:

aKey - cookie name whose values are being requested

Returns:

NSArray of values for the cookie name specified by aKey

See Also:

WORequest.cookieValues(), WORequest.cookieValueForKey(String aKey), WOCookie

cookieValueForKey

public String cookieValueForKey(String aKey)

Returns the first value in the request for the given cookie name as specified by 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

Parameters:

aKey - cookie name whose values are being queried

Returns:

String value for the cookie name specified by aKey

See Also:

WORequest.cookieValues(), WORequest.cookieValuesForKey(String aKey), WOCookie

cookieValues

public NSDictionary cookieValues()

Returns an NSDictionary containing the values for all cookies in the request.

For more information about cookies, please see the Netscape cookie specification at: http://www.netscape.com/newsref/std/cookie_spec.html

Returns:

NSDictionary of cookie values and cookie keys

See Also:

WORequest.cookieValueForKey(String aKey), WORequest.cookieValuesForKey(String aKey), WOCookie

cookies

public NSArray cookies()

Returns an NSArray containing all cookies packaged as WOCookie objects.

Overrides:

cookies in class WOMessage

Returns:

NSArray containing all cookies packaged as WOCookie objects

See Also:

WOMessage.addCookie(WOCookie aCookie), WOMessage.removeCookie(WOCookie aCookie), WOCookie

isUsingWebServer

public boolean isUsingWebServer()

Returns true if the request is using a webserver, false otherwise.

Returns:

a boolean value indicating whether the request uses the web server

isAjaxSubmit

public boolean isAjaxSubmit()

Returns true if the request is using an AJAX request, false otherwise.

Returns:

a boolean value indicating whether the request was an AJAX request

Since:

5.4

ajaxFormSubmitKey

public static String ajaxFormSubmitKey()

Return the key used in the form values to identify a AJAX form sumit. This is necessary asin some case the form is hidden.

Returns:

a String used for identifying the key.

Since:

5.4

setAjaxFormSubmitKey

public static void setAjaxFormSubmitKey(String value)

Set the key in the form values used to identify a AJAX form sumit. This is necessary asin some case the form is hidden.

Parameters:

value - a String used for identifying the key.

Since:

5.4

isRequestFromFormSubmission

protected boolean isRequestFromFormSubmission()

Checks is the request is the result of a Form submission.

Returns:

true if a form was submitted

getFormValuesFromURLEncoding

protected NSDictionary getFormValuesFromURLEncoding()

isWhitespaceOrNull

protected boolean isWhitespaceOrNull(char value)

Detect if a char is a whitespace or null character

Parameters:

character - value

Returns:

true if whitespace or null character

removeCRLF

protected String removeCRLF(String value)

Process given string with CRLF chars removed

Parameters:

String - to process

Returns:

String with CRLF chars removed

detectFormValuesEncoding

protected String detectFormValuesEncoding(String content)

Return detected encoding for form values

Parameters:

content -

Returns:

String for detected encoding for form values

formValues

public 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. This array is not sorted in any particular order, and is not necessarily sorted in the same order on successive invocations of this method.

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.

Returns:

an NSDictionary containing all of the form data names and values

Throws:

IllegalStateException - when the content of a multipart request has been accessed through some other means.

See Also:

WORequest.formValueForKey(String aKey), WORequest.formValuesForKey(String aKey)

applicationURLPrefix

public String applicationURLPrefix()

Return the prefix of the URL used to access the application instance up to and including the application number. This will contain the adaptorPrefix, the applicationName, and the applicationNumber.

Returns:

The URL used to access the application instance up to and including the application number

See Also:

WORequest.adaptorPrefix(), WORequest.applicationName(), WORequest.applicationNumber()

isFromClientComponent

@Deprecated
public boolean isFromClientComponent()

Deprecated. isFromClientComponent() is deprecated as the Client Side Components Feature are not supported anymore

Deprecated.

Returns:

nothing, ever

sessionID

public String sessionID()

Returns the session ID if there is one. 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.

Returns:

the session ID, or null if no session ID is found

isSessionIDInRequest

public 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. WORequest's session() method is used to retrieve the value of the session ID from the request.

Returns:

true if the session ID can be obtained from the form values or a cookie.

contentType

protected String contentType()

Gets the value of the content type header.

Returns:

request content type

isMultipartFormData

public boolean isMultipartFormData()

Returns true if this WORequest represents multipart form data. Essentially, it checks the value of the content-type header for the type "multipart/form-data".

Returns:

true this WORequest is multipart/form-data.

useLegacyMultipart

protected boolean useLegacyMultipart()

getFormValuesFromMultipartFormData

protected NSDictionary getFormValuesFromMultipartFormData()

Returns the form values from the multipart iterator.

Returns:

dictionary contaioning the form values.

multipartIterator

public WOMultipartIterator multipartIterator()

Returns the WOMultipartIterator for this request. If this request does not represent multipart form-data, this method returns null; otherwise if contentInputStream has been called previously, this method returns null.

Returns:

the WOMultipartIterator used to traverse the form data