Package org.jdesktop.http

Class Request

java.lang.Object
org.jdesktop.beans.AbstractBean
org.jdesktop.http.Request
All Implemented Interfaces:
Constants
public class Request extends AbstractBean implements Constants
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 Details

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

    • 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:
      param - 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 -

    • getPassword

      public final String getPassword()
      Gets the password. May be null.
      Returns:
      may be null.

    • 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 Document.
      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()
      Overrides:
      toString in class Object