elemental.xml.XMLHttpRequest Maven / Gradle / Ivy
/*
* Copyright 2012 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 elemental.xml;
import elemental.events.EventTarget;
import elemental.html.ArrayBuffer;
import elemental.html.Blob;
import elemental.html.FormData;
import elemental.events.EventListener;
import elemental.dom.Document;
import elemental.events.Event;
import elemental.events.*;
import elemental.util.*;
import elemental.dom.*;
import elemental.html.*;
import elemental.css.*;
import elemental.stylesheets.*;
import java.util.Date;
/**
* XMLHttpRequest is a JavaScript object that was designed by Microsoft and adopted by Mozilla, Apple, and Google. It's now being standardized in the W3C. It provides an easy way to retrieve data at a URL. Despite its name, XMLHttpRequest can be used to retrieve any type of data, not just XML, and it supports protocols other than HTTP (including file and ftp).
To create an instance of XMLHttpRequest, simply do this:
var req = new XMLHttpRequest();
For details about how to use XMLHttpRequest, see Using XMLHttpRequest.
*/
public interface XMLHttpRequest extends EventTarget {
/**
* The operation is complete.
*/
static final int DONE = 4;
/**
* send() has been called, and headers and status are available.
*/
static final int HEADERS_RECEIVED = 2;
/**
* Downloading; responseText holds partial data.
*/
static final int LOADING = 3;
/**
* send()has not been called yet.
*/
static final int OPENED = 1;
/**
* open()has not been called yet.
*/
static final int UNSENT = 0;
boolean isAsBlob();
void setAsBlob(boolean arg);
EventListener getOnabort();
void setOnabort(EventListener arg);
EventListener getOnerror();
void setOnerror(EventListener arg);
EventListener getOnload();
void setOnload(EventListener arg);
EventListener getOnloadend();
void setOnloadend(EventListener arg);
EventListener getOnloadstart();
void setOnloadstart(EventListener arg);
EventListener getOnprogress();
void setOnprogress(EventListener arg);
EventListener getOnreadystatechange();
void setOnreadystatechange(EventListener arg);
/**
* The state of the request:
Value State Description 0UNSENTopen()has not been called yet. 1OPENEDsend()has not been called yet. 2HEADERS_RECEIVEDsend() has been called, and headers and status are available. 3LOADINGDownloading; responseText holds partial data. 4DONEThe operation is complete.
*/
int getReadyState();
/**
* The response entity body according to responseType, as an ArrayBuffer, Blob, Document
, JavaScript object (for "moz-json"), or string. This is NULL if the request is not complete or was not successful.
*/
Object getResponse();
Blob getResponseBlob();
/**
* The response to the request as text, or null if the request was unsuccessful or has not yet been sent. Read-only.
*/
String getResponseText();
/**
* Can be set to change the response type. This tells the server what format you want the response to be in.
Value Data type of response property empty string String (this is the default) "arraybuffer" ArrayBuffer "blob" Blob
"document" Document
"text" String "moz-json" JavaScript object, parsed from a JSON string returned by the server
Requires Gecko 9.0
*/
String getResponseType();
void setResponseType(String arg);
/**
* The response to the request as a DOM Document object, or null if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML. The response is parsed as if it were a text/xml stream. Read-only.
Note: If the server doesn't apply the text/xml Content-Type header, you can use overrideMimeType()to force XMLHttpRequest to parse it as XML anyway.
*/
Document getResponseXML();
/**
* The status of the response to the request. This is the HTTP result code (for example, status is 200 for a successful request). Read-only.
*/
int getStatus();
/**
* The response string returned by the HTTP server. Unlike status, this includes the entire text of the response message ("200 OK", for example). Read-only.
*/
String getStatusText();
/**
* The upload process can be tracked by adding an event listener to upload.
New in Firefox 3.5
*/
XMLHttpRequestUpload getUpload();
/**
* Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies or authorization headers.
New in Firefox 3.5
Note: This never affects same-site requests. The default is false.
*/
boolean isWithCredentials();
void setWithCredentials(boolean arg);
/**
* Aborts the request if it has already been sent.
*/
void abort();
EventRemover addEventListener(String type, EventListener listener);
EventRemover addEventListener(String type, EventListener listener, boolean useCapture);
boolean dispatchEvent(Event evt);
/**
* string getAllResponseHeaders();
Returns all the response headers as a string, or null if no response has been received. Note: For multipart requests, this returns the headers from the current part of the request, not from the original channel.
*/
String getAllResponseHeaders();
/**
* Returns the string containing the text of the specified header, or null if either the response has not yet been received or the header doesn't exist in the response.
*/
String getResponseHeader(String header);
/**
* Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.
Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().
Parameters
method- The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.
url- The URL to which to send the request.
async- An optional boolean parameter, defaulting to
true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown. user- The optional user name to use for authentication purposes; by default, this is an empty string.
password- The optional password to use for authentication purposes; by default, this is an empty string.
*/
void open(String method, String url);
/**
* Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.
Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().
Parameters
method- The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.
url- The URL to which to send the request.
async- An optional boolean parameter, defaulting to
true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown. user- The optional user name to use for authentication purposes; by default, this is an empty string.
password- The optional password to use for authentication purposes; by default, this is an empty string.
*/
void open(String method, String url, boolean async);
/**
* Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.
Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().
Parameters
method- The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.
url- The URL to which to send the request.
async- An optional boolean parameter, defaulting to
true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown. user- The optional user name to use for authentication purposes; by default, this is an empty string.
password- The optional password to use for authentication purposes; by default, this is an empty string.
*/
void open(String method, String url, boolean async, String user);
/**
* Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.
Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().
Parameters
method- The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.
url- The URL to which to send the request.
async- An optional boolean parameter, defaulting to
true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown. user- The optional user name to use for authentication purposes; by default, this is an empty string.
password- The optional password to use for authentication purposes; by default, this is an empty string.
*/
void open(String method, String url, boolean async, String user, String password);
/**
* Overrides the MIME type returned by the server. This may be used, for example, to force a stream to be treated and parsed as text/xml, even if the server does not report it as such.This method must be called before send().
*/
void overrideMimeType(String override);
void removeEventListener(String type, EventListener listener);
void removeEventListener(String type, EventListener listener, boolean useCapture);
/**
* Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
Note: Any event listeners you wish to set must be set before calling send().
Parameters
body- This may be an
nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile
, and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
you may also specify a FormData object.
*/
void send();
/**
* Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
Note: Any event listeners you wish to set must be set before calling send().
Parameters
body- This may be an
nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile
, and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
you may also specify a FormData object.
*/
void send(ArrayBuffer data);
/**
* Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
Note: Any event listeners you wish to set must be set before calling send().
Parameters
body- This may be an
nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile
, and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
you may also specify a FormData object.
*/
void send(Blob data);
/**
* Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
Note: Any event listeners you wish to set must be set before calling send().
Parameters
body- This may be an
nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile
, and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
you may also specify a FormData object.
*/
void send(Document data);
/**
* Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
Note: Any event listeners you wish to set must be set before calling send().
Parameters
body- This may be an
nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile
, and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
you may also specify a FormData object.
*/
void send(String data);
/**
* Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
Note: Any event listeners you wish to set must be set before calling send().
Parameters
body- This may be an
nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile
, and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
you may also specify a FormData object.
*/
void send(FormData data);
/**
* Sets the value of an HTTP request header.You must call open()before using this method.
Parameters
header- The name of the header whose value is to be set.
value- The value to set as the body of the header.
*/
void setRequestHeader(String header, String value);
}