Overview  Package   Class  Deprecated  Index  Help 
Groovy Documentation
FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.jdesktop.http
[Java] Class Request

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

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.

Authors:
rbair

Field Summary
private boolean followRedirects

private Map headers

Header keys are stored in a case insensitive manner.
private Method method

private Map params

private char[] password

private InputStream requestBody

private String stringBody

Used in the toString() method call only if the body was set as a String.

private String url

private String username

 
Constructor Summary
Request()

Request(String url)

Creaets a new instance of Request with the specified URL.

Request(Method method, String url)

Creates a new instance of Request with the specified HTTP method and url.

Request(Request source)

 
Method Summary
private static String base64Decode(String s)

private static String base64Encode(String s)

protected InputStream getBody()

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 getPassword()

Sets the request body to be the specified String.
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.

private void resetAuthenticationHeader()

void setBody(String body)

void setBody(byte[] body)

void setBody(org.w3c.dom.Document body)

Sets the request body to be the specified InputStream.
void setBody(InputStream body)

void setFollowRedirects(boolean b)

Specifies whether to automatically follow redirects.

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, Element... elements)

Creates a new Header with the given name, value, and elements and adds it to the set of headers.
void setHeader(Header header)

Adds the given header 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(String name, String value)

Creates a Parameter using the given name and value and then adds it to the set of parameters.
void setParameter(Parameter param)

Adds the given parameter to the set of parameters.
void setParameters(Parameter... params)

Sets the parameters to use with this Request.

void setPassword(String password)

Gets the password.

void setUrl(String url)

private void setUrlImpl(String url)

void setUsername(String username)

String toString()

 
Methods inherited from class org.jdesktop.beans.AbstractBean
org.jdesktop.beans.AbstractBean#clone(), org.jdesktop.beans.AbstractBean#addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), org.jdesktop.beans.AbstractBean#addPropertyChangeListener(java.beans.PropertyChangeListener), org.jdesktop.beans.AbstractBean#removePropertyChangeListener(java.beans.PropertyChangeListener), org.jdesktop.beans.AbstractBean#removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), org.jdesktop.beans.AbstractBean#getPropertyChangeListeners(java.lang.String), org.jdesktop.beans.AbstractBean#getPropertyChangeListeners(), org.jdesktop.beans.AbstractBean#addVetoableChangeListener(java.lang.String, java.beans.VetoableChangeListener), org.jdesktop.beans.AbstractBean#addVetoableChangeListener(java.beans.VetoableChangeListener), org.jdesktop.beans.AbstractBean#removeVetoableChangeListener(java.lang.String, java.beans.VetoableChangeListener), org.jdesktop.beans.AbstractBean#removeVetoableChangeListener(java.beans.VetoableChangeListener), org.jdesktop.beans.AbstractBean#getVetoableChangeListeners(java.lang.String), org.jdesktop.beans.AbstractBean#getVetoableChangeListeners(), org.jdesktop.beans.AbstractBean#wait(), org.jdesktop.beans.AbstractBean#wait(long), org.jdesktop.beans.AbstractBean#wait(long, int), org.jdesktop.beans.AbstractBean#equals(java.lang.Object), org.jdesktop.beans.AbstractBean#toString(), org.jdesktop.beans.AbstractBean#hashCode(), org.jdesktop.beans.AbstractBean#getClass(), org.jdesktop.beans.AbstractBean#notify(), org.jdesktop.beans.AbstractBean#notifyAll()
 
Methods inherited from class Object
wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll
 

Field Detail

followRedirects

private boolean followRedirects

headers

private Map headers
Header keys are stored in a case insensitive manner.

method

private Method method

params

private Map params

password

private char[] password

requestBody

private InputStream requestBody

stringBody

private String stringBody
Used in the toString() method call only if the body was set as a String. If set as an InputStream or as bytes then this will be null.

url

private String url

username

private String username

 
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

base64Decode

private static String base64Decode(String s)

base64Encode

private static String base64Encode(String s)

getBody

protected InputStream getBody()

getFollowRedirects

public final boolean getFollowRedirects()
Gets whether to automatically follow redirct requests.
Returns:
whether to automatically follow redirects.
See Also:
setFollowRedirects(boolean)

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.

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

getMethod

public final Method getMethod()
Gets the http Method used.
Returns:
the Method for this Request.

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.

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

getPassword

final String getPassword()
Sets the request body to be the specified String.
Parameters:
body - the String to use for the body. May be null.

getUrl

public final String getUrl()
Returns the URL to request content from.
Returns:
the url

getUsername

public final String getUsername()
Gets the username used for Basic Authentication.
Returns:
may 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.

resetAuthenticationHeader

private void resetAuthenticationHeader()

setBody

public void setBody(String body)

setBody

public void setBody(byte[] body)

setBody

public void setBody(org.w3c.dom.Document body)
Sets the request body to be the specified InputStream.
Parameters:
body - the InputStream to use for the body. May be null.

setBody

public void setBody(InputStream body)

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

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

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.

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.

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.

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.

setPassword

public void setPassword(String password)
Gets the password. May be null.
Returns:
may be null.

setUrl

public void setUrl(String url)

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.

throws:
IllegalArgumentException if the url is malformed.
Parameters:
url - The url to request content from. May be null

setUrlImpl

private void setUrlImpl(String url)

setUsername

public void setUsername(String username)

toString

return
public String toString()

 

Groovy Documentation