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.

By default, this builder is restricted to building HTTP GET and POST requests due to a bug in Safari's implementation of the XmlHttpRequest object.

Please see http://bugs.webkit.org/show_bug.cgi?id=3812 for more details.

Required Module

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

<!--                                                                        -->
<!-- Copyright 2007 Google Inc.                                             -->
<!-- Licensed under the Apache License, Version 2.0 (the "License"); you    -->
<!-- may not use this file except in compliance with the License. You may   -->
<!-- may obtain a copy of the License at                                    -->
<!--                                                                        -->
<!-- http://www.apache.org/licenses/LICENSE-2.0                             -->
<!--                                                                        -->
<!-- Unless required by applicable law or agreed to in writing, software    -->
<!-- distributed under the License is distributed on an "AS IS" BASIS,      -->
<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        -->
<!-- implied. License for the specific language governing permissions and   -->
<!-- limitations under the License.                                         -->

<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

static class

RequestBuilder.Method HTTP request method constants.

Field Summary

static RequestBuilder.Method	GET Specifies that the HTTP GET method should be used.
static RequestBuilder.Method	POST Specifies that the HTTP POST method should be used.

Constructor Summary

	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

Request	sendRequest(java.lang.String requestData, RequestCallback callback) Sends an HTTP request based on the current builder configuration.
void	setHeader(java.lang.String header, java.lang.String value) Sets a request header with the given name and value.
void	setPassword(java.lang.String password) Sets the password to use in the request URL.
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

GET

public static final RequestBuilder.Method GET

Specifies that the HTTP GET method should be used.

POST

public static final RequestBuilder.Method POST

Specifies that the HTTP POST 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) and URL.encodeComponent(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.encodeComponent(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

WARNING:This method is provided in order to allow the creation of HTTP request other than GET and POST to be made. If this is done, the developer must accept that the behavior on Safari is undefined.

Method Detail

sendRequest

public Request sendRequest(java.lang.String requestData,
                           RequestCallback callback)
                    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".

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:

RequestException

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

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