com.zenkey.net.prowser
Class Request

java.lang.Object
  com.zenkey.net.prowser.Request

public class Request
extends Object

The Request class is a collection of properties that specify a web page request to be made by a Tab instance. When a Request is executed by a Tab, a Response object is generated.

The properties of a Request are listed in the following table. Note that only the URI property is required; the rest are optional:

URI	The web address of the request.
Request Parameters	Extra data that is usually submitted via an HTML form in a URI query string, or in POSTed data. (See A note about request parameters for more information.)
HTTP Method	The HTTP method for making the request. Tab accepts the GET and POST methods. (See RFC 2616 for more information.)
HTTP Version	Version of HTTP to use. (0.9, 1.0 or 1.1)
Timeout	Time to wait before giving up on a web page request in progress.
User Agent String	Identifies the web client to the web server. (Passed to the web server as an HTTP header field.)

Except for the URI, the properties of a Request object can be specified either during the object's construction or via setter methods. The URI can only be set during construction, and it cannot be changed afterward.

There are two options for setting Request properties during construction. The first option involves specifying only a URI. In this case, the other properties receive default values. (See Request(URI), Request(String), and Request(String, boolean).) The other option involves the specification of a request file that contains the Request's property values. (See Request(File).)

After construction, various properties of the Request can be manipulated with getter and setter methods.

When a Request is used by a Tab instance to execute a page request, a response is generated and returned in the form of a Response object. From this Response object, you can obtain the contents of the web page as text or binary data. You can also obtain the error condition of the request/repsonse transaction, as well as the HTTP status information of the respone. The Response object is returned by the Tab method that executed the page request, but it is also stored in the Request object and is available via the getResponse() method.

A note about request parameters:

Request parameters are extra information that can be sent with an HTTP request. They usually constitute the data submitted in an HTML form. When using the HTTP GET method, parameters are transmitted in a URI's query string. When using the HTTP POST method, parameters are included in the message body of the request.

Keep in mind that a request can have multiple parameters with the same name. For instance, if an HTML form has a <select> element that is configured to allow more than one option selection at a time, each selected option will be submitted as a parameter with the same name. So, for example, if the name attribute of a <select> element is colors, and the user selects red, orange, and yellow, the following three parameters would be submitted in the request:

colors=red
colors=orange
colors=yellow
 

Basic and Digest Authentication:

To request a page that requires Basic or Digest Authentication, simply include the username and password as part of the URI, like this:

    http://username:password@www.site-requiring-auth.com/
 

Thread Safety:

A Request object is not thread-safe. It maintains state information so that it may be used repeatedly. Multiple threads using the same Request might corrupt this state information.

Version:

$Revision: 1.2 $, $Date: 2006/02/21 19:41:49 $

See Also:

Tab, Response

Field Summary

static String	HTTP_METHOD_GET The HTTP GET method.
static String	HTTP_METHOD_POST The HTTP POST method.
static String	HTTP_VERSION_0_9 HTTP version 0.9.
static String	HTTP_VERSION_1_0 HTTP version 1.0.
static String	HTTP_VERSION_1_1 HTTP version 1.1.
static int	TIMEOUT_INFINITE A timeout value of zero (0), which should be interpreted as an "infinite" timeout.

Constructor Summary

protected	Request() Protected, do-nothing constrcutor.
	Request(File requestFile) Constructs a new Request object whose property values are specified in a request file.
	Request(String uri) Constructs a new Request object for the specified URL-encoded URI string; all other request properties receive default values.
	Request(String uri, boolean isEncoded) Constructs a new Request object for the specified URI string, which is assumed to be URL-encoded if the isEncoded argument is true; all other request properties receive default values.
	Request(URI uri) Constructs a new Request object for the specified URI; all other request properties receive default values.

Method Summary

void	addParameter(String name, String value) Adds a parameter to this Request.
void	addParameters(Map<String,String[]> parameterMap) Adds parameters from a java.util.Map to this Request.
void	addParameters(String name, String[] values) Adds parameters with the spcecified name and values to this Request.
boolean	changeParameter(String name, String oldValue, String newValue) Changes the value of an existing parameter in this Request.
static Request	createRequest(File requestFile) Factory method that returns a new Request object whose property values are specified in a request file.
static Request	createRequest(String uri) Factory method that returns a new Request object for the specified URL-encoded URI string; all other request properties receive default values.
static Request	createRequest(String uri, boolean isEncoded) Factory method that returns a new Request object for the specified URI string, which is assumed to be URL-encoded if the isEncoded argument is true; all other request properties receive default values.
String	getHttpMethod() Returns the HTTP method of this Request.
String	getHttpVersion() Returns the explicit HTTP version of this Request.
Map<String,String[]>	getParameterMap() Returns a java.util.Map of the parameters in this Request.
String[]	getParameterValues(String name) Returns an array of values for this Request's parameters that have the specified name.
Response	getResponse() Returns the most recent Response that resulted from this Request.
Integer	getTimeout() Returns the explicit timeout value (in milliseconds) for this Request.
URI	getUri() Returns the URI of this Request.
String	getUserAgent() Returns the explicit user-agent string of this Request.
boolean	removeParameter(String name, String value) Removes a specified parameter with a specified value from this Request.
Map<String,String[]>	removeParameters() Removes all parameters from this Request.
String[]	removeParameters(String name) Removes all parameters with the specified name from this Request.
void	setHttpMethod(String httpMethod) Sets the HTTP method for this Request.
void	setHttpVersion(String httpVersion) Sets an explicit HTTP version for this Request.
String[]	setParameter(String name, String value) Sets a parameter with the spcecified value for this Request.
Map<String,String[]>	setParameters(Map<String,String[]> parameterMap) Sets parameters from a java.util.Map for this Request.
String[]	setParameters(String name, String[] values) Sets parameters with the spcecified name and values for this Request.
void	setTimeout(Integer timeout) Sets an explicit timeout (in milliseconds) for this Request.
void	setUserAgent(String userAgent) Sets an explicit user-agent string for this Request.
String	toString() Returns a String representation of the Request.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

HTTP_METHOD_GET

public static final String HTTP_METHOD_GET

The HTTP GET method.

See Also:

Constant Field Values

HTTP_METHOD_POST

public static final String HTTP_METHOD_POST

The HTTP POST method.

See Also:

Constant Field Values

HTTP_VERSION_0_9

public static final String HTTP_VERSION_0_9

HTTP version 0.9.

See Also:

Constant Field Values

HTTP_VERSION_1_0

public static final String HTTP_VERSION_1_0

HTTP version 1.0.

See Also:

Constant Field Values

HTTP_VERSION_1_1

public static final String HTTP_VERSION_1_1

HTTP version 1.1.

See Also:

Constant Field Values

TIMEOUT_INFINITE

public static final int TIMEOUT_INFINITE

A timeout value of zero (0), which should be interpreted as an "infinite" timeout. This value is used for web page requests. Note that the use of this value may still result in a finite timeout, depending on how it is handled by the Tab object and the underlying protocol stack.

See Also:

setTimeout(Integer), Constant Field Values

Constructor Detail

Request

protected Request()

Protected, do-nothing constrcutor.

Request

public Request(File requestFile)
        throws Exception

Constructs a new Request object whose property values are specified in a request file. (Request properties are explained here. Default values are listed here.)

Some notes on request files:

• The only required property is the URI. All others are optional. (See below for valid property names.)
• It is the caller's responsibility to ensure that the URI's path and query (if any) are URL-encoded.
• It is the caller's responsibility to ensure that the parameters are URL-encoded.
• Timeout values are in milliseconds.
• Property names are case-insensitive (e.g., HttpVersion is the same as HTTPVERSION).
• Comments are indicated by lines that begin with a hash mark (#).
• Blank lines are permitted.

Here is an example of a request file that shows the names and format of all valid property entries:

# This is a request file for class com.zenkey.net.prowser.Request.

URI http://onesearch.sun.com/search/onesearch/index.jsp
 
Parameter qt=java
Parameter charset=UTF-8

HttpMethod GET
 
HttpVersion 1.1

Timeout 10000

UserAgent Mozilla/4.8 [en] (Windows NT 5.1; U)
 

If the request is using the HTTP GET method, then if the URI contains a query string, the parameters contained in that string will be added to the request's parameter collection. Also, the URI's query string will be updated to include any parameters that are added separately via Parameter properties in the request file.

Parameters:

requestFile - The request file that contains the request's property values.

Throws:

Exception - If errors occur related to the processing of the request file.

Request

public Request(String uri)
        throws URISyntaxException

Constructs a new Request object for the specified URL-encoded URI string; all other request properties receive default values. For a list of default property values, see Request(URI).

It is the caller's responsibility to ensure that The URI's path and query (if any) are URL-encoded.

Parameters:

uri - The request's URI.

Throws:

URISyntaxException - If string could not be parsed as a URI reference.

Request

public Request(String uri,
               boolean isEncoded)
        throws URISyntaxException

Constructs a new Request object for the specified URI string, which is assumed to be URL-encoded if the isEncoded argument is true; all other request properties receive default values. For a list of default property values, see Request(URI).

If isEncoded is false, then this constructor will URL-encode the path and query (if any).

Parameters:

uri - The request's URI.

isEncoded - true when the supplied URI is URL-encoded; false otherwise.

Throws:

URISyntaxException - If string could not be parsed as a URI reference.

Request

public Request(URI uri)

Constructs a new Request object for the specified URI; all other request properties receive default values.

The default property values are:

Request Parameters:	null	(No request parameters)
HTTP Method:	GET
HTTP Version:	null	(Tab will govern the value)
Timeout:	null	(Tab will govern the value)
User Agent String:	null	(Tab will govern the value)

If the URI contains a query string, then the parameters contained in that string will be added to the request's parameters.

Parameters:

uri - The request's URI.

Method Detail

addParameter

public void addParameter(String name,
                         String value)

Adds a parameter to this Request.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameter's name.

value - The parameter's value.

addParameters

public void addParameters(Map<String,String[]> parameterMap)

Adds parameters from a java.util.Map to this Request. The keys of the map are parameter names; the values of the map are arrays of parameter values associated with each parameter name.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

parameterMap - Map containing parameters to be added to the request. A null value is allowed.

addParameters

public void addParameters(String name,
                          String[] values)

Adds parameters with the spcecified name and values to this Request.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameters' name.

values - The parameter values.

changeParameter

public boolean changeParameter(String name,
                               String oldValue,
                               String newValue)

Changes the value of an existing parameter in this Request.

If the specified name-value pair of name=oldValue does not exist, no changes or additions are made. If more than one parameter exists with the same name and oldValue, all of them will be changed to newValue.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameter's name.

oldValue - The parameter value to be changed.

newValue - The parameter value to replace oldValue

Returns:

true if the parameter's oldValue existed and was changed to newValue; false otherwise.

createRequest

public static Request createRequest(File requestFile)

Factory method that returns a new Request object whose property values are specified in a request file.

See Request(File) for more information on the usage and format of request files.

Parameters:

requestFile - The request file that contains the request's property values.

Returns:

A new Request object for the specified request file, or null if the request can not be created.

createRequest

public static Request createRequest(String uri)

Factory method that returns a new Request object for the specified URL-encoded URI string; all other request properties receive default values. For a list of default property values, see Request(URI).

It is the caller's responsibility to ensure that The URI's path and query (if any) are URL-encoded.

Parameters:

uri - The request's URI.

Returns:

A new Request object for the specified URL-encoded URI string, or null if the request can not be created.

createRequest

public static Request createRequest(String uri,
                                    boolean isEncoded)

Factory method that returns a new Request object for the specified URI string, which is assumed to be URL-encoded if the isEncoded argument is true; all other request properties receive default values. For a list of default property values, see Request(URI).

If isEncoded is false, then this method will URL-encode the path and query (if any).

Parameters:

uri - The request's URI.

isEncoded - true when the supplied URI is URL-encoded; false otherwise.

Returns:

A new Request object for the specified URI string, or null if the request can not be created.

getHttpMethod

public String getHttpMethod()

Returns the HTTP method of this Request.

If this property is not set, the request uses a default value of GET.

Returns:

The request's HTTP method.

getHttpVersion

public String getHttpVersion()

Returns the explicit HTTP version of this Request.

If this property is not set, the value will be governed by the Tab object that executes this request.

Returns:

The request's explicit HTTP version, or null if one has not been set.

getParameterMap

public Map<String,String[]> getParameterMap()

Returns a java.util.Map of the parameters in this Request. The keys of the map are parameter names; the values of the map are arrays of parameter values associated with each parameter name.

Returns:

A java.util.Map of the request's parameters, or null if the request has no parameters.

getParameterValues

public String[] getParameterValues(String name)

Returns an array of values for this Request's parameters that have the specified name.

If there is only one parameter with the specified name, the array will have a length of 1.

Parameters:

name - The parameter's name.

Returns:

An array of values associated with the specified parameter name, or null if the parameter does not exist.

getResponse

public Response getResponse()

Returns the most recent Response that resulted from this Request.

Returns:

The most recent Response that resulted from this Request, or null if the Request has not been submitted yet.

getTimeout

public Integer getTimeout()

Returns the explicit timeout value (in milliseconds) for this Request.

Returns:

The request's explicit timeout value, in milliseconds, or null if the request does not specify a timeout value itself (i.e., the timeout [if any] will be governed by the Tab instance that executes the request).

See Also:

setTimeout(Integer)

getUri

public URI getUri()

Returns the URI of this Request.

Returns:

The request's URI.

getUserAgent

public String getUserAgent()

Returns the explicit user-agent string of this Request.

If this property is not set, the value will be governed by the Tab object that executes this request.

Returns:

The request's explicit user-agent string, or null if one has not been not set.

removeParameter

public boolean removeParameter(String name,
                               String value)

Removes a specified parameter with a specified value from this Request. Other parameters with the same name but different values will not be removed. If more than one occurrence of the name-value pair exists, the superfluous parameters will also be removed. To remove all parameters with a specified name (regardless of value), use removeParameters(String name).

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameter's name.

value - The parameter's value.

Returns:

true if the parameter was removed; false otherwise.

removeParameters

public Map<String,String[]> removeParameters()

Removes all parameters from this Request.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Returns:

A java.util.Map of the request's former parameters, or null if the request had no parameters. The structure of the map is the same as the one returned by getParameterMap().

removeParameters

public String[] removeParameters(String name)

Removes all parameters with the specified name from this Request. To remove a single parameter with a specified name and value, use removeParameter(String name, String value).

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameter's name.

Returns:

An array of the values removed for the specified parameter name, or null if the parameter does not exist.

setHttpMethod

public void setHttpMethod(String httpMethod)

Sets the HTTP method for this Request.

If the GET method is specified, then the URI's query string will be updated to include any parameters that have already been added to the request.

If this property is not set, the request uses a default value of GET.

Parameters:

httpMethod - The request's HTTP httpMethod.

setHttpVersion

public void setHttpVersion(String httpVersion)

Sets an explicit HTTP version for this Request.

If this property is not set, the value will be governed by the Tab object that executes this request.

Parameters:

httpVersion - The request's HTTP version.

setParameter

public String[] setParameter(String name,
                             String value)

Sets a parameter with the spcecified value for this Request.

If any parameters with the specified name already exist, they will all be replaced by a single parameter with the spcecfied value. If no parameters with the specified name exist, a new parameter with the specified value will be added to the request.

When parameters are replaced by this method, an array of the replaced values is returned.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameter's name.

value - The parameter's value.

Returns:

An array of replaced parameter values for the specified name, or null if no parameters were replaced.

setParameters

public Map<String,String[]> setParameters(Map<String,String[]> parameterMap)

Sets parameters from a java.util.Map for this Request. The keys of the map are parameter names; the values of the map are arrays of parameter values associated with each parameter name.

For each entry in the map argument, if any parameters with the specified name already exist, they will all be replaced by parameters with the spcecfied values. If no parameters with the specified name exist, new parameters with the specified values will be added to the request.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

parameterMap - Map containing parameters to be set for the request. A null value is allowed.

Returns:

A java.util.Map of any request parameters that were replaced, or null if no request parameters were replaced. The structure of the map is the same as the one returned by getParameterMap().

setParameters

public String[] setParameters(String name,
                              String[] values)

Sets parameters with the spcecified name and values for this Request.

If any parameters with the specified name already exist, they will all be replaced by parameters with the spcecfied values. If no parameters with the specified name exist, new parameters with the specified values will be added to the request.

If the request is using the HTTP GET method, then the URI's query string will be updated accordingly.

Parameters:

name - The parameters' name.

values - The parameter values.

Returns:

An array of replaced parameter values for the specified name, or null if no parameters were replaced.

setTimeout

public void setTimeout(Integer timeout)

Sets an explicit timeout (in milliseconds) for this Request.

Use a value of TIMEOUT_INFINITE to indicate that the calling thread should wait indefinitely for the request to complete.

Use a value of null to indicate that the request itself does not specify a timeout. In this case, the timeout (if any) will be governed by the Tab instance that executes the request.

If the request's timeout is never explicitly set, the default timeout value is null.

Parameters:

timeout - The number of milliseconds to wait before timing out a reqeust, or null to indicate that the request itself does not specify a timeout. A value of TIMEOUT_INFINITE means that the calling thread should wait indefinitely for the request to complete.

Throws:

IllegalArgumentException - If the timeout value is less than zero.

setUserAgent

public void setUserAgent(String userAgent)

Sets an explicit user-agent string for this Request.

If this property is not set, the value will be governed by the Tab object that executes this request.

Parameters:

userAgent - The request's user-agent string.

toString

public String toString()

Returns a String representation of the Request.

Overrides:

toString in class Object

Returns:

A String representation of the Request.