All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.gwt.xhr.client.XMLHttpRequest Maven / Gradle / Ivy

There is a newer version: 2.10.0
Show newest version
/*
 * 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 http://www.w3.org/TR/XMLHttpRequest//
 */
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 XmlHttpRequest.onreadystatechange 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.
   * 

* See http://www.w3.org/TR/XMLHttpRequest/#the-abort-method. */ public final native void abort() /*-{ this.abort(); }-*/; /** * Clears the {@link ReadyStateChangeHandler}. *

* See http://www.w3.org/TR/XMLHttpRequest/#handler-xhr-onreadystatechange. * * @see #clearOnReadyStateChange() */ public final native void clearOnReadyStateChange() /*-{ this.onreadystatechange = function() {}; }-*/; /** * Gets all the HTTP response headers, as a single string. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-getallresponseheaders-method. * * @return the response headers. */ public final native String getAllResponseHeaders() /*-{ return this.getAllResponseHeaders(); }-*/; /** * Get's the current ready-state. *

* See http://www.w3.org/TR/XMLHttpRequest/#dom-xmlhttprequest-state. * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-getresponseheader-method. * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-responsetext-attribute. * * @return the response text */ public final native String getResponseText() /*-{ return this.responseText; }-*/; /** * Gets the response type. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute * * @return the response type */ public final native String getResponseType() /*-{ return this.responseType || ""; }-*/; /** * Gets the status code. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-status-attribute. * * @return the status code */ public final native int getStatus() /*-{ return this.status; }-*/; /** * Gets the status text. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-statustext-attribute. * * @return the status text */ public final native String getStatusText() /*-{ return this.statusText; }-*/; /** * Opens an asynchronous connection. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-open-method. * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-open-method. * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-open-method. * * @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 null as an argument, because the * no-argument send() method is unavailable on Firefox. */ public final void send() { send(null); } /** * Initiates a request with data. If there is no data, specify null. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-send-method. * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#handler-xhr-onreadystatechange. * *

* Note: Applications must 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. *

* * @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() { [email protected]::onReadyStateChange(Lcom/google/gwt/xhr/client/XMLHttpRequest;)(_this); }); }-*/; /** * Sets a request header. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-setrequestheader-method. * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-withcredentials-attribute. * * @param withCredentials whether to include credentials in XHR */ public final native void setWithCredentials(boolean withCredentials) /*-{ this.withCredentials = withCredentials; }-*/; /** * Sets the response type. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute * * @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. *

* See http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute * * @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; }-*/; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy