com.google.gwt.http.client

## Class RequestBuilder

- java.lang.Object
- - com.google.gwt.http.client.RequestBuilder

-     public class RequestBuilder
      extends java.lang.Object

  Builder for constructing `Request` objects.

  ### Required Module

  Modules that use this class should inherit `com.google.gwt.http.HTTP`.

  >     <module>
  >       <!-- other inherited modules, such as com.google.gwt.user.User -->
  >       <inherits name="com.google.gwt.http.HTTP"/>
  >       <!-- additional module settings -->
  >     </module>

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RequestBuilder.Method` HTTP request method constants.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static RequestBuilder.Method` | `DELETE` Specifies that the HTTP DELETE method should be used.
    `static RequestBuilder.Method` | `GET` Specifies that the HTTP GET method should be used.
    `static RequestBuilder.Method` | `HEAD` Specifies that the HTTP HEAD method should be used.
    `static RequestBuilder.Method` | `POST` Specifies that the HTTP POST method should be used.
    `static RequestBuilder.Method` | `PUT` Specifies that the HTTP PUT method should be used.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `RequestBuilder(RequestBuilder.Method httpMethod, java.lang.String url)` Creates a builder using the parameters for configuration.
    `protected` | `RequestBuilder(java.lang.String httpMethod, java.lang.String url)` Creates a builder using the parameters values for configuration.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `RequestCallback` | `getCallback()` Returns the callback previously set by `setCallback(RequestCallback)`, or `null` if no callback was set.
    `java.lang.String` | `getHeader(java.lang.String header)` Returns the value of a header previous set by `setHeader(String, String)`, or `null` if no such header was set.
    `java.lang.String` | `getHTTPMethod()` Returns the HTTP method specified in the constructor.
    `java.lang.String` | `getPassword()` Returns the password previously set by `setPassword(String)`, or `null` if no password was set.
    `java.lang.String` | `getRequestData()` Returns the requestData previously set by `setRequestData(String)`, or `null` if no requestData was set.
    `int` | `getTimeoutMillis()` Returns the timeoutMillis previously set by `setTimeoutMillis(int)`, or `0` if no timeoutMillis was set.
    `java.lang.String` | `getUrl()` Returns the HTTP URL specified in the constructor.
    `java.lang.String` | `getUser()` Returns the user previously set by `setUser(String)`, or `null` if no user was set.
    `Request` | `send()` Sends an HTTP request based on the current builder configuration.
    `Request` | `sendRequest(java.lang.String requestData, RequestCallback callback)` Sends an HTTP request based on the current builder configuration with the specified data and callback.
    `void` | `setCallback(RequestCallback callback)` Sets the response handler for this request.
    `void` | `setHeader(java.lang.String header, java.lang.String value)` Sets a request header with the given name and value.
    `void` | `setIncludeCredentials(boolean includeCredentials)` Sets whether the cross origin request will include credentials.
    `void` | `setPassword(java.lang.String password)` Sets the password to use in the request URL.
    `void` | `setRequestData(java.lang.String requestData)` Sets the data to send as part of this request.
    `void` | `setTimeoutMillis(int timeoutMillis)` Sets the number of milliseconds to wait for a request to complete.
    `void` | `setUser(java.lang.String user)` Sets the user name that will be used in the request URL.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DELETE

          public static final RequestBuilder.Method DELETE

      Specifies that the HTTP DELETE method should be used.

    - #### GET

          public static final RequestBuilder.Method GET

      Specifies that the HTTP GET method should be used.

    - #### HEAD

          public static final RequestBuilder.Method HEAD

      Specifies that the HTTP HEAD method should be used.

    - #### POST

          public static final RequestBuilder.Method POST

      Specifies that the HTTP POST method should be used.

    - #### PUT

          public static final RequestBuilder.Method PUT

      Specifies that the HTTP PUT method should be used.

  - ### Constructor Detail

    - #### RequestBuilder

          public RequestBuilder(RequestBuilder.Method httpMethod,
                        java.lang.String url)

      Creates a builder using the parameters for configuration.
      Parameters:
        `httpMethod` - HTTP method to use for the request
        `url` - URL that has already has already been encoded. Please see `URL.encode(String)`, `URL.encodePathSegment(String)` and `URL.encodeQueryString(String)` for how to do this.
      Throws:
        `java.lang.IllegalArgumentException` - if the httpMethod or URL are empty
        `java.lang.NullPointerException` - if the httpMethod or the URL are null

    - #### RequestBuilder

          protected RequestBuilder(java.lang.String httpMethod,
                        java.lang.String url)

      Creates a builder using the parameters values for configuration.
      Parameters:
        `httpMethod` - HTTP method to use for the request
        `url` - URL that has already has already been URL encoded. Please see `URL.encode(String)` and `URL.encodePathSegment(String)` and `URL.encodeQueryString(String)` for how to do this.
      Throws:
        `java.lang.IllegalArgumentException` - if the httpMethod or URL are empty
        `java.lang.NullPointerException` - if the httpMethod or the URL are null

  - ### Method Detail

    - #### getCallback

          public RequestCallback getCallback()

      Returns the callback previously set by `setCallback(RequestCallback)`, or `null` if no callback was set.

    - #### getHeader

          public java.lang.String getHeader(java.lang.String header)

      Returns the value of a header previous set by `setHeader(String, String)`, or `null` if no such header was set.
      Parameters:
        `header` - the name of the header

    - #### getHTTPMethod

          public java.lang.String getHTTPMethod()

      Returns the HTTP method specified in the constructor.

    - #### getPassword

          public java.lang.String getPassword()

      Returns the password previously set by `setPassword(String)`, or `null` if no password was set.

    - #### getRequestData

          public java.lang.String getRequestData()

      Returns the requestData previously set by `setRequestData(String)`, or `null` if no requestData was set.

    - #### getTimeoutMillis

          public int getTimeoutMillis()

      Returns the timeoutMillis previously set by `setTimeoutMillis(int)`, or `0` if no timeoutMillis was set.

    - #### getUrl

          public java.lang.String getUrl()

      Returns the HTTP URL specified in the constructor.

    - #### getUser

          public java.lang.String getUser()

      Returns the user previously set by `setUser(String)`, or `null` if no user was set.

    - #### send

          public Request send()
                       throws RequestException

      Sends an HTTP request based on the current builder configuration. If no request headers have been set, the header "Content-Type" will be used with a value of "text/plain; charset=utf-8". You must call `setRequestData(String)` and `setCallback(RequestCallback)` before calling this method.
      Returns:
        a `Request` object that can be used to track the request
      Throws:
        `RequestException` - if the call fails to initiate
        `java.lang.NullPointerException` - if a request callback has not been set

    - #### sendRequest

          public Request sendRequest(java.lang.String requestData,
                            RequestCallback callback)
                              throws RequestException

      Sends an HTTP request based on the current builder configuration with the specified data and callback. If no request headers have been set, the header "Content-Type" will be used with a value of "text/plain; charset=utf-8". This method does not cache `requestData` or `callback`.
      Parameters:
        `requestData` - the data to send as part of the request
        `callback` - the response handler to be notified when the request fails or completes
      Returns:
        a `Request` object that can be used to track the request
      Throws:
        `java.lang.NullPointerException` - if `callback` `null`
        `RequestException`

    - #### setCallback

          public void setCallback(RequestCallback callback)

      Sets the response handler for this request. This method must be called before calling `send()`.
      Parameters:
        `callback` - the response handler to be notified when the request fails or completes
      Throws:
        `java.lang.NullPointerException` - if `callback` is `null`

    - #### setHeader

          public void setHeader(java.lang.String header,
                       java.lang.String value)

      Sets a request header with the given name and value. If a header with the specified name has already been set then the new value overwrites the current value.
      Parameters:
        `header` - the name of the header
        `value` - the value of the header
      Throws:
        `java.lang.NullPointerException` - if header or value are null
        `java.lang.IllegalArgumentException` - if header or value are the empty string

    - #### setPassword

          public void setPassword(java.lang.String password)

      Sets the password to use in the request URL. This is ignored if there is no user specified.
      Parameters:
        `password` - password to use in the request URL
      Throws:
        `java.lang.IllegalArgumentException` - if the password is empty
        `java.lang.NullPointerException` - if the password is null

    - #### setRequestData

          public void setRequestData(java.lang.String requestData)

      Sets the data to send as part of this request. This method must be called before calling `send()`.
      Parameters:
        `requestData` - the data to send as part of the request

    - #### setTimeoutMillis

          public void setTimeoutMillis(int timeoutMillis)

      Sets the number of milliseconds to wait for a request to complete. Should the request timeout, the `RequestCallback.onError(Request, Throwable)` method will be called on the callback instance given to the `sendRequest(String, RequestCallback)` method. The callback method will receive an instance of the `RequestTimeoutException` class as its `Throwable` argument.
      Parameters:
        `timeoutMillis` - number of milliseconds to wait before canceling the request, a value of zero disables timeouts
      Throws:
        `java.lang.IllegalArgumentException` - if the timeout value is negative

    - #### setUser

          public void setUser(java.lang.String user)

      Sets the user name that will be used in the request URL.
      Parameters:
        `user` - user name to use
      Throws:
        `java.lang.IllegalArgumentException` - if the user is empty
        `java.lang.NullPointerException` - if the user is null

    - #### setIncludeCredentials

          public void setIncludeCredentials(boolean includeCredentials)

      Sets whether the cross origin request will include credentials.
      Parameters:
        `withCredentials` - whether to include credentials in XHR