001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js.user;
021 
022 import js.*;
023 import js.core.*;
024 
025 /**
026  * <p>An <b>opaque</b> class representing JavaScript client-side objects of the global 
027  * {@link JsClient#XMLHttpRequest} class.</p>
028  * <p>A {@link JsXMLHttpRequest} object allows client-side JavaScript to issue HTTP 
029  * requests and receive responses, which need not be XML, from web servers.</p>
030  * <p>{@link JsXMLHttpRequest} is quite portable and well supported by all modern 
031  * browsers. The only browser dependency involves the creation of an {@link JsXMLHttpRequest} 
032  * object. In IE, you must use the constructor of the IE-specific {@link JsClient#ActiveXObject}: 
033  * {@link js.dom.DOM.ActiveXObject#create(String)}.</p>
034  * <p>Once a {@link JsXMLHttpRequest} object has been created, you typically use it like this:
035  * <ol>
036  * <li>Call {@link JsXMLHttpRequest#open(String, String, Boolean, String, String)} to specify the URL 
037  * and method (usually "GET" or "POST") for the request. When you call {@link JsXMLHttpRequest#open(String, String, Boolean, String, String)}, 
038  * you also specify whether you want the request to be synchronous or asynchronous.</li>
039  * <li>If you specified an asynchronous request, set the {@link JsXMLHttpRequest#onreadystatechange} 
040  * property to the function that will be notified of the progress of the request.</li>
041  * <li>Call {@link JsXMLHttpRequest#setRequestHeader(String, String)}, if needed, to 
042  * specify additional request parameters</li>
043  * <li>Call {@link JsXMLHttpRequest#send(Object)} to send the request to the web server. 
044  * If it is a POST request, you may also pass a request body to this method. If you 
045  * specify a synchronous request in your call to {@link JsXMLHttpRequest#open(String, String, Boolean, String, String)}, 
046  * the {@link JsXMLHttpRequest#send(Object)} method blocks until the response is complete 
047  * and {@link JsXMLHttpRequest#readyState} is {@link JsXMLHttpRequest#LOADED}. Otherwise, 
048  * your {@link JsXMLHttpRequest#onreadystatechange} event handler function must wait 
049  * until the {@link JsXMLHttpRequest#readyState} property reaches {@link JsXMLHttpRequest#LOADED} 
050  * (or at least {@link JsXMLHttpRequest#RECEIVING}).</li>
051  * <li>Once {@link JsXMLHttpRequest#send(Object)} has returned for synchronous requests, 
052  * or {@link JsXMLHttpRequest#readyState} has reached {@link JsXMLHttpRequest#LOADED} 
053  * for asynchronous requests, you can use the server's response. First, check the {@link JsXMLHttpRequest#status} 
054  * code to ensure that the request was successful. If so, use {@link JsXMLHttpRequest#getResponseHeader(String)} 
055  * or {@link JsXMLHttpRequest#getAllResponseHeaders()} to retrieve values from the 
056  * response header, and use the {@link JsXMLHttpRequest#responseText} or {@link JsXMLHttpRequest#responseXML} 
057  * properties to obtain the response body.</li>
058  * </ol></p>
059  * <p>{@link JsXMLHttpRequest} objects have not been standardized, but work on a 
060  * standard has begun at the W3C.</p>
061  *
062  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
063  *
064  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be
065  * generated into the target codes. Re-compilers must exit with error on the operations of
066  * accessing that kind of class objects.
067  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored
068  * and <tt>instanceof</tt> to it always <tt>true</tt>.
069  */
070 public class JsXMLHttpRequest extends JsClient.XMLHttpRequest.Prototype
071 {
072     /**
073      * A legal value for the {@link #readyState} representing the initial state that 
074      * the {@link JsXMLHttpRequest} object has just been created or has been reset with 
075      * the {@link #abort()} method.
076      * @since 1.0
077      */
078     public final static short UNINITIALIZED = 0;
079     /**
080      * A legal value for the {@link #readyState} indicating that the {@link #open(String, String)} 
081      * method has been called, but {@link #send(Object)} has not, that is, the request 
082      * has not yet been sent.
083      * @since 1.0
084      */
085     public final static short OPEN          = 1;
086     /**
087      * A legal value for the {@link #readyState} indicating that the {@link #send(Object)} 
088      * method has been called, and the HTTP request has been transmitted to the web 
089      * server but no response has been received yet.
090      * @since 1.0
091      */
092     public final static short SENT          = 2;
093     /**
094      * A legal value for the {@link #readyState} indicating that all response headers 
095      * have been received and the response body is being received but is not complete.
096      * @since 1.0
097      */
098     public final static short RECEIVING     = 3;
099     /**
100      * A legal value for the {@link #readyState} indicating that the HTTP response 
101      * has been fully received.
102      * @since 1.0
103      */
104     public final static short LOADED        = 4;
105 
106     /**
107      * <p>An <b>internal</b> class containing membership data for its enclosing
108      * opaque class.</p>
109      * <p>This class is only used inside of <b>opaque</b> or <b>internal</b> classes or
110      * class members.</p>
111      *
112      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
113      * 
114      * @javascript Re-compilers must report error on resolving an <b>internal</b> class.
115      */
116     protected static abstract class Members extends JsClient.XMLHttpRequest.Prototype.Members
117     {
118         /**
119          * <p>An <b>internal</b> static field defining a member ID of the field name and
120          * used internally to define a member of the same name.</p>
121          * @since 1.0
122          * @see JsXMLHttpRequest#readyState
123          * @see JsXMLHttpRequest.Member#readyState
124          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
125          */
126         public final static Mid readyState         = id("readyState"        );
127         /**
128          * <p>An <b>internal</b> static field defining a member ID of the field name and
129          * used internally to define a member of the same name.</p>
130          * @since 1.0
131          * @see JsXMLHttpRequest#responseText
132          * @see JsXMLHttpRequest.Member#responseText
133          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
134          */
135         public final static Mid responseText       = id("responseText"      );
136         /**
137          * <p>An <b>internal</b> static field defining a member ID of the field name and
138          * used internally to define a member of the same name.</p>
139          * @since 1.0
140          * @see JsXMLHttpRequest#responseXML
141          * @see JsXMLHttpRequest.Member#responseXML
142          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
143          */
144         public final static Mid responseXML        = id("responseXML"       );
145         /**
146          * <p>An <b>internal</b> static field defining a member ID of the field name and
147          * used internally to define a member of the same name.</p>
148          * @since 1.0
149          * @see JsXMLHttpRequest#status
150          * @see JsXMLHttpRequest.Member#status
151          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
152          */
153         public final static Mid status             = id("status"            );
154         /**
155          * <p>An <b>internal</b> static field defining a member ID of the field name and
156          * used internally to define a member of the same name.</p>
157          * @since 1.0
158          * @see JsXMLHttpRequest#statusText
159          * @see JsXMLHttpRequest.Member#statusText
160          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
161          */
162         public final static Mid statusText         = id("statusText"        );
163         /**
164          * <p>An <b>internal</b> static field defining a member ID of the field name and
165          * used internally to define a member of the same name.</p>
166          * @since 1.0
167          * @see JsXMLHttpRequest#onreadystatechange
168          * @see JsXMLHttpRequest.Member#onreadystatechange
169          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
170          */
171         public final static Mid onreadystatechange = id("onreadystatechange");
172     }
173     /**
174      * <p>An <b>opaque</b> class representing members of its enclosing <b>opaque</b> type.</p>
175      * <p>Note that, this class is <b>opaque</b> but its constructors are all <b>internal</b>. 
176      * This class and the subclasses of this class are used to declare either <b>opaque</b> 
177      * <tt>public</tt> instance fields of the opaque type {@link js.Var.Member} or the 
178      * <b>opaque</b> <tt>public</tt> static fields of other <b>opaque</b> types while their 
179      * constructors are used to define the fields inside <b>opaque</b> classes. Under 
180      * either circumstance, the field names must be exactly same as the member names, as 
181      * the <b>opaque</b> fields of <b>opaque</b> types are resolved by re-compilers directly 
182      * based on the field names.</p>
183      *
184      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
185      * 
186      * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be created
187      * in the target codes. Re-compilers must exit with error on operations accessing that kind 
188      * of class objects.
189      * Re-compilers must resolve an <b>opaque</b> instance field declared by this class in
190      * {@link js.Var.Member} or its subclasses to the JavaScript identifier: 
191      * <pre>q.m</pre>
192      * where <tt>m</tt> is the identifier of the field name and <tt>q</tt> is the identifier
193      * resolved from the instance of the enclosing member. Re-compilers must resolve an 
194      * <b>opaque</b> static field declared by this class in <b>opaque</b> types other than 
195      * {@link js.Var.Member} and its subclasses to the JavaScript identifier: 
196      * <pre>m</pre>
197      * where <tt>m</tt> is the identifier of the field name. And re-compilers must report
198      * error on the access to <b>opaque</b> fields declared by this class under any other 
199      * circumstances.
200      */
201     public static class Member extends JsClient.XMLHttpRequest.Prototype.Member
202     {
203         /**
204          * <p>Internally constructs a member based on a qualifying member.</p>
205          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
206          * or <b>internal</b> classes or class members.</p>
207          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
208          * <b>opaque</b>. This constructor is used to define <b>opaque</b> instance fields 
209          * declared in the declaring class of this constructor itself or its subclasses. 
210          * Under this circumstance, the field names must be exactly same as the member 
211          * names, as the <b>opaque</b> instance fields of the <b>opaque</b> type 
212          * {@link js.Var.Member} or its subclasses are resolved by re-compilers directly
213          * to their names appending to the name resolved from the specified qualifying 
214          * member with a dot in between.</p>
215          * @param q A qualifying member
216          * @param mid The ID of the member to construct
217          * @since 1.0
218          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
219          */
220         public Member(JsObject.Member q, Mid mid) {
221             super(q, mid);
222         }
223         /**
224          * <p>Internally constructs a member without a qualifying member.</p>
225          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
226          * or <b>internal</b> classes or class members.</p>
227          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
228          * <b>opaque</b>. This constructor is used to define <b>opaque</b> static fields, 
229          * declared in <b>opaque</b> types other than the declaring class of this constructor 
230          * itself and its subclasses. Under this circumstance, the field names must be
231          * exactly same as the member names, as the <b>opaque</b> static fields of <b>opaque</b>
232          * types are generally resolved by re-compilers directly to identifiers of their names.</p>
233          * @param mid The ID of the member to construct
234          * @since 1.0
235          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
236          */
237         public Member(Mid mid) {
238             super(mid);
239         }
240         @Override
241         /**
242          * <p>Evaluates the property, represented by the current member instance, of the
243          * argument object.</p>
244          * @param o The argument object
245          * @return The value of the current member based on the object argument.
246          * @since 1.0
247          * @javascript Re-compilers must convert the instance invocation of this method into
248          * the JavaScript expression: 
249          * <pre>o.m</pre>
250          * where <tt>m</tt> is the identifier name resolved from the current member
251          * instance of the invocation.
252          */
253         public JsXMLHttpRequest with(ObjectLike o) {
254             return new JsXMLHttpRequest(super.with(o));
255         }
256 
257         /**
258          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
259          * name of this field, qualified by the current member instance of the field, and 
260          * to access the property of the name on an object.</p>
261          * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
262          * refers to a read-only integer value specifying the state of the HTTP request. 
263          * The value begins at {@link JsXMLHttpRequest#UNINITIALIZED} or 0 when the {@link JsXMLHttpRequest} 
264          * object is first created and increases to {@link JsXMLHttpRequest#LOADED} or 4 
265          * when the complete HTTP response has been received. The five states are {@link JsXMLHttpRequest#UNINITIALIZED}, 
266          * {@link JsXMLHttpRequest#OPEN}, {@link JsXMLHttpRequest#SENT}, {@link JsXMLHttpRequest#RECEIVING} 
267          * and {@link JsXMLHttpRequest#LOADED}, each having an informal name associated 
268          * with it.</p>
269          * <p>The value of the property never decreases, unless {@link JsXMLHttpRequest#abort()} 
270          * or {@link JsXMLHttpRequest#open(String, String, Boolean, String, String)} method 
271          * is called on a request that is already in progress. Every time the value of 
272          * the property increases, the {@link JsXMLHttpRequest#onreadystatechange} event 
273          * handler is triggered.</p> 
274          * @since 1.0
275          * @see JsXMLHttpRequest#UNINITIALIZED
276          * @see JsXMLHttpRequest#OPEN
277          * @see JsXMLHttpRequest#SENT
278          * @see JsXMLHttpRequest#RECEIVING
279          * @see JsXMLHttpRequest#LOADED
280          * @see JsXMLHttpRequest#onreadystatechange
281          * @see JsXMLHttpRequest#abort()
282          * @see JsXMLHttpRequest#open(String, String)
283          * @see JsXMLHttpRequest#open(String, String, Boolean)
284          * @see JsXMLHttpRequest#open(String, String, Boolean, String, String)
285          * @javascript Re-compilers must resolve the member of this instance field to the
286          * identifier of the field name appending to the identifier resolved from its 
287          * qualifying member with a dot in between.
288          */
289         public final Value.Number.Member readyState   = new Value.Number.Member(this, Members.readyState  );
290         /**
291          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
292          * name of this field, qualified by the current member instance of the field, and 
293          * to access the property of the name on an object.</p>
294          * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
295          * refers to a read-only string value specifying the body of the response, excluding 
296          * headers, that has been received from the server so far, or the empty string if 
297          * no data has been received yet. If {@link #readyState} is less than {@link JsXMLHttpRequest#RECEIVING}, 
298          * the property is the empty string. When {@link #readyState} is {@link JsXMLHttpRequest#RECEIVING}, 
299          * the property returns whatever portion of the response has been received so 
300          * far. If {@link #readyState} is {@link JsXMLHttpRequest#LOADED}, the property 
301          * holds the complete body of the response.</p>
302          * <p>If the response includes headers that specify a character encoding for the 
303          * body, that encoding is used. Otherwise, the Unicode UTF-8 encoding is assumed.</p> 
304          * @since 1.0
305          * @see JsXMLHttpRequest#UNINITIALIZED
306          * @see JsXMLHttpRequest#OPEN
307          * @see JsXMLHttpRequest#SENT
308          * @see JsXMLHttpRequest#RECEIVING
309          * @see JsXMLHttpRequest#LOADED
310          * @javascript Re-compilers must resolve the member of this instance field to the
311          * identifier of the field name appending to the identifier resolved from its 
312          * qualifying member with a dot in between.
313          */
314         public final Value.String.Member responseText = new Value.String.Member(this, Members.responseText);
315         /**
316          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
317          * name of this field, qualified by the current member instance of the field, and 
318          * to access the property of the name on an object.</p>
319          * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
320          * refers to a read-only integer value specifying the HTTP status code returned 
321          * by the server, such as 200 for success and 404 for "Not Found" errors. 
322          * Reading this property when {@link #readyState} is less than {@link JsXMLHttpRequest#RECEIVING} 
323          * causes an error.</p> 
324          * @since 1.0
325          * @see JsXMLHttpRequest#UNINITIALIZED
326          * @see JsXMLHttpRequest#OPEN
327          * @see JsXMLHttpRequest#SENT
328          * @see JsXMLHttpRequest#RECEIVING
329          * @see JsXMLHttpRequest#LOADED
330          * @javascript Re-compilers must resolve the member of this instance field to the
331          * identifier of the field name appending to the identifier resolved from its 
332          * qualifying member with a dot in between.
333          */
334         public final Value.Number.Member status       = new Value.Number.Member(this, Members.status      );
335         /**
336          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
337          * name of this field, qualified by the current member instance of the field, and 
338          * to access the property of the name on an object.</p>
339          * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
340          * refers to a read-only string value specifying the HTTP status code of the 
341          * request by name rather than by number. That is, it is "OK" when status is 200 
342          * and "Not Found" when status is 404. As with the {@link #status} property, reading 
343          * the property when {@link #readyState} is less than {@link JsXMLHttpRequest#RECEIVING} 
344          * causes an error.</p> 
345          * @since 1.0
346          * @see JsXMLHttpRequest#UNINITIALIZED
347          * @see JsXMLHttpRequest#OPEN
348          * @see JsXMLHttpRequest#SENT
349          * @see JsXMLHttpRequest#RECEIVING
350          * @see JsXMLHttpRequest#LOADED
351          * @javascript Re-compilers must resolve the member of this instance field to the
352          * identifier of the field name appending to the identifier resolved from its 
353          * qualifying member with a dot in between.
354          */
355         public final Value.String.Member statusText   = new Value.String.Member(this, Members.statusText  );
356         /**
357          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
358          * name of this field, qualified by the current member instance of the field, and 
359          * to access the property of the name on an object.</p>
360          * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object
361          * is a read-only reference to the response to the request, parsed as XML and 
362          * returned as a Document object. The property will be <tt>null</tt> unless all 
363          * three of the following conditions are true:
364          * <ul>
365          * <li>{@link #readyState} is {@link JsXMLHttpRequest#LOADED}.</li>
366          * <li>The response includes a <tt>Content-Type</tt> header of "text/xml", 
367          * "application/xml", or anything ending with "+xml" to indicate that the 
368          * response is an XML document.</li>
369          * <li>The response body consists of well-formed XML mark-up that can be parsed 
370          * without errors.</li>
371          * </ul></p> 
372          * @since 1.0
373          * @javascript Re-compilers must resolve the member of this instance field to the
374          * identifier of the field name appending to the identifier resolved from its 
375          * qualifying member with a dot in between.
376          */
377         public final JsDocument.Member responseXML = new JsDocument.Member(this, Members.responseXML);
378         /**
379          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
380          * name of this field, qualified by the current member instance of the field, and 
381          * to access the property of the name on an object.</p>
382          * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object
383          * is a reference to the event handler function invoked each time the {@link #readyState} 
384          * property changes. It may also be invoked multiple times while {@link #readyState} 
385          * is {@link JsXMLHttpRequest#RECEIVING}.</p> 
386          * @since 1.0
387          * @javascript Re-compilers must resolve the member of this instance field to the
388          * identifier of the field name appending to the identifier resolved from its 
389          * qualifying member with a dot in between.
390          */
391         public final JsFunction.Member<?> onreadystatechange = new JsFunction.Member<Object>(this, Members.onreadystatechange);
392     }
393 
394     /**
395      * <p>Casts an <b>opaque</b> object to the current <b>opaque</b> type by wrapping it
396      * with the wrapping constructor.</p>
397      * @param var The argument of an <b>opaque</b> object.
398      * @since 1.0
399      * @javascript Re-compilers must ignore the construction operation of this constructor,
400      * that is, replacing it with its only argument.
401      */
402     public JsXMLHttpRequest(JsObject var) {
403         super(var);
404     }
405 
406     /**
407      * <p>An <b>opaque</b> static field defining a member that is named by the field name
408      * without a qualifying member and to access the property of the name on an object.</p>
409      * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
410      * refers to a read-only integer value specifying the state of the HTTP request. 
411      * The value begins at {@link #UNINITIALIZED} or 0 when the {@link JsXMLHttpRequest} 
412      * object is first created and increases to {@link JsXMLHttpRequest#LOADED} or 4 
413      * when the complete HTTP response has been received. The five states are {@link #UNINITIALIZED}, 
414      * {@link #OPEN}, {@link #SENT}, {@link #RECEIVING} and {@link #LOADED}, each having 
415      * an informal name associated with it.</p>
416      * <p>The value of the property never decreases, unless the {@link #abort()} 
417      * or {@link #open(String, String, Boolean, String, String)} method is called on a 
418      * request that is already in progress. Every time the value of the property 
419      * increases, the {@link #onreadystatechange} event handler is triggered.</p> 
420      * @since 1.0
421      * @see #UNINITIALIZED
422      * @see #OPEN
423      * @see #SENT
424      * @see #RECEIVING
425      * @see #LOADED
426      * @see #onreadystatechange
427      * @see #abort()
428      * @see #open(String, String)
429      * @see #open(String, String, Boolean)
430      * @see #open(String, String, Boolean, String, String)
431      * @javascript Re-compilers must resolve the member of this static field to the
432      * identifier of the field name.
433      */
434     public static final Value.Number.Member readyState   = new Value.Number.Member(Members.readyState  );
435     /**
436      * <p>An <b>opaque</b> static field defining a member that is named by the field name
437      * without a qualifying member and to access the property of the name on an object.</p>
438      * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
439      * refers to a read-only string value specifying the body of the response, excluding 
440      * headers, that has been received from the server so far, or the empty string if 
441      * no data has been received yet. If {@link #readyState} is less than {@link #RECEIVING}, 
442      * the property is the empty string. When {@link #readyState} is {@link #RECEIVING}, 
443      * the property returns whatever portion of the response has been received so 
444      * far. If {@link #readyState} is {@link #LOADED}, the property holds the complete 
445      * body of the response.</p>
446      * <p>If the response includes headers that specify a character encoding for the 
447      * body, that encoding is used. Otherwise, the Unicode UTF-8 encoding is assumed.</p> 
448      * @since 1.0
449      * @see #UNINITIALIZED
450      * @see #OPEN
451      * @see #SENT
452      * @see #RECEIVING
453      * @see #LOADED
454      * @javascript Re-compilers must resolve the member of this static field to the
455      * identifier of the field name.
456      */
457     public static final Value.String.Member responseText = new Value.String.Member(Members.responseText);
458     /**
459      * <p>An <b>opaque</b> static field defining a member that is named by the field name
460      * without a qualifying member and to access the property of the name on an object.</p>
461      * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
462      * refers to a read-only integer value specifying the HTTP status code returned 
463      * by the server, such as 200 for success and 404 for "Not Found" errors. 
464      * Reading this property when {@link #readyState} is less than {@link #RECEIVING} 
465      * causes an error.</p> 
466      * @since 1.0
467      * @see #UNINITIALIZED
468      * @see #OPEN
469      * @see #SENT
470      * @see #RECEIVING
471      * @see #LOADED
472      * @javascript Re-compilers must resolve the member of this static field to the
473      * identifier of the field name.
474      */
475     public static final Value.Number.Member status       = new Value.Number.Member(Members.status      );
476     /**
477      * <p>An <b>opaque</b> static field defining a member that is named by the field name
478      * without a qualifying member and to access the property of the name on an object.</p>
479      * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object 
480      * refers to a read-only string value specifying the HTTP status code of the 
481      * request by name rather than by number. That is, it is "OK" when status is 200 
482      * and "Not Found" when status is 404. As with the {@link #status} property, reading 
483      * the property when {@link #readyState} is less than {@link #RECEIVING} causes an 
484      * error.</p> 
485      * @since 1.0
486      * @see #UNINITIALIZED
487      * @see #OPEN
488      * @see #SENT
489      * @see #RECEIVING
490      * @see #LOADED
491      * @javascript Re-compilers must resolve the member of this static field to the
492      * identifier of the field name.
493      */
494     public static final Value.String.Member statusText   = new Value.String.Member(Members.statusText  );
495     /**
496      * <p>An <b>opaque</b> static field defining a member that is named by the field name
497      * without a qualifying member and to access the property of the name on an object.</p>
498      * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object
499      * is a read-only reference to the response to the request, parsed as XML and 
500      * returned as a Document object. The property will be <tt>null</tt> unless all 
501      * three of the following conditions are true:
502      * <ul>
503      * <li>{@link #readyState} is {@link #LOADED}.</li>
504      * <li>The response includes a <tt>Content-Type</tt> header of "text/xml", 
505      * "application/xml", or anything ending with "+xml" to indicate that the 
506      * response is an XML document.</li>
507      * <li>The response body consists of well-formed XML mark-up that can be parsed 
508      * without errors.</li>
509      * </ul></p> 
510      * @since 1.0
511      * @javascript Re-compilers must resolve the member of this static field to the
512      * identifier of the field name.
513      */
514     public static final JsDocument.Member responseXML = new JsDocument.Member(Members.responseXML);
515     /**
516      * <p>An <b>opaque</b> static field defining a member that is named by the field name
517      * without a qualifying member and to access the property of the name on an object.</p>
518      * <p>The property, identified by this member, of a {@link JsXMLHttpRequest} object
519      * is a reference to the event handler function invoked each time the {@link #readyState} 
520      * property changes. It may also be invoked multiple times while {@link #readyState} 
521      * is {@link #RECEIVING}.</p> 
522      * @since 1.0
523      * @javascript Re-compilers must resolve the member of this static field to the
524      * identifier of the field name.
525      */
526     public static final JsFunction.Member<?> onreadystatechange = new JsFunction.Member<Object>(Members.onreadystatechange);
527 
528     @Override
529     /**
530      * <p>Returns the primitive value associated with the current instance, if there is one.
531      * This invocation simply returns the instance itself for the current instance is an 
532      * object and there is no primitive value for it.</p>
533      * @return The current object itself.
534      * @since 1.0
535      * @javascript Re-compilers must convert the instance invocation of this method directly
536      * into a JavaScript invocation on its current object instance without changing the 
537      * method name, but expanding variable arguments, if any, into comma-separated values. 
538      */
539     public JsXMLHttpRequest valueOf() {
540         return new JsXMLHttpRequest((JsObject)var().valueOf());
541     }
542     public final JsDocument var(JsDocument.Member r) {
543         return r.with(this);
544     }
545 
546     /**
547      * <p>Cancels the current request, closing connections and stopping any pending 
548      * network activity.</p>
549      * <p>This method resets the {@link JsXMLHttpRequest} object to a {@link #readyState} 
550      * of {@link #UNINITIALIZED} and aborts any pending network activity. You might call 
551      * this method, for example, if a request has taken too long, and the response is 
552      * no longer necessary.</p>
553      * @since 1.0
554      * @javascript Re-compilers must convert the instance invocation of this method directly
555      * into a JavaScript invocation on its current object instance without changing the 
556      * method name, but expanding variable arguments, if any, into comma-separated values. 
557      */
558     public void abort() {
559         call(abort);
560     }
561     /**
562      * <p>Returns the HTTP response headers as an unparsed string.</p>
563      * @return <tt>null</tt> if {@link #readyState} is less than {@link #RECEIVING}; 
564      * Otherwise, it returns all HTTP response headers, but not the status line, sent by 
565      * the server. The headers are returned as a single string, with one header per line. 
566      * Lines are delimited by "\r\n" line terminators.
567      * @since 1.0
568      * @javascript Re-compilers must convert the instance invocation of this method directly
569      * into a JavaScript invocation on its current object instance without changing the 
570      * method name, but expanding variable arguments, if any, into comma-separated values. 
571      */
572     public String getAllResponseHeaders() {
573         return call(getAllResponseHeaders);
574     }
575     /**
576      * <p>Returns the value of a named HTTP response header.</p>
577      * @param header The name of the HTTP response header whose value is to be returned. 
578      * the <tt>header</tt> name may be specified using any case, as the comparison to 
579      * response headers is case-insensitive.
580      * @return The value of the named HTTP response header, or the empty string if no 
581      * such header was received or if {@link #readyState} is less than {@link #RECEIVING}. 
582      * If more than one header with the specified name is received, the values of those 
583      * headers are concatenated and returned, using a comma and space as the delimiter.
584      * @since 1.0
585      * @see #getResponseHeader(StringLike)
586      * @javascript Re-compilers must convert the instance invocation of this method directly
587      * into a JavaScript invocation on its current object instance without changing the 
588      * method name, but expanding variable arguments, if any, into comma-separated values. 
589      */
590     public String getResponseHeader(String header) {
591         return call(getResponseHeader, header);
592     }
593     /**
594      * <p>Returns the value of a named HTTP response header.</p>
595      * @param header The name of the HTTP response header whose value is to be returned. 
596      * the <tt>header</tt> name may be specified using any case, as the comparison to 
597      * response headers is case-insensitive.
598      * @return The value of the named HTTP response header, or the empty string if no 
599      * such header was received or if {@link #readyState} is less than {@link #RECEIVING}. 
600      * If more than one header with the specified name is received, the values of those 
601      * headers are concatenated and returned, using a comma and space as the delimiter.
602      * @since 1.0
603      * @see #getResponseHeader(String)
604      * @javascript Re-compilers must convert the instance invocation of this method directly
605      * into a JavaScript invocation on its current object instance without changing the 
606      * method name, but expanding variable arguments, if any, into comma-separated values. 
607      */
608     public String getResponseHeader(StringLike header) {
609         return getResponseHeader(Js.valueOf(header));
610     }
611     /**
612      * <p>Initializes HTTP request parameters, such as the URL and HTTP method, but 
613      * does not send the request.</p>
614      * <p>This method initializes request parameters for later use by the {@link #send(Object)} 
615      * method. It sets {@link #readyState} to {@link #OPEN}, deletes any previously 
616      * specified request headers and previously received response headers, and sets the 
617      * {@link #responseText}, {@link #responseXML}, {@link #status}, and {@link #statusText} 
618      * properties to their default values. It is safe to call this method when {@link #readyState} 
619      * is {@link #UNINITIALIZED} {when the {@link JsXMLHttpRequest} object is just created 
620      * or after a call to {@link #abort()}), and when {@link #readyState} is {@link #LOADED}, 
621      * (after a response has been received). The behavior of this method is unspecified 
622      * when it is called from any other state.</p>
623      * <p>Other than storing request parameters for use by {@link #send(Object)} and 
624      * resetting the {@link JsXMLHttpRequest} object for reuse, this method has no other 
625      * behavior. In particular, note that implementations do not typically open a 
626      * network connection to the web server when this method is called.</p>
627      * @param method The HTTP method to be used for the request. Reliably implemented 
628      * values include "GET", "POST", and "HEAD". Implementations may also support other 
629      * methods as well.
630      * @param url The URL that is the subject of the request. Most browsers impose a 
631      * same-origin security policy and require that this URL have the same host name and 
632      * port as the document that contains the script. Relative URLs are resolved in the 
633      * normal way, using the URL of the document that contains the script.
634      * @since 1.0
635      * @see #open(String, String, Boolean)
636      * @see #open(String, String, Boolean, String, String)
637      * @see #send(Object)
638      * @javascript Re-compilers must convert the instance invocation of this method directly
639      * into a JavaScript invocation on its current object instance without changing the 
640      * method name, but expanding variable arguments, if any, into comma-separated values. 
641      */
642     public void open(String method, String url) {
643         call(open, new Vars<Object>().add(method).add(url));
644     }
645     /**
646      * <p>Initializes HTTP request parameters, such as the URL and HTTP method, but 
647      * does not send the request.</p>
648      * <p>This method initializes request parameters for later use by the {@link #send(Object)} 
649      * method. It sets {@link #readyState} to {@link #OPEN}, deletes any previously 
650      * specified request headers and previously received response headers, and sets the 
651      * {@link #responseText}, {@link #responseXML}, {@link #status}, and {@link #statusText} 
652      * properties to their default values. It is safe to call this method when {@link #readyState} 
653      * is {@link #UNINITIALIZED} {when the {@link JsXMLHttpRequest} object is just created 
654      * or after a call to {@link #abort()}), and when {@link #readyState} is {@link #LOADED}, 
655      * (after a response has been received). The behavior of this method is unspecified 
656      * when it is called from any other state.</p>
657      * <p>Other than storing request parameters for use by {@link #send(Object)} and 
658      * resetting the {@link JsXMLHttpRequest} object for reuse, this method has no other 
659      * behavior. In particular, note that implementations do not typically open a 
660      * network connection to the web server when this method is called.</p>
661      * @param method The HTTP method to be used for the request. Reliably implemented 
662      * values include "GET", "POST", and "HEAD". Implementations may also support other 
663      * methods as well.
664      * @param url The URL that is the subject of the request. Most browsers impose a 
665      * same-origin security policy and require that this URL have the same host name and 
666      * port as the document that contains the script. Relative URLs are resolved in the 
667      * normal way, using the URL of the document that contains the script.
668      * @param async Specifies whether the request should be performed asynchronously or 
669      * not. If this argument is <tt>false</tt>, the request is synchronous, and a 
670      * subsequent call to {@link #send(Object)} will block until the response is fully 
671      * received. If this argument is <tt>true</tt> or is undefined, the request is 
672      * asynchronous, and an {@link #onreadystatechange} event handler is typically 
673      * required.
674      * @since 1.0
675      * @see #open(String, String)
676      * @see #open(String, String, Boolean, String, String)
677      * @see #send(Object)
678      * @javascript Re-compilers must convert the instance invocation of this method directly
679      * into a JavaScript invocation on its current object instance without changing the 
680      * method name, but expanding variable arguments, if any, into comma-separated values. 
681      */
682     public void open(String method, String url, Boolean async) {
683         call(open, new Vars<Object>().add(method).add(url).add(async));
684     }
685     /**
686      * <p>Initializes HTTP request parameters, such as the URL and HTTP method, but 
687      * does not send the request.</p>
688      * <p>This method initializes request parameters for later use by the {@link #send(Object)} 
689      * method. It sets {@link #readyState} to {@link #OPEN}, deletes any previously 
690      * specified request headers and previously received response headers, and sets the 
691      * {@link #responseText}, {@link #responseXML}, {@link #status}, and {@link #statusText} 
692      * properties to their default values. It is safe to call this method when {@link #readyState} 
693      * is {@link #UNINITIALIZED} {when the {@link JsXMLHttpRequest} object is just created 
694      * or after a call to {@link #abort()}), and when {@link #readyState} is {@link #LOADED}, 
695      * (after a response has been received). The behavior of this method is unspecified 
696      * when it is called from any other state.</p>
697      * <p>Other than storing request parameters for use by {@link #send(Object)} and 
698      * resetting the {@link JsXMLHttpRequest} object for reuse, this method has no other 
699      * behavior. In particular, note that implementations do not typically open a 
700      * network connection to the web server when this method is called.</p>
701      * @param method The HTTP method to be used for the request. Reliably implemented 
702      * values include "GET", "POST", and "HEAD". Implementations may also support other 
703      * methods as well.
704      * @param url The URL that is the subject of the request. Most browsers impose a 
705      * same-origin security policy and require that this URL have the same host name and 
706      * port as the document that contains the script. Relative URLs are resolved in the 
707      * normal way, using the URL of the document that contains the script.
708      * @param async Specifies whether the request should be performed asynchronously or 
709      * not. If this argument is <tt>false</tt>, the request is synchronous, and a 
710      * subsequent call to {@link #send(Object)} will block until the response is fully 
711      * received. If this argument is <tt>true</tt> or is undefined, the request is 
712      * asynchronous, and an {@link #onreadystatechange} event handler is typically 
713      * required.
714      * @param username An optional argument specifying authorization user name for use 
715      * with URLs that require authorization. If specified, it overrides the user name 
716      * specified in the URL itself.
717      * @param password An optional argument specifying authorization password for use 
718      * with URLs that require authorization. If specified, it overrides the password 
719      * specified in the URL itself.
720      * @since 1.0
721      * @see #open(String, String)
722      * @see #open(String, String, Boolean)
723      * @see #send(Object)
724      * @javascript Re-compilers must convert the instance invocation of this method directly
725      * into a JavaScript invocation on its current object instance without changing the 
726      * method name, but expanding variable arguments, if any, into comma-separated values. 
727      */
728     public void open(String method, String url, Boolean async, String username, String password) {
729         call(open, new Vars<Object>().add(method).add(url).add(async).add(username).add(password));
730     }
731     /**
732      * <p>Sends the HTTP request, using parameters passed to the {@link #open(String, String, Boolean, String, String)} 
733      * method and an optional request <tt>body</tt> passed to this method.</p>
734      * <p>This method causes an HTTP request to be issued. If there has been no previous 
735      * call to {@link #open(String, String, Boolean)}, or, more generally, if {@link #readyState} 
736      * is not {@link #OPEN}, this method throws an error. Otherwise, it issues an HTTP 
737      * request that consists of:
738      * <ul>
739      * <li>The HTTP method, URL, and authorization credentials (if any) specified in the 
740      * previous call to {@link #open(String, String, Boolean, String, String)}.</li>
741      * <li>The request headers, if any, specified by previous calls to {@link #setRequestHeader(String, String)}.</li>
742      * <li>The <tt>body</tt> argument passed to this method.</li>
743      * </ul>
744      * Once the request has been issued, this method sets {@link #readyState} to {@link #SENT} 
745      * and triggers the {@link #onreadystatechange} event handler.</p>
746      * <p>If the <tt>async</tt> argument to the previous call to {@link #open(String, String, Boolean, String, String)} 
747      * was <tt>false</tt>, this method blocks and does not return until {@link #readyState} 
748      * is {@link #LOADED} and the server's response has been fully received. Otherwise, 
749      * if the <tt>async</tt> argument is <tt>true</tt> or if that argument is undefined, 
750      * this method returns immediately, and the server's response is processed on a 
751      * background thread.</p>
752      * <p>If the server responds with an HTTP redirect, this method or the background 
753      * thread follow the redirect automatically. When all HTTP response headers have 
754      * been received, this method or the background thread sets {@link #readyState} to 
755      * {@link #RECEIVING} and triggers the {@link #onreadystatechange} event handler. 
756      * If the response is long, this method or the background thread may trigger the 
757      * {@link #onreadystatechange} more than once while in state {@link #RECEIVING}. 
758      * This can serve as a download progress indicator. Finally, when the response is 
759      * complete, this method or the background thread sets {@link #readyState} to {@link #LOADED} 
760      * and triggers the event handler one last time.</p>
761      * @param body If the HTTP method specified by the call to {@link #open(String, String, Boolean, String, String)} 
762      * is "POST" or "PUT", this argument specifies the body of the request, as a string 
763      * or {@link JsDocument} object, or <tt>null</tt> if no body is necessary. For any 
764      * other method, this argument is unused and should be <tt>null</tt>, but some 
765      * implementations do not allow you to omit this argument.
766      * @since 1.0
767      * @see #open(String, String)
768      * @see #open(String, String, Boolean)
769      * @see #open(String, String, Boolean, String, String)
770      * @javascript Re-compilers must convert the instance invocation of this method directly
771      * into a JavaScript invocation on its current object instance without changing the 
772      * method name, but expanding variable arguments, if any, into comma-separated values. 
773      */
774     public void send(Object body) {
775         call(send, body);
776     }
777     /**
778      * <p>Sets or adds an HTTP request header to an open but unsent request.</p>
779      * <p>This method specifies an HTTP request header that should be included in the 
780      * request issued by a subsequent call to {@link #send(Object)}. This method may be 
781      * called only when {@link #readyState} is {@link #OPEN}, that is, after a call to 
782      * {@link #open(String, String, Boolean, String, String)} but before a call to {@link #send(Object)}.</p>
783      * <p>If a header with the specified name has already been specified, the new value 
784      * for that header is the previously specified value, plus a comma, a space, and the 
785      * value specified in this call.</p>
786      * <p>If the call to {@link #open(String, String, Boolean, String, String)} specifies 
787      * authorization credentials, {@link JsClient#XMLHttpRequest} automatically sends an 
788      * appropriate <tt>Authorization</tt> request header. You can append to this header 
789      * with this method, however. Similarly, if the web browser has stored cookies 
790      * associated with the URL passed to {@link #open(String, String, Boolean, String, String)}, 
791      * appropriate <tt>Cookie</tt> or <tt>Cookie2</tt> headers are automatically included 
792      * with the request. You can append additional cookies to these headers by calling 
793      * this method. {@link JsClient#XMLHttpRequest} may also provide a default value for 
794      * the <tt>User-Agent</tt> header. If it does this, any value you specify for that 
795      * header is appended to the default value.</p>
796      * <p>Some request headers are automatically set by the {@link JsClient#XMLHttpRequest} 
797      * for conformance to the HTTP protocol and may not be set with this method. These 
798      * include proxy-related headers as well as the following:
799      * <ul>
800      * <li><tt>Host</tt></li>
801      * <li><tt>Connection</tt></li>
802      * <li><tt>Keep-Alive</tt></li>
803      * <li><tt>Accept-Charset</tt></li>
804      * <li><tt>Accept-Encoding</tt></li>
805      * <li><tt>If-Modified-Since</tt></li>
806      * <li><tt>If-None-Match</tt></li>
807      * <li><tt>If-Range</tt></li>
808      * <li><tt>Range</tt></li>
809      * </ul></p>
810      * @param name The name of the header to be set. This argument should not contain 
811      * spaces, colons, linefeeds, or newlines.
812      * @param value The value for the header. This argument should not contain 
813      * linefeeds or newlines.
814      * @since 1.0
815      * @javascript Re-compilers must convert the instance invocation of this method directly
816      * into a JavaScript invocation on its current object instance without changing the 
817      * method name, but expanding variable arguments, if any, into comma-separated values. 
818      */
819     public void setRequestHeader(String name, String value) {
820         call(setRequestHeader, new Vars<Object>().add(name).add(value));
821     }
822 }