1 /*

     2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.

     3 Code licensed under the BSD License:

     4 http://developer.yahoo.net/yui/license.txt

     5 version: 3.0.0

     6 build: 1549

     7 */

     8 YUI.add('io-base', function(Y) {

     9 

    10    /**

    11    	* Base IO functionality. Provides basic XHR transport support.

    12    	* @module io

    13    	* @submodule io-base

    14    	*/

    15 

    16    /**

    17 	* The io class is a utility that brokers HTTP requests through a simplified

    18 	* interface.  Specifically, it allows JavaScript to make HTTP requests to

    19 	* a resource without a page reload.  The underlying transport for making

    20 	* same-domain requests is the XMLHttpRequest object.  YUI.io can also use

    21 	* Flash, if specified as a transport, for cross-domain requests.

    22 	*

    23    	* @class io

    24    	*/

    25 

    26    /**

    27    	* @event io:start

    28    	* @description This event is fired by YUI.io when a transaction is initiated.

    29    	* @type Event Custom

    30    	*/

    31    	var E_START = 'io:start',

    32 

    33    /**

    34    	* @event io:complete

    35    	* @description This event is fired by YUI.io when a transaction is complete.

    36    	* Response status and data are accessible, if available.

    37    	* @type Event Custom

    38    	*/

    39    	E_COMPLETE = 'io:complete',

    40 

    41    /**

    42    	* @event io:success

    43    	* @description This event is fired by YUI.io when a transaction is complete, and

    44    	* the HTTP status resolves to HTTP2xx.

    45    	* @type Event Custom

    46    	*/

    47    	E_SUCCESS = 'io:success',

    48 

    49    /**

    50    	* @event io:failure

    51    	* @description This event is fired by YUI.io when a transaction is complete, and

    52    	* the HTTP status resolves to HTTP4xx, 5xx and above.

    53    	* @type Event Custom

    54    	*/

    55    	E_FAILURE = 'io:failure',

    56 

    57    /**

    58    	* @event io:end

    59    	* @description This event signifies the end of the transaction lifecycle.  The

    60    	* transaction transport is destroyed.

    61    	* @type Event Custom

    62    	*/

    63    	E_END = 'io:end',

    64 

    65    	//--------------------------------------

    66    	//  Properties

    67    	//--------------------------------------

    68    /**

    69    	* @description A transaction counter that increments for each transaction.

    70    	*

    71    	* @property transactionId

    72    	* @private

    73    	* @static

    74    	* @type int

    75    	*/

    76    	transactionId = 0,

    77 

    78    /**

    79    	* @description Object of default HTTP headers to be initialized and sent

    80    	* for all transactions.

    81    	*

    82    	* @property _headers

    83    	* @private

    84    	* @static

    85    	* @type object

    86    	*/

    87    	_headers = {

    88    		'X-Requested-With' : 'XMLHttpRequest'

    89    	},

    90 

    91    /**

    92    	* @description Object that stores timeout values for any transaction with

    93    	* a defined "timeout" configuration property.

    94    	*

    95    	* @property _timeout

    96    	* @private

    97    	* @static

    98    	* @type object

    99    	*/

   100    	_timeout = {},

   101 

   102    	// Window reference

   103    	w = Y.config.win;

   104 

   105    	//--------------------------------------

   106    	//  Methods

   107    	//--------------------------------------

   108    /**

   109    	* @description Method for requesting a transaction. _io() is implemented as

   110    	* yui.io().  Each transaction may include a configuration object.  Its

   111    	* properties are:

   112    	*

   113    	* method: HTTP method verb (e.g., GET or POST). If this property is not

   114    	*         not defined, the default value will be GET.

   115    	*

   116    	* data: This is the name-value string that will be sent as the transaction

   117     *		data.  If the request is HTTP GET, the data become part of

   118     *		querystring. If HTTP POST, the data are sent in the message body.

   119    	*

   120    	* xdr: Defines the transport to be used for cross-domain requests.  By

   121    	*      setting this property, the transaction will use the specified

   122    	*      transport instead of XMLHttpRequest.  Currently, the only alternate

   123    	*      transport supported is Flash (e.g., { xdr: 'flash' }).

   124    	*

   125    	* form: This is a defined object used to process HTML form as data.  The

   126    	*       properties are:

   127    	*       {

   128    	*	      id: object, //HTML form object or id of HTML form

   129    	*         useDisabled: boolean, //Allow disabled HTML form field values

   130    	*                      to be sent as part of the data.

   131 	*       }

   132 	*

   133 	* on: This is a defined object used to create and handle specific

   134 	*     events during a transaction lifecycle.  These events will fire in

   135 	*     addition to the global io events. The events are:

   136 	*	  start - This event is fired when a request is sent to a resource.

   137 	*     complete - This event fires when the transaction is complete.

   138 	*     success - This event fires when the response status resolves to

   139 	*               HTTP 2xx.

   140 	*     failure - This event fires when the response status resolves to

   141 	*               HTTP 4xx, 5xx; and, for all transaction exceptions,

   142 	*               including aborted transactions and transaction timeouts.

   143 	*	  end -  This even is fired at the conclusion of the transaction

   144    	*			 lifecycle, after a success or failure resolution.

   145 	*

   146 	*     The properties are:

   147 	*     {

   148    	*       start: function(id, args){},

   149    	*       complete: function(id, responseobject, args){},

   150    	*       success: function(id, responseobject, args){},

   151    	*       failure: function(id, responseobject, args){},

   152    	*       end: function(id, args){}

   153    	*     }

   154    	*	  Each property can reference a function or be written as an

   155    	*     inline function.

   156    	*

   157    	*     context: Object reference for an event handler when it is implemented

   158    	*              as a method of a base object. Defining "context" will preserve

   159    	*              the proper reference of "this" used in the event handler.

   160    	*     headers: This is a defined object of client headers, as many as.

   161    	*              desired for the transaction.  These headers are sentThe object

   162    	*              pattern is:

   163    	*              {

   164    	*		         header: value

   165    	*              }

   166    	*

   167    	* timeout: This value, defined as milliseconds, is a time threshold for the

   168    	*          transaction. When this threshold is reached, and the transaction's

   169    	*          Complete event has not yet fired, the transaction will be aborted.

   170    	* arguments: Object, array, string, or number passed to all registered

   171    	*            event handlers.  This value is available as the second

   172    	*            argument in the "start" and "abort" event handlers; and, it is

   173    	*            the third argument in the "complete", "success", and "failure"

   174    	*            event handlers.

   175    	*

   176    	* @method _io

   177    	* @private

   178    	* @static

   179 	* @param {string} uri - qualified path to transaction resource.

   180 	* @param {object} c - configuration object for the transaction.

   181 	* @param {number} i - transaction id, if already set by queue.

   182 	* @return object

   183    	*/

   184    	function _io(uri, c, i) {

   185    		var f, o, m;

   186    			c = c || {};

   187    			o = _create(c.xdr || c.form, i);

   188    			m = c.method ? c.method.toUpperCase() : 'GET';

   189 

   190    		if (c.form) {

   191    			if (c.form.upload) {

   192    				return Y.io._upload(o, uri, c);

   193    			}

   194    			else {

   195 				f = Y.io._serialize(c.form, c.data);

   196 				if (m === 'POST') {

   197 					c.data = f;

   198 					_setHeader('Content-Type', 'application/x-www-form-urlencoded');

   199 				}

   200 				else if (m === 'GET') {

   201 					uri = _concat(uri, f);

   202 				}

   203 			}

   204 		}

   205 		else if (c.data && m === 'GET') {

   206 			uri = _concat(uri, c.data);

   207 		}

   208 

   209    		if (c.xdr) {

   210 			if (c.xdr.use === 'native' && window.XDomainRequest || c.xdr.use === 'flash') {

   211    				return Y.io.xdr(uri, o, c);

   212 			}

   213 			if (c.xdr.credentials) {

   214 				o.c.withCredentials = true;

   215 			}

   216    		}

   217 

   218    		o.c.onreadystatechange = function() { _readyState(o, c); };

   219    		try {

   220 			o.c.open(m, uri, true);

   221    		}

   222    		catch(e0){

   223 			if (c.xdr) {

   224 				// This exception is usually thrown by browsers

   225 				// that do not support native XDR transactions.

   226 				return _resend(o, uri, c);

   227 			}

   228 		}

   229 

   230    		if (c.data && m === 'POST') {

   231    			_setHeader('Content-Type', 'application/x-www-form-urlencoded; charset=UTF-8');

   232    		}

   233 

   234    		_setHeaders(o.c, c.headers || {});

   235 		try {

   236 			// Using "null" will result in a POST request with

   237 			// no Content-Length defined.

   238 	   		o.c.send(c.data || '');

   239 		}

   240    		catch(e1) {

   241 			if (c.xdr) {

   242 				// This exception is usually thrown by browsers

   243 				// that do not support native XDR transactions.

   244 				return _resend(o, uri, c);

   245 			}

   246 		}

   247 

   248    		_ioStart(o.id, c);

   249    		// If config.timeout is defined, and the request is standard XHR,

   250    		// initialize timeout polling.

   251    		if (c.timeout) {

   252    			_startTimeout(o, c.timeout);

   253    		}

   254 

   255 		return {

   256 			id: o.id,

   257 			abort: function() {

   258 				return o.c ? _ioCancel(o, 'abort') : false;

   259 			},

   260 			isInProgress: function() {

   261 				return o.c ? o.c.readyState !== 4 && o.c.readyState !== 0 : false;

   262 	   		}

   263 		}

   264    	}

   265 

   266    /**

   267    	* @description Method for creating and subscribing transaction events.

   268    	*

   269    	* @method _subscribe

   270    	* @private

   271    	* @static

   272    	* @param {string} e - event to be published

   273    	* @param {object} c - configuration data subset for event subscription.

   274    	*

   275 	* @return void

   276    	*/

   277    	function _subscribe(e, c){

   278    		var evt = new Y.EventTarget().publish('transaction:' + e);

   279 		evt.subscribe(c.on[e], (c.context || Y), c.arguments);

   280 

   281    		return evt;

   282    	}

   283 

   284    /**

   285    	* @description Fires event "io:start" and creates, fires a

   286    	* transaction-specific start event, if config.on.start is

   287    	* defined.

   288    	*

   289    	* @method _ioStart

   290    	* @private

   291    	* @static

   292    	* @param {number} id - transaction id

   293    	* @param {object} c - configuration object for the transaction.

   294    	*

   295     * @return void

   296    	*/

   297    	function _ioStart(id, c) {

   298    		var evt;

   299    			// Set default value of argument c, property "on" to Object if

   300    			// the property is null or undefined.

   301    			c.on = c.on || {};

   302 

   303    		Y.fire(E_START, id);

   304    		if (c.on.start) {

   305    			evt = _subscribe('start', c);

   306    			evt.fire(id);

   307    		}

   308    	}

   309 

   310 

   311    /**

   312    	* @description Fires event "io:complete" and creates, fires a

   313    	* transaction-specific "complete" event, if config.on.complete is

   314    	* defined.

   315    	*

   316    	* @method _ioComplete

   317    	* @private

   318    	* @static

   319    	* @param {object} o - transaction object.

   320    	* @param {object} c - configuration object for the transaction.

   321    	*

   322     * @return void

   323    	*/

   324    	function _ioComplete(o, c) {

   325    		var evt,

   326 			r = o.status ? { status: 0, statusText: o.status } : o.c;

   327    			// Set default value of argument c, property "on" to Object if

   328    			// the property is null or undefined.

   329    			c.on = c.on || {};

   330 

   331    		Y.fire(E_COMPLETE, o.id, r);

   332    		if (c.on.complete) {

   333    			evt = _subscribe('complete', c);

   334    			evt.fire(o.id, r);

   335    		}

   336    	}

   337 

   338    /**

   339    	* @description Fires event "io:success" and creates, fires a

   340    	* transaction-specific "success" event, if config.on.success is

   341    	* defined.

   342    	*

   343    	* @method _ioSuccess

   344    	* @private

   345    	* @static

   346    	* @param {object} o - transaction object.

   347    	* @param {object} c - configuration object for the transaction.

   348    	*

   349     * @return void

   350    	*/

   351    	function _ioSuccess(o, c) {

   352    		var evt;

   353    			// Set default value of argument c, property "on" to Object if

   354    			// the property is null or undefined.

   355    			c.on = c.on || {};

   356 

   357    		Y.fire(E_SUCCESS, o.id, o.c);

   358    		if (c.on.success) {

   359    			evt = _subscribe('success', c);

   360    			evt.fire(o.id, o.c);

   361    		}

   362 

   363    		_ioEnd(o, c);

   364    	}

   365 

   366    /**

   367    	* @description Fires event "io:failure" and creates, fires a

   368    	* transaction-specific "failure" event, if config.on.failure is

   369    	* defined.

   370    	*

   371    	* @method _ioFailure

   372    	* @private

   373    	* @static

   374    	* @param {object} o - transaction object.

   375    	* @param {object} c - configuration object for the transaction.

   376    	*

   377     * @return void

   378    	*/

   379    	function _ioFailure(o, c) {

   380    		var evt,

   381  			r = o.status ? { status: 0, statusText: o.status } : o.c;

   382    			// Set default value of argument c, property "on" to Object if

   383    			// the property is null or undefined.

   384    			c.on = c.on || {};

   385 

   386    		Y.fire(E_FAILURE, o.id, r);

   387    		if (c.on.failure) {

   388    			evt = _subscribe('failure', c);

   389    			evt.fire(o.id, r);

   390    		}

   391 

   392    		_ioEnd(o, c);

   393    	}

   394 

   395    /**

   396    	* @description Fires event "io:end" and creates, fires a

   397    	* transaction-specific "end" event, if config.on.end is

   398    	* defined.

   399    	*

   400    	* @method _ioEnd

   401    	* @private

   402    	* @static

   403    	* @param {object} o - transaction object.

   404    	* @param {object} c - configuration object for the transaction.

   405    	*

   406     * @return void

   407    	*/

   408    	function _ioEnd(o, c) {

   409    		var evt;

   410    			// Set default value of argument c, property "on" to Object if

   411    			// the property is null or undefined.

   412    			c.on = c.on || {};

   413 

   414    		Y.fire(E_END, o.id);

   415    		if (c.on.end) {

   416    			evt = _subscribe('end', c);

   417    			evt.fire(o.id);

   418    		}

   419 

   420    		_destroy(o, c.xdr ? true : false );

   421    	}

   422 

   423    /**

   424    	* @description Terminates a transaction due to an explicit abort or

   425    	* timeout.

   426    	*

   427    	* @method _ioCancel

   428    	* @private

   429    	* @static

   430 	* @param {object} o - Transaction object generated by _create().

   431 	* @param {string} s - Identifies timed out or aborted transaction.

   432    	*

   433     * @return void

   434    	*/

   435    	function _ioCancel(o, s) {

   436    		if (o && o.c) {

   437    			o.status = s;

   438    			o.c.abort();

   439    		}

   440    	}

   441 

   442    /**

   443    	* @description Resends an XDR transaction, using the Flash tranport,

   444    	* if the native transport fails.

   445    	*

   446    	* @method _resend

   447    	* @private

   448    	* @static

   449 

   450 	* @param {object} o - Transaction object generated by _create().

   451 	* @param {string} uri - qualified path to transaction resource.

   452    	* @param {object} c - configuration object for the transaction.

   453    	*

   454     * @return void

   455    	*/

   456 	function _resend(o, uri, c) {

   457 		var id = parseInt(o.id);

   458 

   459 		_destroy(o);

   460 		c.xdr.use = 'flash';

   461 

   462 		return Y.io(uri, c, id);

   463 	}

   464 

   465    /**

   466    	* @description Method that increments _transactionId for each transaction.

   467    	*

   468    	* @method _id

   469    	* @private

   470    	* @static

   471     * @return int

   472    	*/

   473    	function _id() {

   474    		var id = transactionId;

   475 

   476    		transactionId++;

   477 

   478    		return id;

   479    	}

   480 

   481    /**

   482    	* @description Method that creates a unique transaction object for each

   483    	* request.

   484    	*

   485    	* @method _create

   486    	* @private

   487    	* @static

   488 	* @param {number} c - configuration object subset to determine if

   489 	*                     the transaction is an XDR or file upload,

   490 	*                     requiring an alternate transport.

   491 	* @param {number} i - transaction id

   492 	* @return object

   493    	*/

   494    	function _create(c, i) {

   495    		var o = {};

   496 	   		o.id = Y.Lang.isNumber(i) ? i : _id();

   497 	   		c = c || {};

   498 

   499 		if (!c.use && !c.upload) {

   500    			o.c = _xhr();

   501 		}

   502    		else if (c.use) {

   503 			if (c.use === 'flash') {

   504    				o.c = Y.io._transport[c.use];

   505 			}

   506 			else if (c.use === 'native' && window.XDomainRequest) {

   507 				o.c = new XDomainRequest();

   508 			}

   509 			else {

   510 				o.c = _xhr();

   511 			}

   512    		}

   513    		else {

   514    			o.c = {};

   515    		}

   516 

   517    		return o;

   518    	};

   519 

   520    /**

   521    	* @description Method that creates the XMLHttpRequest transport

   522    	*

   523    	* @method _xhr

   524    	* @private

   525    	* @static

   526 	* @return object

   527    	*/

   528    	function _xhr() {

   529    		return w.XMLHttpRequest ? new XMLHttpRequest() : new ActiveXObject('Microsoft.XMLHTTP');

   530    	}

   531 

   532    /**

   533    	* @description Method that concatenates string data for HTTP GET transactions.

   534    	*

   535    	* @method _concat

   536    	* @private

   537    	* @static

   538 	* @param {string} s - URI or root data.

   539 	* @param {string} d - data to be concatenated onto URI.

   540 	* @return int

   541    	*/

   542    	function _concat(s, d) {

   543    		s += ((s.indexOf('?') == -1) ? '?' : '&') + d;

   544    		return s;

   545    	}

   546 

   547    /**

   548    	* @description Method that stores default client headers for all transactions.

   549    	* If a label is passed with no value argument, the header will be deleted.

   550    	*

   551    	* @method _setHeader

   552    	* @private

   553    	* @static

   554 	* @param {string} l - HTTP header

   555 	* @param {string} v - HTTP header value

   556 	* @return int

   557    	*/

   558    	function _setHeader(l, v) {

   559    		if (v) {

   560    			_headers[l] = v;

   561    		}

   562    		else {

   563    			delete _headers[l];

   564    		}

   565    	}

   566 

   567    /**

   568    	* @description Method that sets all HTTP headers to be sent in a transaction.

   569    	*

   570    	* @method _setHeaders

   571    	* @private

   572    	* @static

   573 	* @param {object} o - XHR instance for the specific transaction.

   574 	* @param {object} h - HTTP headers for the specific transaction, as defined

   575 	*                     in the configuration object passed to YUI.io().

   576 	* @return void

   577    	*/

   578    	function _setHeaders(o, h) {

   579    		var p;

   580 

   581    		for (p in _headers) {

   582    			if (_headers.hasOwnProperty(p)) {

   583    				if (h[p]) {

   584    					// Configuration headers will supersede IO preset headers,

   585    					// if headers match.

   586    					break;

   587    				}

   588    				else {

   589    					h[p] = _headers[p];

   590    				}

   591    			}

   592    		}

   593 

   594    		for (p in h) {

   595    			if (h.hasOwnProperty(p)) {

   596    				o.setRequestHeader(p, h[p]);

   597    			}

   598    		}

   599    	}

   600 

   601    /**

   602    	* @description Starts timeout count if the configuration object

   603    	* has a defined timeout property.

   604    	*

   605    	* @method _startTimeout

   606    	* @private

   607    	* @static

   608 	* @param {object} o - Transaction object generated by _create().

   609 	* @param {object} c - Configuration object passed to YUI.io().

   610 	* @return void

   611    	*/

   612    	function _startTimeout(o, timeout) {

   613    		_timeout[o.id] = w.setTimeout(function() { _ioCancel(o, 'timeout'); }, timeout);

   614    	}

   615 

   616    /**

   617    	* @description Clears the timeout interval started by _startTimeout().

   618    	*

   619    	* @method _clearTimeout

   620    	* @private

   621    	* @static

   622 	* @param {number} id - Transaction id.

   623 	* @return void

   624    	*/

   625    	function _clearTimeout(id) {

   626    		w.clearTimeout(_timeout[id]);

   627    		delete _timeout[id];

   628    	}

   629 

   630    /**

   631    	* @description Event handler bound to onreadystatechange.

   632    	*

   633    	* @method _readyState

   634    	* @private

   635    	* @static

   636 	* @param {object} o - Transaction object generated by _create().

   637 	* @param {object} c - Configuration object passed to YUI.io().

   638 	* @return void

   639    	*/

   640    	function _readyState(o, c) {

   641    		if (o.c.readyState === 4) {

   642    			if (c.timeout) {

   643    				_clearTimeout(o.id);

   644    			}

   645 

   646    			w.setTimeout(

   647    				function() {

   648    					_ioComplete(o, c);

   649    					_handleResponse(o, c);

   650    				}, 0);

   651    		}

   652    	}

   653 

   654    /**

   655    	* @description Method that determines if a transaction response qualifies

   656    	* as success or failure, based on the response HTTP status code, and

   657    	* fires the appropriate success or failure events.

   658    	*

   659    	* @method _handleResponse

   660    	* @private

   661    	* @static

   662 	* @param {object} o - Transaction object generated by _create().

   663 	* @param {object} c - Configuration object passed to io().

   664 	* @return void

   665    	*/

   666    	function _handleResponse(o, c) {

   667    		var status;

   668    		try{

   669    			if (o.c.status && o.c.status !== 0) {

   670    				status = o.c.status;

   671    			}

   672    			else {

   673    				status = 0;

   674    			}

   675    		}

   676    		catch(e) {

   677    			status = 0;

   678    		}

   679 

   680    		// IE reports HTTP 204 as HTTP 1223.

   681    		if (status >= 200 && status < 300 || status === 1223) {

   682    			_ioSuccess(o, c);

   683    		}

   684    		else {

   685    			_ioFailure(o, c);

   686    		}

   687    	}

   688 

   689    	function _destroy(o, transport) {

   690    		// IE, when using XMLHttpRequest as an ActiveX Object, will throw

   691    		// a "Type Mismatch" error if the event handler is set to "null".

   692    		if(w.XMLHttpRequest && !transport) {

   693    			if (o.c) {

   694    				o.c.onreadystatechange = null;

   695    			}

   696    		}

   697 

   698    		o.c = null;

   699    		o = null;

   700    	}

   701 

   702    	_io.start = _ioStart;

   703 	_io.complete = _ioComplete;

   704    	_io.success = _ioSuccess;

   705    	_io.failure = _ioFailure;

   706    	_io.end = _ioEnd;

   707    	_io._id = _id;

   708    	_io._timeout = _timeout;

   709 

   710 	//--------------------------------------

   711 	//  Begin public interface definition

   712 	//--------------------------------------

   713    /**

   714    	* @description Method that stores default client headers for all transactions.

   715    	* If a label is passed with no value argument, the header will be deleted.

   716    	* This is the interface for _setHeader().

   717    	*

   718    	* @method header

   719    	* @public

   720    	* @static

   721 	* @param {string} l - HTTP header

   722 	* @param {string} v - HTTP header value

   723 	* @return int

   724    	*/

   725    	_io.header = _setHeader;

   726 

   727    /**

   728    	* @description Method for requesting a transaction. This

   729    	* is the interface for _io().

   730    	*

   731    	* @method io

   732    	* @public

   733    	* @static

   734     * @param {string} uri - qualified path to transaction resource.

   735     * @param {object} c - configuration object for the transaction.

   736     * @return object

   737     */

   738    	Y.io = _io;

   739 	Y.io.http = _io;

   740 

   741 

   742 

   743 }, '3.0.0' ,{requires:['event-custom-base']});