lib/yui/3.5.1/build/jsonp/jsonp-debug.js

   1 /*
   2 YUI 3.5.1 (build 22)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('jsonp', function(Y) {
   8
   9 var isFunction = Y.Lang.isFunction;
  10
  11 /**
  12  * <p>Provides a JSONPRequest class for repeated JSONP calls, and a convenience
  13  * method Y.jsonp(url, callback) to instantiate and send a JSONP request.</p>
  14  *
  15  * <p>Both the constructor as well as the convenience function take two
  16  * parameters: a url string and a callback.</p>
  17  *
  18  * <p>The url provided must include the placeholder string
  19  * &quot;{callback}&quot; which will be replaced by a dynamically
  20  * generated routing function to pass the data to your callback function.
  21  * An example url might look like
  22  * &quot;http://example.com/service?callback={callback}&quot;.</p>
  23  *
  24  * <p>The second parameter can be a callback function that accepts the JSON
  25  * payload as its argument, or a configuration object supporting the keys:</p>
  26  * <ul>
  27  *   <li>on - map of callback subscribers
  28  *      <ul>
  29  *         <li>success - function handler for successful transmission</li>
  30  *         <li>failure - function handler for failed transmission</li>
  31  *         <li>timeout - function handler for transactions that timeout</li>
  32  *      </ul>
  33  *  </li>
  34  *  <li>format  - override function for inserting the proxy name in the url</li>
  35  *  <li>timeout - the number of milliseconds to wait before giving up</li>
  36  *  <li>context - becomes <code>this</code> in the callbacks</li>
  37  *  <li>args    - array of subsequent parameters to pass to the callbacks</li>
  38  *  <li>allowCache - use the same proxy name for all requests? (boolean)</li>
  39  * </ul>
  40  *
  41  * @module jsonp
  42  * @class JSONPRequest
  43  * @constructor
  44  * @param url {String} the url of the JSONP service
  45  * @param callback {Object|Function} the default callback configuration or
  46  *                                   success handler
  47  */
  48 function JSONPRequest() {
  49     this._init.apply(this, arguments);
  50 }
  51
  52 JSONPRequest.prototype = {
  53     /**
  54      * Set up the success and failure handlers and the regex pattern used
  55      * to insert the temporary callback name in the url.
  56      *
  57      * @method _init
  58      * @param url {String} the url of the JSONP service
  59      * @param callback {Object|Function} Optional success callback or config
  60      *                  object containing success and failure functions and
  61      *                  the url regex.
  62      * @protected
  63      */
  64     _init : function (url, callback) {
  65         this.url = url;
  66
  67         /**
  68          * Map of the number of requests currently pending responses per
  69          * generated proxy.  Used to ensure the proxy is not flushed if the
  70          * request times out and there is a timeout handler and success
  71          * handler, and used by connections configured to allowCache to make
  72          * sure the proxy isn't deleted until the last response has returned.
  73          *
  74          * @property _requests
  75          * @private
  76          * @type {Object}
  77          */
  78         this._requests = {};
  79
  80         /**
  81          * Map of the number of timeouts received from the destination url
  82          * by generated proxy.  Used to ensure the proxy is not flushed if the
  83          * request times out and there is a timeout handler and success
  84          * handler, and used by connections configured to allowCache to make
  85          * sure the proxy isn't deleted until the last response has returned.
  86          *
  87          * @property _timeouts
  88          * @private
  89          * @type {Object}
  90          */
  91         this._timeouts = {};
  92
  93         // Accept a function, an object, or nothing
  94         callback = (isFunction(callback)) ?
  95             { on: { success: callback } } :
  96             callback || {};
  97
  98         var subs = callback.on || {};
  99
 100         if (!subs.success) {
 101             subs.success = this._defaultCallback(url, callback);
 102         }
 103
 104         // Apply defaults and store
 105         this._config = Y.merge({
 106                 context: this,
 107                 args   : [],
 108                 format : this._format,
 109                 allowCache: false
 110             }, callback, { on: subs });
 111     },
 112
 113     /**
 114      * Override this method to provide logic to default the success callback if
 115      * it is not provided at construction.  This is overridden by jsonp-url to
 116      * parse the callback from the url string.
 117      *
 118      * @method _defaultCallback
 119      * @param url {String} the url passed at construction
 120      * @param config {Object} (optional) the config object passed at
 121      *                        construction
 122      * @return {Function}
 123      */
 124     _defaultCallback: function () {},
 125
 126     /**
 127      * Issues the JSONP request.
 128      *
 129      * @method send
 130      * @param args* {any} any additional arguments to pass to the url formatter
 131      *              beyond the base url and the proxy function name
 132      * @chainable
 133      */
 134     send : function () {
 135         var self   = this,
 136             args   = Y.Array(arguments, 0, true),
 137             config = self._config,
 138             proxy  = self._proxy || Y.guid(),
 139             url;
 140
 141         // TODO: support allowCache as time value
 142         if (config.allowCache) {
 143             self._proxy = proxy;
 144         }
 145
 146         if (self._requests[proxy] === undefined) {
 147             self._requests[proxy] = 0;
 148         }
 149         if (self._timeouts[proxy] === undefined) {
 150             self._timeouts[proxy] = 0;
 151         }
 152         self._requests[proxy]++;
 153
 154         Y.log('sending ' + proxy);
 155
 156         args.unshift(self.url, 'YUI.Env.JSONP.' + proxy);
 157         url = config.format.apply(self, args);
 158
 159         if (!config.on.success) {
 160             Y.log("No success handler defined.  Aborting JSONP request.", "warn", "jsonp");
 161             return self;
 162         }
 163
 164         function wrap(fn, isTimeout) {
 165             return (isFunction(fn)) ?
 166                 function (data) {
 167                     var execute = true,
 168                         counter = '_requests';
 169
 170                     //if (config.allowCache) {
 171                         // A lot of wrangling to make sure timeouts result in
 172                         // fewer success callbacks, but the proxy is properly
 173                         // cleaned up.
 174                         if (isTimeout) {
 175                             ++self._timeouts[proxy];
 176                             --self._requests[proxy];
 177                             Y.log(proxy + ' timed out - timeouts(' + self._timeouts[proxy] + ') requests(' + self._requests[proxy] + ')');
 178                         } else {
 179                             if (!self._requests[proxy]) {
 180                                 execute = false;
 181                                 counter = '_timeouts';
 182                             }
 183                             --self[counter][proxy];
 184                             Y.log(proxy + ' response received - timeouts(' + self._timeouts[proxy] + ') requests(' + self._requests[proxy] + ')');
 185                         }
 186                     //}
 187
 188                     if (!self._requests[proxy] && !self._timeouts[proxy]) {
 189                         Y.log('deleting ' + proxy);
 190                         delete YUI.Env.JSONP[proxy];
 191                     }
 192
 193                     if (execute) {
 194                         fn.apply(config.context, [data].concat(config.args));
 195                     }
 196                 } :
 197                 null;
 198         }
 199
 200         // Temporary un-sandboxed function alias
 201         // TODO: queuing
 202         YUI.Env.JSONP[proxy] = wrap(config.on.success);
 203
 204         Y.Get.script(url, {
 205             onFailure : wrap(config.on.failure),
 206             onTimeout : wrap(config.on.timeout, true),
 207             timeout   : config.timeout,
 208             charset   : config.charset,
 209             attributes: config.attributes
 210         });
 211
 212         return self;
 213     },
 214
 215     /**
 216      * Default url formatter.  Looks for callback= in the url and appends it
 217      * if not present.  The supplied proxy name will be assigned to the query
 218      * param.  Override this method by passing a function as the
 219      * &quot;format&quot; property in the config object to the constructor.
 220      *
 221      * @method _format
 222      * @param url { String } the original url
 223      * @param proxy {String} the function name that will be used as a proxy to
 224      *      the configured callback methods.
 225      * @param args* {any} additional args passed to send()
 226      * @return {String} fully qualified JSONP url
 227      * @protected
 228      */
 229     _format: function (url, proxy) {
 230         return url.replace(/\{callback\}/, proxy);
 231     }
 232 };
 233
 234 Y.JSONPRequest = JSONPRequest;
 235
 236 /**
 237  *
 238  * @method jsonp
 239  * @param url {String} the url of the JSONP service with the {callback}
 240  *          placeholder where the callback function name typically goes.
 241  * @param c {Function|Object} Callback function accepting the JSON payload
 242  *          as its argument, or a configuration object (see above).
 243  * @param args* {any} additional arguments to pass to send()
 244  * @return {JSONPRequest}
 245  * @static
 246  * @for YUI
 247  */
 248 Y.jsonp = function (url,c) {
 249     var req = new Y.JSONPRequest(url,c);
 250     return req.send.apply(req, Y.Array(arguments, 2, true));
 251 };
 252
 253 if (!YUI.Env.JSONP) {
 254     YUI.Env.JSONP = {};
 255 }
 256
 257
 258 }, '3.5.1' ,{requires:['get','oop']});