| /* |
| * Copyright 2009 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.xhr.client; |
| |
| import com.google.gwt.core.client.JavaScriptObject; |
| import com.google.gwt.typedarrays.shared.ArrayBuffer; |
| |
| /** |
| * The native XMLHttpRequest object. Most applications should use the higher- |
| * level {@link com.google.gwt.http.client.RequestBuilder} class unless they |
| * need specific functionality provided by the XMLHttpRequest object. |
| * |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/" |
| * >http://www.w3.org/TR/XMLHttpRequest/</a>/ |
| */ |
| public class XMLHttpRequest extends JavaScriptObject { |
| |
| /** |
| * The type of response expected from the XHR. |
| */ |
| public enum ResponseType { |
| /** |
| * The default response type -- use {@link XMLHttpRequest#getResponseText()} |
| * for the return value. |
| */ |
| Default(""), |
| |
| /** |
| * The default response type -- use |
| * {@link XMLHttpRequest#getResponseArrayBuffer()} for the return value. |
| * This value may only be used if |
| * {@link com.google.gwt.typedarrays.shared.TypedArrays#isSupported()} |
| * returns true. |
| */ |
| ArrayBuffer("arraybuffer"); |
| |
| // not implemented yet |
| /* |
| Blob("blob"), |
| |
| Document("document"), |
| |
| Text("text"); |
| */ |
| |
| private final String responseTypeString; |
| |
| private ResponseType(String responseTypeString) { |
| this.responseTypeString = responseTypeString; |
| } |
| |
| public String getResponseTypeString() { |
| return responseTypeString; |
| } |
| } |
| |
| /* |
| * NOTE: Testing discovered that for some bizarre reason, on Mozilla, the |
| * JavaScript <code>XmlHttpRequest.onreadystatechange</code> handler |
| * function maybe still be called after it is deleted. The theory is that the |
| * callback is cached somewhere. Setting it to null or an empty function does |
| * seem to work properly, though. |
| * |
| * On IE, setting onreadystatechange to null (as opposed to an empty function) |
| * sometimes throws an exception. |
| * |
| * End result: *always* set onreadystatechange to an empty function (never to |
| * null). |
| */ |
| |
| /** |
| * When constructed, the XMLHttpRequest object must be in the UNSENT state. |
| */ |
| public static final int UNSENT = 0; |
| |
| /** |
| * The OPENED state is the state of the object when the open() method has been |
| * successfully invoked. During this state request headers can be set using |
| * setRequestHeader() and the request can be made using send(). |
| */ |
| public static final int OPENED = 1; |
| |
| /** |
| * The HEADERS_RECEIVED state is the state of the object when all response |
| * headers have been received. |
| */ |
| public static final int HEADERS_RECEIVED = 2; |
| |
| /** |
| * The LOADING state is the state of the object when the response entity body |
| * is being received. |
| */ |
| public static final int LOADING = 3; |
| |
| /** |
| * The DONE state is the state of the object when either the data transfer has |
| * been completed or something went wrong during the transfer (infinite |
| * redirects for instance). |
| */ |
| public static final int DONE = 4; |
| |
| /** |
| * Creates an XMLHttpRequest object. |
| * |
| * @return the created object |
| */ |
| public static native XMLHttpRequest create() /*-{ |
| return new $wnd.XMLHttpRequest(); |
| }-*/; |
| |
| protected XMLHttpRequest() { |
| } |
| |
| /** |
| * Aborts the current request. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-abort-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-abort-method</a>. |
| */ |
| public final native void abort() /*-{ |
| this.abort(); |
| }-*/; |
| |
| /** |
| * Clears the {@link ReadyStateChangeHandler}. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#handler-xhr-onreadystatechange" |
| * >http://www.w3.org/TR/XMLHttpRequest/#handler-xhr-onreadystatechange</a>. |
| * |
| * @see #clearOnReadyStateChange() |
| */ |
| public final native void clearOnReadyStateChange() /*-{ |
| this.onreadystatechange = function() {}; |
| }-*/; |
| |
| /** |
| * Gets all the HTTP response headers, as a single string. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-getallresponseheaders-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-getallresponseheaders-method</a>. |
| * |
| * @return the response headers. |
| */ |
| public final native String getAllResponseHeaders() /*-{ |
| return this.getAllResponseHeaders(); |
| }-*/; |
| |
| /** |
| * Get's the current ready-state. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#dom-xmlhttprequest-readystate" |
| * >http://www.w3.org/TR/XMLHttpRequest/#dom-xmlhttprequest-state</a>. |
| * |
| * @return the ready-state constant |
| */ |
| public final native int getReadyState() /*-{ |
| return this.readyState; |
| }-*/; |
| |
| /** |
| * Get the response as an {@link ArrayBuffer}. |
| * |
| * @return an {@link ArrayBuffer} containing the response, or null if the |
| * request is in progress or failed |
| */ |
| public final native ArrayBuffer getResponseArrayBuffer() /*-{ |
| return this.response; |
| }-*/; |
| |
| /** |
| * Gets an HTTP response header. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-getresponseheader-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-getresponseheader-method</a>. |
| * |
| * @param header the response header to be retrieved |
| * @return the header value |
| */ |
| public final native String getResponseHeader(String header) /*-{ |
| return this.getResponseHeader(header); |
| }-*/; |
| |
| /** |
| * Gets the response text. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-responsetext-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-responsetext-attribute</a>. |
| * |
| * @return the response text |
| */ |
| public final native String getResponseText() /*-{ |
| return this.responseText; |
| }-*/; |
| |
| /** |
| * Gets the response type. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute</a> |
| * |
| * @return the response type |
| */ |
| public final native String getResponseType() /*-{ |
| return this.responseType || ""; |
| }-*/; |
| |
| /** |
| * Gets the status code. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-status-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-status-attribute</a>. |
| * |
| * @return the status code |
| */ |
| public final native int getStatus() /*-{ |
| return this.status; |
| }-*/; |
| |
| /** |
| * Gets the status text. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-statustext-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-statustext-attribute</a>. |
| * |
| * @return the status text |
| */ |
| public final native String getStatusText() /*-{ |
| return this.statusText; |
| }-*/; |
| |
| /** |
| * Opens an asynchronous connection. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-open-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-open-method</a>. |
| * |
| * @param httpMethod the HTTP method to use |
| * @param url the URL to be opened |
| */ |
| public final native void open(String httpMethod, String url) /*-{ |
| this.open(httpMethod, url, true); |
| }-*/; |
| |
| /** |
| * Opens an asynchronous connection. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-open-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-open-method</a>. |
| * |
| * @param httpMethod the HTTP method to use |
| * @param url the URL to be opened |
| * @param user user to use in the URL |
| */ |
| public final native void open(String httpMethod, String url, String user) /*-{ |
| this.open(httpMethod, url, true, user); |
| }-*/; |
| |
| /** |
| * Opens an asynchronous connection. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-open-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-open-method</a>. |
| * |
| * @param httpMethod the HTTP method to use |
| * @param url the URL to be opened |
| * @param user user to use in the URL |
| * @param password password to use in the URL |
| */ |
| public final native void open(String httpMethod, String url, String user, |
| String password) /*-{ |
| this.open(httpMethod, url, true, user, password); |
| }-*/; |
| |
| /** |
| * Initiates a request with no request data. This simply calls |
| * {@link #send(String)} with <code>null</code> as an argument, because the |
| * no-argument <code>send()</code> method is unavailable on Firefox. |
| */ |
| public final void send() { |
| send(null); |
| } |
| |
| /** |
| * Initiates a request with data. If there is no data, specify null. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-send-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-send-method</a>. |
| * |
| * @param requestData the data to be sent with the request |
| */ |
| public final native void send(String requestData) /*-{ |
| this.send(requestData); |
| }-*/; |
| |
| /** |
| * Sets the {@link ReadyStateChangeHandler} to be notified when the object's |
| * ready-state changes. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#handler-xhr-onreadystatechange" |
| * >http://www.w3.org/TR/XMLHttpRequest/#handler-xhr-onreadystatechange</a>. |
| * |
| * <p> |
| * Note: Applications <em>must</em> call {@link #clearOnReadyStateChange()} |
| * when they no longer need this object, to ensure that it is cleaned up |
| * properly. Failure to do so will result in memory leaks on some browsers. |
| * </p> |
| * |
| * @param handler the handler to be called when the ready state changes |
| * @see #clearOnReadyStateChange() |
| */ |
| public final native void setOnReadyStateChange(ReadyStateChangeHandler handler) /*-{ |
| // The 'this' context is always supposed to point to the xhr object in the |
| // onreadystatechange handler, but we reference it via closure to be extra sure. |
| var _this = this; |
| this.onreadystatechange = $entry(function() { |
| handler.@com.google.gwt.xhr.client.ReadyStateChangeHandler::onReadyStateChange(Lcom/google/gwt/xhr/client/XMLHttpRequest;)(_this); |
| }); |
| }-*/; |
| |
| /** |
| * Sets a request header. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-setrequestheader-method" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-setrequestheader-method</a>. |
| * |
| * @param header the header to be set |
| * @param value the header's value |
| */ |
| public final native void setRequestHeader(String header, String value) /*-{ |
| this.setRequestHeader(header, value); |
| }-*/; |
| |
| /** |
| * Sets withCredentials attribute. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-withcredentials-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-withcredentials-attribute</a>. |
| * |
| * @param withCredentials whether to include credentials in XHR |
| */ |
| public final native void setWithCredentials(boolean withCredentials) /*-{ |
| this.withCredentials = withCredentials; |
| }-*/; |
| |
| /** |
| * Sets the response type. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute</a> |
| * |
| * @param responseType the type of response desired. See {@link ResponseType} |
| * for limitations on using the different values |
| */ |
| public final void setResponseType(ResponseType responseType) { |
| this.setResponseType(responseType.getResponseTypeString()); |
| } |
| |
| /** |
| * Sets the response type. |
| * <p> |
| * See <a href="http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute" |
| * >http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute</a> |
| * |
| * @param responseType the type of response desired. See {@link ResponseType} |
| * for limitations on using the different values |
| */ |
| public final native void setResponseType(String responseType) /*-{ |
| this.responseType = responseType; |
| }-*/; |
| } |