com.google.gwt.http.client.RequestBuilder.java Source code

Java tutorial

Introduction

Here is the source code for com.google.gwt.http.client.RequestBuilder.java

Source

/*
 * Copyright 2008 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 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. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.gwt.http.client;

import java.util.HashMap;
import java.util.Map;

import com.google.gwt.core.client.JavaScriptException;
import com.google.gwt.xhr.client.ReadyStateChangeHandler;
import com.google.gwt.xhr.client.XMLHttpRequest;

/**
 * Builder for constructing {@link com.google.gwt.http.client.Request} objects.
 * 
 * <h3>Required Module</h3> Modules that use this class should inherit
 * <code>com.google.gwt.http.HTTP</code>.
 * 
 * {@gwt.include
 * com/google/gwt/examples/http/InheritsExample.gwt.xml}
 * 
 */
public class RequestBuilder {
    /**
     * HTTP request method constants.
     */
    public static final class Method {
        private final String name;

        private Method(String name) {
            this.name = name;
        }

        @Override
        public String toString() {
            return name;
        }
    }

    /**
     * Specifies that the HTTP DELETE method should be used.
     */
    public static final Method DELETE = new Method("DELETE");

    /**
     * Specifies that the HTTP GET method should be used.
     */
    public static final Method GET = new Method("GET");

    /**
     * Specifies that the HTTP HEAD method should be used.
     */
    public static final Method HEAD = new Method("HEAD");

    /**
     * Specifies that the HTTP POST method should be used.
     */
    public static final Method POST = new Method("POST");

    /**
     * Specifies that the HTTP PUT method should be used.
     */
    public static final Method PUT = new Method("PUT");

    /**
     * The callback to call when the request completes.
     */
    private RequestCallback callback;

    /**
     * Map of header name to value that will be added to the JavaScript
     * XmlHttpRequest object before sending a request.
     */
    private Map<String, String> headers;

    /**
     * HTTP method to use when opening a JavaScript XmlHttpRequest object.
     */
    private final String httpMethod;

    /**
     * Password to use when opening a JavaScript XmlHttpRequest object.
     */
    private String password;

    /**
     * Request data to use when sending a JavaScript XmlHttpRequest object.
     */
    private String requestData;

    /**
     * Timeout in milliseconds before the request timeouts and fails.
     */
    private int timeoutMillis;

    /**
     * URL to use when opening a JavaScript XmlHttpRequest object.
     */
    private final String url;

    /**
     * User to use when opening a JavaScript XmlHttpRequest object.
     */
    private String user;

    /**
     * Creates a builder using the parameters for configuration.
     * 
     * @param httpMethod HTTP method to use for the request
     * @param url URL that has already has already been encoded. Please see
     *          {@link com.google.gwt.http.client.URL#encode(String)} and
     *          {@link com.google.gwt.http.client.URL#encodeComponent(String)} for
     *          how to do this.
     * @throws IllegalArgumentException if the httpMethod or URL are empty
     * @throws NullPointerException if the httpMethod or the URL are null
     */
    public RequestBuilder(Method httpMethod, String url) {
        this((httpMethod == null) ? null : httpMethod.toString(), url);
    }

    /**
     * Creates a builder using the parameters values for configuration.
     * 
     * @param httpMethod HTTP method to use for the request
     * @param url URL that has already has already been URL encoded. Please see
     *          {@link com.google.gwt.http.client.URL#encode(String)} and
     *          {@link com.google.gwt.http.client.URL#encodeComponent(String)} for
     *          how to do this.
     * @throws IllegalArgumentException if the httpMethod or URL are empty
     * @throws NullPointerException if the httpMethod or the URL are null
     */
    protected RequestBuilder(String httpMethod, String url) {

        StringValidator.throwIfEmptyOrNull("httpMethod", httpMethod);
        StringValidator.throwIfEmptyOrNull("url", url);

        this.httpMethod = httpMethod;
        this.url = url;
    }

    /**
     * Returns the callback previously set by
     * {@link #setCallback(RequestCallback)}, or <code>null</code> if no callback
     * was set.
     */
    public RequestCallback getCallback() {
        return callback;
    }

    /**
     * Returns the value of a header previous set by
     * {@link #setHeader(String, String)}, or <code>null</code> if no such header
     * was set.
     * 
     * @param header the name of the header
     */
    public String getHeader(String header) {
        if (headers == null) {
            return null;
        }
        return headers.get(header);
    }

    /**
     * Returns the HTTP method specified in the constructor.
     */
    public String getHTTPMethod() {
        return httpMethod;
    }

    /**
     * Returns the password previously set by {@link #setPassword(String)}, or
     * <code>null</code> if no password was set.
     */
    public String getPassword() {
        return password;
    }

    /**
     * Returns the requestData previously set by {@link #setRequestData(String)},
     * or <code>null</code> if no requestData was set.
     */
    public String getRequestData() {
        return requestData;
    }

    /**
     * Returns the timeoutMillis previously set by {@link #setTimeoutMillis(int)},
     * or <code>0</code> if no timeoutMillis was set.
     */
    public int getTimeoutMillis() {
        return timeoutMillis;
    }

    /**
     * Returns the HTTP URL specified in the constructor.
     */
    public String getUrl() {
        return url;
    }

    /**
     * Returns the user previously set by {@link #setUser(String)}, or
     * <code>null</code> if no user was set.
     */
    public String getUser() {
        return user;
    }

    /**
     * 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
     * {@link #setRequestData(String)} and {@link #setCallback(RequestCallback)}
     * before calling this method.
     * 
     * @return a {@link Request} object that can be used to track the request
     * @throws RequestException if the call fails to initiate
     * @throws NullPointerException if a request callback has not been set
     */
    public Request send() throws RequestException {
        StringValidator.throwIfNull("callback", callback);
        return doSend(requestData, callback);
    }

    /**
     * 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 <code>requestData</code> or
     * <code>callback</code>.
     * 
     * @param requestData the data to send as part of the request
     * @param callback the response handler to be notified when the request fails
     *          or completes
     * @return a {@link Request} object that can be used to track the request
     * @throws NullPointerException if <code>callback</code> <code>null</code>
     */
    public Request sendRequest(String requestData, RequestCallback callback) throws RequestException {
        StringValidator.throwIfNull("callback", callback);
        return doSend(requestData, callback);
    }

    /**
     * Sets the response handler for this request. This method <b>must</b> be
     * called before calling {@link #send()}.
     * 
     * @param callback the response handler to be notified when the request fails
     *          or completes
     * 
     * @throws NullPointerException if <code>callback</code> is <code>null</code>
     */
    public void setCallback(RequestCallback callback) {
        StringValidator.throwIfNull("callback", callback);

        this.callback = callback;
    }

    /**
     * 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.
     * 
     * @param header the name of the header
     * @param value the value of the header
     * 
     * @throws NullPointerException if header or value are null
     * @throws IllegalArgumentException if header or value are the empty string
     */
    public void setHeader(String header, String value) {
        StringValidator.throwIfEmptyOrNull("header", header);
        StringValidator.throwIfEmptyOrNull("value", value);

        if (headers == null) {
            headers = new HashMap<String, String>();
        }

        headers.put(header, value);
    }

    /**
     * Sets the password to use in the request URL. This is ignored if there is no
     * user specified.
     * 
     * @param password password to use in the request URL
     * 
     * @throws IllegalArgumentException if the password is empty
     * @throws NullPointerException if the password is null
     */
    public void setPassword(String password) {
        StringValidator.throwIfEmptyOrNull("password", password);

        this.password = password;
    }

    /**
     * Sets the data to send as part of this request. This method <b>must</b> be
     * called before calling {@link #send()}.
     * 
     * @param requestData the data to send as part of the request
     */
    public void setRequestData(String requestData) {
        this.requestData = requestData;
    }

    /**
     * Sets the number of milliseconds to wait for a request to complete. Should
     * the request timeout, the
     * {@link com.google.gwt.http.client.RequestCallback#onError(Request, Throwable)}
     * method will be called on the callback instance given to the
     * {@link com.google.gwt.http.client.RequestBuilder#sendRequest(String, RequestCallback)}
     * method. The callback method will receive an instance of the
     * {@link com.google.gwt.http.client.RequestTimeoutException} class as its
     * {@link java.lang.Throwable} argument.
     * 
     * @param timeoutMillis number of milliseconds to wait before canceling the
     *          request, a value of zero disables timeouts
     * 
     * @throws IllegalArgumentException if the timeout value is negative
     */
    public void setTimeoutMillis(int timeoutMillis) {
        if (timeoutMillis < 0) {
            throw new IllegalArgumentException("Timeouts cannot be negative");
        }

        this.timeoutMillis = timeoutMillis;
    }

    /**
     * Sets the user name that will be used in the request URL.
     * 
     * @param user user name to use
     * @throws IllegalArgumentException if the user is empty
     * @throws NullPointerException if the user is null
     */
    public void setUser(String user) {
        StringValidator.throwIfEmptyOrNull("user", user);

        this.user = user;
    }

    /**
     * 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".
     * 
     * @return a {@link Request} object that can be used to track the request
     * @throws RequestException if the call fails to initiate
     * @throws NullPointerException if request data has not been set
     * @throws NullPointerException if a request callback has not been set
     */
    private Request doSend(String requestData, final RequestCallback callback) throws RequestException {
        XMLHttpRequest xmlHttpRequest = XMLHttpRequest.create();

        try {
            if ((user != null) && (password != null)) {
                if (m_sync) {
                    xmlHttpRequest.openSync(httpMethod, url, user, password);
                } else {
                    xmlHttpRequest.open(httpMethod, url, user, password);
                }
            } else if (user != null) {
                if (m_sync) {
                    xmlHttpRequest.openSync(httpMethod, url, user);
                } else {
                    xmlHttpRequest.open(httpMethod, url, user);
                }
            } else {
                if (m_sync) {
                    xmlHttpRequest.openSync(httpMethod, url);
                } else {
                    xmlHttpRequest.open(httpMethod, url);
                }
            }
        } catch (JavaScriptException e) {
            RequestPermissionException requestPermissionException = new RequestPermissionException(url);
            requestPermissionException.initCause(new RequestException(e.getMessage()));
            throw requestPermissionException;
        }

        setHeaders(xmlHttpRequest);

        final Request request = new Request(xmlHttpRequest, timeoutMillis, callback);

        if (!m_sync) {
            // Must set the onreadystatechange handler before calling send().
            xmlHttpRequest.setOnReadyStateChange(new ReadyStateChangeHandler() {

                public void onReadyStateChange(XMLHttpRequest xhr) {

                    if (xhr.getReadyState() == XMLHttpRequest.DONE) {
                        xhr.clearOnReadyStateChange();
                        request.fireOnResponseReceived(callback);
                    }
                }
            });
        }

        try {
            xmlHttpRequest.send(requestData);
        } catch (JavaScriptException e) {
            throw new RequestException(e.getMessage());
        }

        if (m_sync) {
            xmlHttpRequest.clearOnReadyStateChange();
            request.fireOnResponseReceived(callback);
        }

        return request;
    }

    /*
     * Internal method that actually sets our cached headers on the underlying
     * JavaScript XmlHttpRequest object. If there are no headers set, then we set
     * the "Content-Type" to "text/plain; charset=utf-8". This is really lining us
     * up for integration with RPC.
     */
    private void setHeaders(XMLHttpRequest xmlHttpRequest) throws RequestException {

        if ((headers != null) && (headers.size() > 0)) {
            for (Map.Entry<String, String> header : headers.entrySet()) {
                try {
                    xmlHttpRequest.setRequestHeader(header.getKey(), header.getValue());
                } catch (JavaScriptException e) {
                    throw new RequestException(e.getMessage());
                }
            }
        } else {
            xmlHttpRequest.setRequestHeader("Content-Type", "text/plain; charset=utf-8");
        }
    }

    private boolean m_sync = false;

    /**
     * Returns the sync.<p>
     *
     * @return the sync
     */
    public boolean isSync() {

        return m_sync;
    }

    /**
     * Sets the sync.<p>
     *
     * @param sync the sync to set
     */
    public void setSync(boolean sync) {

        m_sync = sync;
    }
}