org.jdesktop.http
Class Request

java.lang.Object
  org.jdesktop.beans.AbstractBean
      org.jdesktop.http.Request

Direct Known Subclasses:

FormRequest

public class Request
extends org.jdesktop.beans.AbstractBean

Represents an http request. A Request is constructed and then passed to a Session for execution. The Session then returns a Response after execution finishes.

It is not possible to reuse Requests with content bodies because those bodies are specified as InputStreams. This is done for efficient handling of large files that may be used as content bodies.

To help simplify reuse of Requests, a copy constructor is provided which will copy everything _except_ the content body from the source Request

.

A Request is composed of a URL and HTTP method and optionally Headers, Parameters, and a body.

The URL for convenience is specified as a String, not a java.net.URL. The evaluation of the URL is done when the Request is executed, as opposed to when it is first set. The HTTP Method must be non-null.

HTTP headers are represented by the Header API. All HTTP headers that will be sent as part of this request are represented with a Header in this class. By default, all Request objects are created with an Accept-Encoding header set to "gzip", and have a Content-Type header set to 'text/plain; charset="UTF-8"'. If you send other data be sure to replace the value of the content type header.

According to the HTTP specification, HTTP headers are not case sensivite. Therefore, this class will allow headers to be lookedup in a case insensitive manner, unlike parameters which are case sensitive.

For convenience, this class supports automatic header generation for basic authentication when the username property is set. Whenever username or password is set it will reset the "Authentication" header. Be aware that manual modifications of this header will be lost whenever the username/password is changed.

Request also supports setting query parameters. A URL is composed of the protocol part, path part, and optionally the query parameter part.

     http://www.example.com/foo.html?a=b;c=d
     |-----|------------------------|-------|
      proto  path portion of URI      params
 

Request supports the setting of query parameters either in the URL or separately from it. In the next code snippet, the query parameters are set as part of the URL. As you can see from the code snippet, the query parameters, even though specified as part of the URL, are extracted from the URL and can be read and/or modified via the parameter API:

      Request req = new Request("http://www.example.com/foo.html?a=b;c=d");
      System.out.println(req.getUrl()); // prints out http://www.example.com/foo.html
      System.out.println(req.getParameter("a")); // prints out a=b
      System.out.println(req.getParameter("c")); // prints out c=d
 

You may also specify the query parameters completely separately from the URL:

      Request req = new Request("http://www.example.com/foo.html");
      req.setParameter("a", "b");
      req.setParameter("c", "d");
 

HTTP parameters must be URL encoded prior to transmission. This task is not handled by the Request, but by the Session. All parameter names and values are not URL encoded.

Some HTTP oriented APIs distinguish between "GET" parameters and "POST" parameters. This one does not. All parameters in this Request class are "GET" parameters, meaning that regardless of the HTTP method being used the parameters are set on the query string in the URL, not the body of the request. A subclass, FormRequest, handles "POST" parameters in a more complete way by also supporting different encoding schemes for POST requests.

Constructor Summary

Request()
Creates a new instance of Request.

Request(Method method, String url)
Creates a new instance of Request with the specified HTTP method and url.

Request(Request source)
Creates a new instance of Request, using source as the basis for all of the initial property values (except for requestBody, which is always null).

Request(String url)
Creaets a new instance of Request with the specified URL.

Method Summary

protected InputStream	getBody() Protected method which returns the request body.
boolean	getFollowRedirects() Gets whether to automatically follow redirct requests.
Header	getHeader(String name) Returns the Header with the given name, or null if there is no such header.
Header[]	getHeaders() Gets an array of all the Headers for this Request.
Method	getMethod() Gets the http Method used.
Parameter	getParameter(String name) Returns the Parameter with the given name, or null if there is no such Parameter.
Parameter[]	getParameters() Gets an array of all the Parameters for this Request.
String	getUrl() Returns the URL to request content from.
String	getUsername() Gets the username used for Basic Authentication.
void	removeHeader(Header header) Removes the given header from this Request.
void	removeHeader(String header) Removes the given named header from this Request.
void	setBody(byte[] body) Sets the request body to be the specified array of bytes.
void	setBody(Document body) Sets the request body to be the specified SimpleDocument.
void	setBody(InputStream body) Sets the request body to be the specified InputStream.
void	setBody(String body) Sets the request body to be the specified String.
void	setFollowRedirects(boolean b) Specifies whether to automatically follow redirects.
void	setHeader(Header header) Adds the given header to the set of headers.
void	setHeader(String name, String value) Creates a new Header with the given name and value, and no elements and adds it to the set of headers.
void	setHeader(String name, String value, Header.Element... elements) Creates a new Header with the given name, value, and elements and adds it to the set of headers.
void	setHeaders(Header... headers) Sets the headers to use with this Request.
void	setMethod(Method method) Sets the http Method to use for this Request.
void	setParameter(Parameter param) Adds the given parameter to the set of parameters.
void	setParameter(String name, String value) Creates a Parameter using the given name and value and then adds it to the set of parameters.
void	setParameters(Parameter... params) Sets the parameters to use with this Request.
void	setPassword(String password) Sets the passsword to use for Basic Authentication.
void	setUrl(String url) The URL to request content from.
void	setUsername(String username) Sets the username to use for Basic Authentication.
String	toString() Returns a string representation of the object.

Methods inherited from class org.jdesktop.beans.AbstractBean

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, clone, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, hasPropertyChangeListeners, hasVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener

Methods inherited from class java.lang.Object

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

Constructor Detail

Request

public Request()

Creates a new instance of Request. The following default values are used:

• headers: Accept-Encoding = gzip
• parameters: empty set
• followRedirects: true
• method: GET
• url: null
• requestBody: null

Request

public Request(String url)

Creaets a new instance of Request with the specified URL. Other default values are the same as for the default constructor.

Parameters:

url -

Request

public Request(Method method,
               String url)

Creates a new instance of Request with the specified HTTP method and url. All other default values are the same as for the default consturctor.

Parameters:

method - The HTTP method. If null, Method.GET is used.

url - The url. If non null, any query parameters are extracted and set as params for this request.

Request

public Request(Request source)

Creates a new instance of Request, using source as the basis for all of the initial property values (except for requestBody, which is always null). This is a copy constructor.

Parameters:

source - The source Request to copy

Method Detail

getHeader

public final Header getHeader(String name)

Returns the Header with the given name, or null if there is no such header. Header names are checked in a case insensitive manner.

Parameters:

name - the name to look for. If null then a null value will be returned

Returns:

the Header with the given name.

setHeader

public final void setHeader(String name,
                            String value)

Creates a new Header with the given name and value, and no elements and adds it to the set of headers.

Parameters:

name - The name. Must not be null.

value - The value. May be null.

setHeader

public final void setHeader(String name,
                            String value,
                            Header.Element... elements)

Creates a new Header with the given name, value, and elements and adds it to the set of headers.

Parameters:

name - The name. Must not be null.

value - The value. May be null.

elements - The elements. May be null.

setHeader

public void setHeader(Header header)

Adds the given header to the set of headers.

Parameters:

header - the Header to add. This must not be null.

removeHeader

public final void removeHeader(Header header)

Removes the given header from this Request.

Parameters:

header - the Header to remove. If null, nothing happens. If the header is not specified in this Request, nothing happens.

removeHeader

public final void removeHeader(String header)

Removes the given named header from this Request. The header is case-insensitive.

Parameters:

header - the name of the Header to remove. If null, nothing happens. If the header is not specified in this Request, nothing happens. Matches in a case-insensitive manner.

getHeaders

public final Header[] getHeaders()

Gets an array of all the Headers for this Request. This array will never be null. Ordering of items is not guaranteed.

Returns:

the array of Headers for this request

setHeaders

public final void setHeaders(Header... headers)

Sets the headers to use with this Request. This replaces whatever headers may have been previously defined. If null, this array is treated as an empty array.

Parameters:

headers - the Headers to set for this Request. May be null.

getParameter

public final Parameter getParameter(String name)

Returns the Parameter with the given name, or null if there is no such Parameter.

Parameters:

name - the name to look for. If null, null is returned.

Returns:

the Parameter with the given name.

setParameter

public final void setParameter(String name,
                               String value)

Creates a Parameter using the given name and value and then adds it to the set of parameters.

Parameters:

name - must not be null

value -

setParameter

public void setParameter(Parameter param)

Adds the given parameter to the set of parameters.

Parameters:

parem - the Parameter to add. This must not be null.

getParameters

public final Parameter[] getParameters()

Gets an array of all the Parameters for this Request. This array will never be null. Ordering of items is not guaranteed.

Returns:

the array of Parameters for this request

setParameters

public final void setParameters(Parameter... params)

Sets the parameters to use with this Request. This replaces whatever parameters may have been previously defined. If null, this array is treated as an empty array.

Parameters:

params - the Parameters to set for this Request. May be null.

setFollowRedirects

public void setFollowRedirects(boolean b)

Specifies whether to automatically follow redirects. An HTTP response may indicate that the system should be redirected to a new page. In that case, if followRedirects is true, this will happen automatically and the Response will be the new page (as long as the new page does not also cause a redirect). It is possible to encounter infinite redirects. boolean b whether to automatically follow redirects

getFollowRedirects

public final boolean getFollowRedirects()

Gets whether to automatically follow redirct requests. @see #setFollowRedirects(boolean).

Returns:

whether to automatically follow redirects.

setMethod

public void setMethod(Method method)

Sets the http Method to use for this Request. If null, a GET method will be used.

Parameters:

method - the Method to use. If null, Method.GET is used.

getMethod

public final Method getMethod()

Gets the http Method used.

Returns:

the Method for this Request.

setUrl

public void setUrl(String url)
            throws IllegalArgumentException

The URL to request content from. This must be an absolute URL. An IllegalArgumentException will be thrown if this url is malformed. This value may be null, but must be specified prior to executing this Request, otherwise an IllegalStateException will occur at execution time.

This URL may contain parameters (ie: in the query string). These parameters will be left in place. Any parameters added via #setParameters(Parameter[]) will be appened to this query string if this is not a POST request, otherwise, they will be included in the body of the post.

Parameters:

url - The url to request content from. May be null

Throws:

IllegalArgumentException - if the url is malformed.

getUrl

public final String getUrl()

Returns the URL to request content from.

Returns:

the url

setUsername

public void setUsername(String username)

Sets the username to use for Basic Authentication. If a username is specified, then the Session will attempt to use Basic Authentication with the web server. Setting username to null essentially turns off Basic Authentication. Setting this property causes a header to be added.

Parameters:

username - the user name to use

getUsername

public final String getUsername()

Gets the username used for Basic Authentication.

Returns:

may be null.

setPassword

public void setPassword(String password)

Sets the passsword to use for Basic Authentication. This property is only used if a username is also specified. For security reasons, the password cannot be retrieved after being set, and no property change event is fired for this property.

Parameters:

password -

setBody

public void setBody(String body)

Sets the request body to be the specified String.

Parameters:

body - the String to use for the body. May be null.

setBody

public void setBody(byte[] body)

Sets the request body to be the specified array of bytes.

Parameters:

body - the byte array to use for the body. May be null.

setBody

public void setBody(Document body)

Sets the request body to be the specified SimpleDocument.

Parameters:

body - the DOM document to use for the body. May be null.

setBody

public void setBody(InputStream body)

Sets the request body to be the specified InputStream.

Parameters:

body - the InputStream to use for the body. May be null.

getBody

protected InputStream getBody()
                       throws Exception

Protected method which returns the request body. This is only called by the Session. This method should never be called by client code, and should only be overridden in subclasses where the body is constructed in a manner unique to the request (for example: FormRequest).

Throws:

Exception

toString

public String toString()

Description copied from class: java.lang.Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.