WebObjects 5.4.2

com.webobjects.appserver
Class WORequest

java.lang.Object
  extended by com.webobjects.appserver.WOMessage
      extended by 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:

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

Last updated June 2008

Copyright © 2000-2008 Apple Inc.