com.google.gwt.http.client

Class RequestBuilder

java.lang.Object

com.google.gwt.http.client.RequestBuilder

Direct Known Subclasses:

FailingRequestBuilder

public class RequestBuilder
extends Object

Builder for constructing Request objects.

Required Module

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

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, String url) Creates a builder using the parameters for configuration.
protected	RequestBuilder(String httpMethod, String url) Creates a builder using the parameters values for configuration.

Method Summary

Modifier and Type	Method and Description
RequestCallback	getCallback() Returns the callback previously set by setCallback(RequestCallback), or null if no callback was set.
String	getHeader(String header) Returns the value of a header previous set by setHeader(String, String), or null if no such header was set.
String	getHTTPMethod() Returns the HTTP method specified in the constructor.
String	getPassword() Returns the password previously set by setPassword(String), or null if no password was set.
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.
String	getUrl() Returns the HTTP URL specified in the constructor.
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(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(String header, 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(String password) Sets the password to use in the request URL.
void	setRequestData(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(String user) Sets the user name that will be used in the request URL.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, toString

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

IllegalArgumentException - if the httpMethod or URL are empty

NullPointerException - if the httpMethod or the URL are null

RequestBuilder

protected RequestBuilder(String httpMethod,
                         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:

IllegalArgumentException - if the httpMethod or URL are empty

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 String getHeader(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 String getHTTPMethod()

Returns the HTTP method specified in the constructor.

getPassword

public String getPassword()

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

getRequestData

public 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 String getUrl()

Returns the HTTP URL specified in the constructor.

getUser

public 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

NullPointerException - if a request callback has not been set

sendRequest

public Request sendRequest(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:

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:

NullPointerException - if callback is null

setHeader

public void setHeader(String header,
                      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:

NullPointerException - if header or value are null

IllegalArgumentException - if header or value are the empty string

setPassword

public void setPassword(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:

IllegalArgumentException - if the password is empty

NullPointerException - if the password is null

setRequestData

public void setRequestData(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:

IllegalArgumentException - if the timeout value is negative

setUser

public void setUser(String user)

Sets the user name that will be used in the request URL.

Parameters:

user - user name to use

Throws:

IllegalArgumentException - if the user is empty

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