io/js/io-base.js

io-base.js revision 52085b0c6a9a5207a1e8368ec8de34501b7784dd
  /**
   * Base IO functionality. Provides basic XHR transport support.
   * @module io
   * @submodule io-base
   */

  /**
   * The io class is a utility that brokers HTTP requests through a simplified
   * interface.  Specifically, it allows JavaScript to make HTTP requests to
   * a resource without a page reload.  The underlying transport for making
   * same-domain requests is the XMLHttpRequest object.  YUI.io can also use
   * Flash, if specified as a transport, for cross-domain requests.
   *
   * @class io
   */

  /**
   * @event io:start
   * @description This event is fired by YUI.io when a transaction is initiated.
   * @type Event Custom
   */
   var E_START = 'io:start',

  /**
   * @event io:complete
   * @description This event is fired by YUI.io when a transaction is complete.
   * Response status and data are accessible, if available.
   * @type Event Custom
   */
   E_COMPLETE = 'io:complete',

  /**
   * @event io:success
   * @description This event is fired by YUI.io when a transaction is complete, and
   * the HTTP status resolves to HTTP2xx.
   * @type Event Custom
   */
   E_SUCCESS = 'io:success',

  /**
   * @event io:failure
   * @description This event is fired by YUI.io when a transaction is complete, and
   * the HTTP status resolves to HTTP4xx, 5xx and above.
   * @type Event Custom
   */
   E_FAILURE = 'io:failure',

  /**
   * @event io:end
   * @description This event signifies the end of the transaction lifecycle.  The
   * transaction transport is destroyed.
   * @type Event Custom
   */
   E_END = 'io:end',

   //--------------------------------------
   //  Properties
   //--------------------------------------
  /**
   * @description A transaction counter that increments for each transaction.
   *
   * @property transactionId
   * @private
   * @static
   * @type int
   */
   transactionId = 0,

  /**
   * @description Object of default HTTP headers to be initialized and sent
   * for all transactions.
   *
   * @property _headers
   * @private
   * @static
   * @type object
   */
   _headers = {
       'X-Requested-With' : 'XMLHttpRequest'
   },

  /**
   * @description Object that stores timeout values for any transaction with
   * a defined "timeout" configuration property.
   *
   * @property _timeout
   * @private
   * @static
   * @type object
   */
   _timeout = {},

   // Window reference
   w = Y.config.win;

   //--------------------------------------
   //  Methods
   //--------------------------------------
  /**
   * @description Method for requesting a transaction. _io() is implemented as
   * yui.io().  Each transaction may include a configuration object.  Its
   * properties are:
   *
   * method: HTTP method verb (e.g., GET or POST). If this property is not
   *         not defined, the default value will be GET.
   *
   * data: This is the name-value string that will be sent as the transaction
   *       data.  If the request is HTTP GET, the data become part of
   *       querystring. If HTTP POST, the data are sent in the message body.
   *
   * xdr: Defines the transport to be used for cross-domain requests.  By
   *      setting this property, the transaction will use the specified
   *      transport instead of XMLHttpRequest.
   *      The properties are:
   *      {
   *        use: Specify the transport to be used: 'flash' and 'native'
   *        dataType: Set the value to 'XML' if that is the expected
   *                  response content type.
   *      }
   *
   *
   * form: This is a defined object used to process HTML form as data.  The
   *       properties are:
   *       {
   *         id: Node object or id of HTML form.
   *         useDisabled: Boolean value to allow disabled HTML form field
   *                      values to be sent as part of the data.
   *       }
   *
   * on: This is a defined object used to create and handle specific
   *     events during a transaction lifecycle.  These events will fire in
   *     addition to the global io events. The events are:
   *     start - This event is fired when a request is sent to a resource.
   *     complete - This event fires when the transaction is complete.
   *     success - This event fires when the response status resolves to
   *               HTTP 2xx.
   *     failure - This event fires when the response status resolves to
   *               HTTP 4xx, 5xx; and, for all transaction exceptions,
   *               including aborted transactions and transaction timeouts.
   *     end -  This even is fired at the conclusion of the transaction
   *            lifecycle, after a success or failure resolution.
   *
   *     The properties are:
   *     {
   *       start: function(id, arguments){},
   *       complete: function(id, responseobject, arguments){},
   *       success: function(id, responseobject, arguments){},
   *       failure: function(id, responseobject, arguments){},
   *       end: function(id, arguments){}
   *     }
   *     Each property can reference a function or be written as an
   *     inline function.
   *
   * sync: To enable synchronous transactions, set the configuration property
   *       "sync" to true; the default behavior is false.  Synchronous
   *       transactions are limited to same-domain requests only.
   *
   * context: Object reference for all defined transaction event handlers
   *          when it is implemented as a method of a base object. Defining
   *          "context" will set the reference of "this," used in the
   *          event handlers, to the context value.  In the case where
   *          different event handlers all have different contexts,
   *          use Y.bind() to set the execution context, bypassing this
   *          configuration.
   *
   * headers: This is a defined object of client headers, as many as.
   *          desired for the transaction.  The object pattern is:
   *          { 'header': 'value' }.
   *
   * timeout: This value, defined as milliseconds, is a time threshold for the
   *          transaction. When this threshold is reached, and the transaction's
   *          Complete event has not yet fired, the transaction will be aborted.
   *
   * arguments: Object, array, string, or number passed to all registered
   *            event handlers.  This value is available as the second
   *            argument in the "start" and "abort" event handlers; and, it is
   *            the third argument in the "complete", "success", and "failure"
   *            event handlers.
   *
   * @method _io
   * @private
   * @static
   * @param {string} uri - qualified path to transaction resource.
   * @param {object} c - configuration object for the transaction.
   * @param {number} i - transaction id, if already set.
   * @return object
   */
   function _io(uri, c, i) {
       var f, o, d, m, r, s, oD,
           u = uri;
           c = Y.Object(c);
           o = _create(c.xdr || c.form, i);
           m = c.method ? c.method = c.method.toUpperCase() : c.method = 'GET';
           s = c.sync;
           oD = c.data;

       //To serialize an object into a key-value string, add the
       //QueryString module in the YUI instance's 'use' method.
       if (Y.Lang.isObject(c.data)) {
           c.data = Y.QueryString.stringify(c.data);
           Y.log('Configuration property "data" is an object. The serialized value is: ' + c.data, 'info', 'io');
       }

       if (c.form) {
           if (c.form.upload) {
               return Y.io._upload(o, uri, c);
           }
           else {
               f = Y.io._serialize(c.form, c.data);
               if (m === 'POST' || m === 'PUT') {
                   c.data = f;
               }
               else if (m === 'GET') {
                   uri = _concat(uri, f);
               }
           }
       }
       else if (c.data && m === 'GET') {
           uri = _concat(uri, c.data);
           Y.log('HTTP GET with configuration data.  The querystring is: ' + uri, 'info', 'io');
       }

       if (o.t) {
           return Y.io.xdr(uri, o, c);
       }

       if (!s) {
           o.c.onreadystatechange = function() { _readyState(o, c); };
       }

       try {
           o.c.open(m, uri, s ? false : true);
           // Will work only in browsers that implement the
           // Cross-Origin Resource Sharing draft.
           if (c.xdr && c.xdr.credentials) {
               o.c.withCredentials = true;
           }
       }
       catch(a) {
           if (c.xdr) {
               // This exception is usually thrown by browsers
               // that do not support native XDR transactions.
               return _resend(o, u, c, oD);
           }
       }

       if (c.data && m === 'POST') {
           c.headers = Y.merge({ 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8' }, c.headers);
       }

       _setHeaders(o.c, c.headers);
       _ioStart(o.id, c);
       try {
           // Using "null" with HTTP POST will  result in a request
           // with no Content-Length header defined.
           o.c.send(c.data || '');
           if (s) {
               d = o.c;
               r = c.arguments ? { id: o.id, arguments: c.arguments } : { id: o.id };
               r = Y.mix(r, d, false, ['status', 'statusText', 'responseText', 'responseXML']);
               r.getAllResponseHeaders = function() { return d.getAllResponseHeaders(); };
               r.getResponseHeader = function(h) { return d.getResponseHeader(h); };

               _ioComplete(o, c);
               _handleResponse(o, c);

               return r;
           }
       }
       catch(b) {
           if (c.xdr) {
               // This exception is usually thrown by browsers
               // that do not support native XDR transactions.
               return _resend(o, u, c, oD);
           }
       }

       // If config.timeout is defined, and the request is standard XHR,
       // initialize timeout polling.
       if (c.timeout) {
           _startTimeout(o, c.timeout);
           Y.log('Configuration timeout set to: ' + c.timeout, 'info', 'io');
       }

       return {
           id: o.id,
           abort: function() {
               return o.c ? _ioCancel(o, 'abort') : false;
           },
           isInProgress: function() {
               return o.c ? o.c.readyState !== 4 && o.c.readyState !== 0 : false;
           }
       }
   }

  /**
   * @description Method for creating and subscribing transaction events.
   *
   * @method _tE
   * @private
   * @static
   * @param {string} e - event to be published
   * @param {object} c - configuration data subset for event subscription.
   *
   * @return void
   */
   function _tE(e, c) {
       var eT = new Y.EventTarget().publish('transaction:' + e),
           a = c.arguments,
           cT = c.context || Y;

       a ? eT.on(c.on[e], cT, a) : eT.on(c.on[e], cT);

       return eT;
   }

  /**
   * @description Fires event "io:start" and creates, fires a
   * transaction-specific start event, if config.on.start is
   * defined.
   *
   * @method _ioStart
   * @private
   * @static
   * @param {number} id - transaction id
   * @param {object} c - configuration object for the transaction.
   *
   * @return void
   */
   function _ioStart(id, c) {
       var a = c.arguments;
           // Set default value of argument c, property "on" to Object if
           // the property is null or undefined.
           c.on = c.on || {};

       a ? Y.fire(E_START, id, a) : Y.fire(E_START, id);
       if (c.on.start) {
           _tE('start', c).fire(id);
       }
   }


  /**
   * @description Fires event "io:complete" and creates, fires a
   * transaction-specific "complete" event, if config.on.complete is
   * defined.
   *
   * @method _ioComplete
   * @private
   * @static
   * @param {object} o - transaction object.
   * @param {object} c - configuration object for the transaction.
   *
   * @return void
   */
   function _ioComplete(o, c) {
       var r = o.e ? { status: 0, statusText: o.e } : o.c,
           a = c.arguments;
           // Set default value of argument c, property "on" to Object if
           // the property is null or undefined.
           c.on = c.on || {};

       a ? Y.fire(E_COMPLETE, o.id, r, a) : Y.fire(E_COMPLETE, o.id, r);
       if (c.on.complete) {
           _tE('complete', c).fire(o.id, r);
       }
   }

  /**
   * @description Fires event "io:success" and creates, fires a
   * transaction-specific "success" event, if config.on.success is
   * defined.
   *
   * @method _ioSuccess
   * @private
   * @static
   * @param {object} o - transaction object.
   * @param {object} c - configuration object for the transaction.
   *
   * @return void
   */
   function _ioSuccess(o, c) {
       var a = c.arguments;
           // Set default value of argument c, property "on" to Object if
           // the property is null or undefined.
           c.on = c.on || {};

       a ? Y.fire(E_SUCCESS, o.id, o.c, a) : Y.fire(E_SUCCESS, o.id, o.c);
       if (c.on.success) {
           _tE('success', c).fire(o.id, o.c);
       }

       _ioEnd(o, c);
   }

  /**
   * @description Fires event "io:failure" and creates, fires a
   * transaction-specific "failure" event, if config.on.failure is
   * defined.
   *
   * @method _ioFailure
   * @private
   * @static
   * @param {object} o - transaction object.
   * @param {object} c - configuration object for the transaction.
   *
   * @return void
   */
   function _ioFailure(o, c) {
       var r = o.e ? { status: 0, statusText: o.e } : o.c,
           a = c.arguments;
           // Set default value of argument c, property "on" to Object if
           // the property is null or undefined.
           c.on = c.on || {};

       a ? Y.fire(E_FAILURE, o.id, r, a) : Y.fire(E_FAILURE, o.id, r);
       if (c.on.failure) {
           _tE('failure', c).fire(o.id, r);
       }

       _ioEnd(o, c);
   }

  /**
   * @description Fires event "io:end" and creates, fires a
   * transaction-specific "end" event, if config.on.end is
   * defined.
   *
   * @method _ioEnd
   * @private
   * @static
   * @param {object} o - transaction object.
   * @param {object} c - configuration object for the transaction.
   *
   * @return void
   */
   function _ioEnd(o, c) {
       var a = c.arguments;
           // Set default value of argument c, property "on" to Object if
           // the property is null or undefined.
           c.on = c.on || {};

       a ? Y.fire(E_END, o.id, a) : Y.fire(E_END, o.id);
       if (c.on.end) {
           _tE('end', c).fire(o.id);
       }

       _destroy(o);
   }

  /**
   * @description Terminates a transaction due to an explicit abort or
   * timeout.
   *
   * @method _ioCancel
   * @private
   * @static
   * @param {object} o - Transaction object generated by _create().
   * @param {string} s - Identifies timed out or aborted transaction.
   *
   * @return void
   */
   function _ioCancel(o, s) {
       if (o && o.c) {
           o.e = s;
           o.c.abort();
       }
   }

  /**
   * @description Resends an XDR transaction, using the Flash tranport,
   * if the native transport fails.
   *
   * @method _resend
   * @private
   * @static

   * @param {object} o - Transaction object generated by _create().
   * @param {string} uri - qualified path to transaction resource.
   * @param {object} c - configuration object for the transaction.
   *
   * @return void
   */
   function _resend(o, uri, c, d) {
       var id = parseInt(o.id);

       _destroy(o);
       c.xdr.use = 'flash';
       // If the original request included serialized form data,
       // it must be reset to prevent duplication.
       c.form && d ? c.data = d : c.data = null;

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

  /**
   * @description Method that increments _transactionId for each transaction.
   *
   * @method _id
   * @private
   * @static
   * @return int
   */
   function _id() {
       var id = transactionId;

       transactionId++;

       return id;
   }

  /**
   * @description Method that creates a unique transaction object for each
   * request.
   *
   * @method _create
   * @private
   * @static
   * @param {number} c - configuration object subset to determine if
   *                     the transaction is an XDR or file upload,
   *                     requiring an alternate transport.
   * @param {number} i - transaction id
   * @return object
   */
   function _create(c, i) {
       var o = {};
           o.id = Y.Lang.isNumber(i) ? i : _id();
           c = c || {};

       if (!c.use && !c.upload) {
           o.c = _xhr();
       }
       else if (c.use) {
           if (c.use === 'native') {
               if (w.XDomainRequest) {
                   o.c = new XDomainRequest();
                   o.t = c.use;
               }
               else {
                   o.c = _xhr();
               }
           }
           else {
               o.c = Y.io._transport[c.use];
               o.t = c.use;
           }
           // Remove the custom header when making cross-domain
           // requests to avoid unintended pre-flight requests
           // or access control conflicts.
           delete _headers['X-Requested-With'];
       }
       else {
           o.c = {};
       }

       return o;
   };

  /**
   * @description Method that creates the XMLHttpRequest transport
   *
   * @method _xhr
   * @private
   * @static
   * @return object
   */
   function _xhr() {
       return w.XMLHttpRequest ? new XMLHttpRequest() : new ActiveXObject('Microsoft.XMLHTTP');
   }

  /**
   * @description Method that concatenates string data for HTTP GET transactions.
   *
   * @method _concat
   * @private
   * @static
   * @param {string} s - URI or root data.
   * @param {string} d - data to be concatenated onto URI.
   * @return int
   */
   function _concat(s, d) {
       s += ((s.indexOf('?') == -1) ? '?' : '&') + d;
       return s;
   }

  /**
   * @description Method that stores default client headers for all transactions.
   * If a label is passed with no value argument, the header will be deleted.
   *
   * @method _setHeader
   * @private
   * @static
   * @param {string} l - HTTP header
   * @param {string} v - HTTP header value
   * @return int
   */
   function _setHeader(l, v) {
       if (v) {
           _headers[l] = v;
       }
       else {
           delete _headers[l];
       }
   }

  /**
   * @description Method that sets all HTTP headers to be sent in a transaction.
   *
   * @method _setHeaders
   * @private
   * @static
   * @param {object} o - XHR instance for the specific transaction.
   * @param {object} h - HTTP headers for the specific transaction, as defined
   *                     in the configuration object passed to YUI.io().
   * @return void
   */
   function _setHeaders(o, h) {
       var p;
           h = h || {};

       for (p in _headers) {
           if (_headers.hasOwnProperty(p)) {
               if (h[p]) {
                   // Configuration headers will supersede io preset headers,
                   // if headers match.
                   break;
               }
               else {
                   h[p] = _headers[p];
               }
           }
       }

       for (p in h) {
           if (h.hasOwnProperty(p)) {
               o.setRequestHeader(p, h[p]);
           }
       }
   }

  /**
   * @description Starts timeout count if the configuration object
   * has a defined timeout property.
   *
   * @method _startTimeout
   * @private
   * @static
   * @param {object} o - Transaction object generated by _create().
   * @param {object} t - Timeout in milliseconds.
   * @return void
   */
   function _startTimeout(o, t) {
       _timeout[o.id] = w.setTimeout(function() { _ioCancel(o, 'timeout'); }, t);
   }

  /**
   * @description Clears the timeout interval started by _startTimeout().
   *
   * @method _clearTimeout
   * @private
   * @static
   * @param {number} id - Transaction id.
   * @return void
   */
   function _clearTimeout(id) {
       w.clearTimeout(_timeout[id]);
       delete _timeout[id];
   }

  /**
   * @description Event handler bound to onreadystatechange.
   *
   * @method _readyState
   * @private
   * @static
   * @param {object} o - Transaction object generated by _create().
   * @param {object} c - Configuration object passed to YUI.io().
   * @return void
   */
   function _readyState(o, c) {
       if (o.c.readyState === 4) {
           if (c.timeout) {
               _clearTimeout(o.id);
           }

           w.setTimeout(
               function() {
                   _ioComplete(o, c);
                   _handleResponse(o, c);
               }, 0);
       }
   }

  /**
   * @description Method that determines if a transaction response qualifies
   * as success or failure, based on the response HTTP status code, and
   * fires the appropriate success or failure events.
   *
   * @method _handleResponse
   * @private
   * @static
   * @param {object} o - Transaction object generated by _create().
   * @param {object} c - Configuration object passed to io().
   * @return void
   */
   function _handleResponse(o, c) {
       var status;

       try{
           if (o.c.status && o.c.status !== 0) {
               status = o.c.status;
           }
           else {
               status = 0;
           }
       }
       catch(e) {
           status = 0;
       }

       // IE reports HTTP 204 as HTTP 1223.
       if (status >= 200 && status < 300 || status === 1223) {
           _ioSuccess(o, c);
       }
       else {
           _ioFailure(o, c);
       }
   }

   function _destroy(o) {
       // IE, when using XMLHttpRequest as an ActiveX Object, will throw
       // a "Type Mismatch" error if the event handler is set to "null".
       if (w.XMLHttpRequest) {
           if (o.c) {
               o.c.onreadystatechange = null;
           }
       }

       o.c = null;
       o = null;
   }

   _io.start = _ioStart;
   _io.complete = _ioComplete;
   _io.success = _ioSuccess;
   _io.failure = _ioFailure;
   _io.end = _ioEnd;
   _io._id = _id;
   _io._timeout = _timeout;

   //--------------------------------------
   //  Begin public interface definition
   //--------------------------------------
  /**
   * @description Method that stores default client headers for all transactions.
   * If a label is passed with no value argument, the header will be deleted.
   * This is the interface for _setHeader().
   *
   * @method header
   * @public
   * @static
   * @param {string} l - HTTP header
   * @param {string} v - HTTP header value
   * @return int
   */
   _io.header = _setHeader;

  /**
   * @description Method for requesting a transaction. This
   * is the interface for _io().
   *
   * @method io
   * @public
   * @static
   * @param {string} uri - qualified path to transaction resource.
   * @param {object} c - configuration object for the transaction.
   * @return object
   */
   Y.io = _io;
   Y.io.http = _io;