Google Web Toolkit
Search Google Code:

# Package com.google.gwt.http.client

Provides the client-side classes and interfaces for making HTTP requests and processing the associated responses.

Most applications will be interested in the Request, RequestBuilder, RequestCallback and Response classes.

## Caveats

### Same-Origin Security Policy

Modern web browsers restrict client-side scripts from accessing items outside of their source origin. This means that a script loaded form `www.foo.com` cannot access content from `www.bar.com`. For more details plesae see, Same-Origin Security Policy.

### Pending Request Limit

Modern web browsers are limited to having only two HTTP requests outstanding at any one time. If your server experiences and error that prevents it from sending a response, it can tie up your outstanding requests. If you are concerned about this, you can always set timeouts for the request via RequestBuilder.setTimeoutMillis(int).

### Required Module

Modules that use the classes and interfaces in this package should inherit the `com.google.gwt.http.HTTP` module.

    <!--                                                                        -->
    <!-- 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>

## Quick Howto's

### How should I write a RequestCallback handler class?

The following code shows how a RequestCallback instance should be written.

    public class RequestCallbackExample implements RequestCallback {

      private static final int STATUS_CODE_OK = 200;

      public void onError(Request request, Throwable exception) {
        if (exception instanceof RequestTimeoutException) {
          // handle a request timeout
        } else {
          // handle other request errors
        }
      }

      public void onResponseReceived(Request request, Response response) {
        if (STATUS_CODE_OK == response.getStatusCode()) {
          // handle OK response from the server
        } else {
          // handle non-OK response from the server
        }
      }
    }

### How do I make a GET request?

The following example demonstrates how to perform an HTTP GET request.

    public class GetExample implements EntryPoint {
      public static final int STATUS_CODE_OK = 200;

      public static void doGet(String url) {
        RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, url);

        try {
          Request response = builder.sendRequest(null, new RequestCallback() {
            public void onError(Request request, Throwable exception) {
              // Code omitted for clarity
            }

            public void onResponseReceived(Request request, Response response) {
              // Code omitted for clarity
            }
          });
        } catch (RequestException e) {
          // Code omitted for clarity
        }
      }

      public void onModuleLoad() {
        doGet("/");
      }
    }

### How do I make a POST request?

The following example demonstrates how to perform an HTTP POST request.

    public class PostExample {
      public static void doPost(String url, String postData) {
        RequestBuilder builder = new RequestBuilder(RequestBuilder.POST, url);

        try {
          Request response = builder.sendRequest(postData, new RequestCallback() {

            public void onError(Request request, Throwable exception) {
              // code omitted for clarity
            }

            public void onResponseReceived(Request request, Response response) {
              // code omitted for clarity
            }
          });
        } catch (RequestException e) {
          Window.alert("Failed to send the request: " + e.getMessage());
        }
      }

      public void onModuleLoad() {
        doPost("/", "Hello World!");
      }
    }

### How do I use request timeouts?

The following example demonstrates how to use the timeout feature.

    public class TimeoutExample implements EntryPoint {
      public static void doGetWithTimeout(String url) {
        RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, url);

        try {
          /*
           * wait 2000 milliseconds for the request to complete
           */
          builder.setTimeoutMillis(2000);

          Request response = builder.sendRequest(null, new RequestCallback() {
            public void onError(Request request, Throwable exception) {
              if (exception instanceof RequestTimeoutException) {
                // handle a request timeout
              } else {
                // handle other request errors
              }
            }

            public void onResponseReceived(Request request, Response response) {
              // code omitted for clarity
            }
          });
        } catch (RequestException e) {
          Window.alert("Failed to send the request: " + e.getMessage());
        }
      }

      public void onModuleLoad() {
        doGetWithTimeout("/");
      }
    }

### How do I construct a string for use in a query or POST body?

The following example demonstrates how to build a x-www-form-urlencoded string that can be used as a query string or as the body of a POST request.

    public class QueryAndFormDataExample {

      public static interface Entry {
        String getName();
        String getValue();
      }

      public static String buildQueryString(Entry[] queryEntries) {
        StringBuffer sb = new StringBuffer();

        for (int i = 0, n = queryEntries.length; i < n; ++i) {
          Entry queryEntry = queryEntries[i];

          if (i > 0) {
            sb.append("&");
          }

          // encode the characters in the name
          String encodedName = URL.encodeComponent(queryEntry.getName());
          sb.append(encodedName);

          sb.append("=");

          // encode the characters in the value
          String encodedValue = URL.encodeComponent(queryEntry.getValue());
          sb.append(encodedValue);
        }

        return sb.toString();
      }
    }

### How can I make a RequestBuilder send a request other than GET or POST?

The following example demonstrates how to allow an HTTP request other than a GET or a POST to be made. Beware: if you plan on supporting Safari, you cannot use this scheme.

    public class RequestBuilderForAnyHTTPMethodTypeExample extends RequestBuilder {

      /**
       * Constructor that allows a developer to override the HTTP method
       * restrictions imposed by the RequestBuilder class.  Note if you override the
       * RequestBuilder's HTTP method restrictions in this manner, your application
       * may not work correctly on Safari browsers.
       *
       * @param httpMethod any non-null, non-empty string is considered valid
       * @param url any non-null, non-empty string is considered valid
       *
       * @throws IllegalArgumentException if httpMethod or url are empty
       * @throws NullPointerException if httpMethod or url are null
       */
      public RequestBuilderForAnyHTTPMethodTypeExample(String httpMethod, String url) {
        super(httpMethod, url);
      }
    }

## Classes

Header | Class for describing an HTTP header.
Request | An HTTP request that is waiting for a response.
RequestBuilder | Builder for constructing Request objects.
RequestException | RequestException is the superclass for the HTTP request related exceptions.
RequestPermissionException | Exception thrown when the RequestBuilder attempts to make a request to a URL which violates the Same-Origin Security Policy.
RequestTimeoutException | Thrown to indicate that an HTTP request has timed out.
Response | Wrapper which provides access to the components of an HTTP response.
URL | Utility class for the encoding and decoding URLs in their entirety or by their individual components.

## Interfaces

RequestCallback | The primary interface a caller must implement to receive a response to a Request.