src/third_party/google_input_tools/third_party/closure_library/closure/goog/net/jsloader.js

   1 // Copyright 2011 The Closure Library Authors. All Rights Reserved.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //      http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS-IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 /**
  16  * @fileoverview A utility to load JavaScript files via DOM script tags.
  17  * Refactored from goog.net.Jsonp. Works cross-domain.
  18  *
  19  */
  20
  21 goog.provide('goog.net.jsloader');
  22 goog.provide('goog.net.jsloader.Error');
  23 goog.provide('goog.net.jsloader.ErrorCode');
  24 goog.provide('goog.net.jsloader.Options');
  25
  26 goog.require('goog.array');
  27 goog.require('goog.async.Deferred');
  28 goog.require('goog.debug.Error');
  29 goog.require('goog.dom');
  30 goog.require('goog.dom.TagName');
  31
  32
  33 /**
  34  * The name of the property of goog.global under which the JavaScript
  35  * verification object is stored by the loaded script.
  36  * @type {string}
  37  * @private
  38  */
  39 goog.net.jsloader.GLOBAL_VERIFY_OBJS_ = 'closure_verification';
  40
  41
  42 /**
  43  * The default length of time, in milliseconds, we are prepared to wait for a
  44  * load request to complete.
  45  * @type {number}
  46  */
  47 goog.net.jsloader.DEFAULT_TIMEOUT = 5000;
  48
  49
  50 /**
  51  * Optional parameters for goog.net.jsloader.send.
  52  * timeout: The length of time, in milliseconds, we are prepared to wait
  53  *     for a load request to complete. Default it 5 seconds.
  54  * document: The HTML document under which to load the JavaScript. Default is
  55  *     the current document.
  56  * cleanupWhenDone: If true clean up the script tag after script completes to
  57  *     load. This is important if you just want to read data from the JavaScript
  58  *     and then throw it away. Default is false.
  59  *
  60  * @typedef {{
  61  *   timeout: (number|undefined),
  62  *   document: (HTMLDocument|undefined),
  63  *   cleanupWhenDone: (boolean|undefined)
  64  * }}
  65  */
  66 goog.net.jsloader.Options;
  67
  68
  69 /**
  70  * Scripts (URIs) waiting to be loaded.
  71  * @type {Array.<string>}
  72  * @private
  73  */
  74 goog.net.jsloader.scriptsToLoad_ = [];
  75
  76
  77 /**
  78  * Loads and evaluates the JavaScript files at the specified URIs, guaranteeing
  79  * the order of script loads.
  80  *
  81  * Because we have to load the scripts in serial (load script 1, exec script 1,
  82  * load script 2, exec script 2, and so on), this will be slower than doing
  83  * the network fetches in parallel.
  84  *
  85  * If you need to load a large number of scripts but dependency order doesn't
  86  * matter, you should just call goog.net.jsloader.load N times.
  87  *
  88  * If you need to load a large number of scripts on the same domain,
  89  * you may want to use goog.module.ModuleLoader.
  90  *
  91  * @param {Array.<string>} uris The URIs to load.
  92  * @param {goog.net.jsloader.Options=} opt_options Optional parameters. See
  93  *     goog.net.jsloader.options documentation for details.
  94  */
  95 goog.net.jsloader.loadMany = function(uris, opt_options) {
  96   // Loading the scripts in serial introduces asynchronosity into the flow.
  97   // Therefore, there are race conditions where client A can kick off the load
  98   // sequence for client B, even though client A's scripts haven't all been
  99   // loaded yet.
 100   //
 101   // To work around this issue, all module loads share a queue.
 102   if (!uris.length) {
 103     return;
 104   }
 105
 106   var isAnotherModuleLoading = goog.net.jsloader.scriptsToLoad_.length;
 107   goog.array.extend(goog.net.jsloader.scriptsToLoad_, uris);
 108   if (isAnotherModuleLoading) {
 109     // jsloader is still loading some other scripts.
 110     // In order to prevent the race condition noted above, we just add
 111     // these URIs to the end of the scripts' queue and return.
 112     return;
 113   }
 114
 115   uris = goog.net.jsloader.scriptsToLoad_;
 116   var popAndLoadNextScript = function() {
 117     var uri = uris.shift();
 118     var deferred = goog.net.jsloader.load(uri, opt_options);
 119     if (uris.length) {
 120       deferred.addBoth(popAndLoadNextScript);
 121     }
 122   };
 123   popAndLoadNextScript();
 124 };
 125
 126
 127 /**
 128  * Loads and evaluates a JavaScript file.
 129  * When the script loads, a user callback is called.
 130  * It is the client's responsibility to verify that the script ran successfully.
 131  *
 132  * @param {string} uri The URI of the JavaScript.
 133  * @param {goog.net.jsloader.Options=} opt_options Optional parameters. See
 134  *     goog.net.jsloader.Options documentation for details.
 135  * @return {!goog.async.Deferred} The deferred result, that may be used to add
 136  *     callbacks and/or cancel the transmission.
 137  *     The error callback will be called with a single goog.net.jsloader.Error
 138  *     parameter.
 139  */
 140 goog.net.jsloader.load = function(uri, opt_options) {
 141   var options = opt_options || {};
 142   var doc = options.document || document;
 143
 144   var script = goog.dom.createElement(goog.dom.TagName.SCRIPT);
 145   var request = {script_: script, timeout_: undefined};
 146   var deferred = new goog.async.Deferred(goog.net.jsloader.cancel_, request);
 147
 148   // Set a timeout.
 149   var timeout = null;
 150   var timeoutDuration = goog.isDefAndNotNull(options.timeout) ?
 151       options.timeout : goog.net.jsloader.DEFAULT_TIMEOUT;
 152   if (timeoutDuration > 0) {
 153     timeout = window.setTimeout(function() {
 154       goog.net.jsloader.cleanup_(script, true);
 155       deferred.errback(new goog.net.jsloader.Error(
 156           goog.net.jsloader.ErrorCode.TIMEOUT,
 157           'Timeout reached for loading script ' + uri));
 158     }, timeoutDuration);
 159     request.timeout_ = timeout;
 160   }
 161
 162   // Hang the user callback to be called when the script completes to load.
 163   // NOTE(user): This callback will be called in IE even upon error. In any
 164   // case it is the client's responsibility to verify that the script ran
 165   // successfully.
 166   script.onload = script.onreadystatechange = function() {
 167     if (!script.readyState || script.readyState == 'loaded' ||
 168         script.readyState == 'complete') {
 169       var removeScriptNode = options.cleanupWhenDone || false;
 170       goog.net.jsloader.cleanup_(script, removeScriptNode, timeout);
 171       deferred.callback(null);
 172     }
 173   };
 174
 175   // Add an error callback.
 176   // NOTE(user): Not supported in IE.
 177   script.onerror = function() {
 178     goog.net.jsloader.cleanup_(script, true, timeout);
 179     deferred.errback(new goog.net.jsloader.Error(
 180         goog.net.jsloader.ErrorCode.LOAD_ERROR,
 181         'Error while loading script ' + uri));
 182   };
 183
 184   // Add the script element to the document.
 185   goog.dom.setProperties(script, {
 186     'type': 'text/javascript',
 187     'charset': 'UTF-8',
 188     // NOTE(user): Safari never loads the script if we don't set
 189     // the src attribute before appending.
 190     'src': uri
 191   });
 192   var scriptParent = goog.net.jsloader.getScriptParentElement_(doc);
 193   scriptParent.appendChild(script);
 194
 195   return deferred;
 196 };
 197
 198
 199 /**
 200  * Loads a JavaScript file and verifies it was evaluated successfully, using a
 201  * verification object.
 202  * The verification object is set by the loaded JavaScript at the end of the
 203  * script.
 204  * We verify this object was set and return its value in the success callback.
 205  * If the object is not defined we trigger an error callback.
 206  *
 207  * @param {string} uri The URI of the JavaScript.
 208  * @param {string} verificationObjName The name of the verification object that
 209  *     the loaded script should set.
 210  * @param {goog.net.jsloader.Options} options Optional parameters. See
 211  *     goog.net.jsloader.Options documentation for details.
 212  * @return {!goog.async.Deferred} The deferred result, that may be used to add
 213  *     callbacks and/or cancel the transmission.
 214  *     The success callback will be called with a single parameter containing
 215  *     the value of the verification object.
 216  *     The error callback will be called with a single goog.net.jsloader.Error
 217  *     parameter.
 218  */
 219 goog.net.jsloader.loadAndVerify = function(uri, verificationObjName, options) {
 220   // Define the global objects variable.
 221   if (!goog.global[goog.net.jsloader.GLOBAL_VERIFY_OBJS_]) {
 222     goog.global[goog.net.jsloader.GLOBAL_VERIFY_OBJS_] = {};
 223   }
 224   var verifyObjs = goog.global[goog.net.jsloader.GLOBAL_VERIFY_OBJS_];
 225
 226   // Verify that the expected object does not exist yet.
 227   if (goog.isDef(verifyObjs[verificationObjName])) {
 228     // TODO(user): Error or reset variable?
 229     return goog.async.Deferred.fail(new goog.net.jsloader.Error(
 230         goog.net.jsloader.ErrorCode.VERIFY_OBJECT_ALREADY_EXISTS,
 231         'Verification object ' + verificationObjName + ' already defined.'));
 232   }
 233
 234   // Send request to load the JavaScript.
 235   var sendDeferred = goog.net.jsloader.load(uri, options);
 236
 237   // Create a deferred object wrapping the send result.
 238   var deferred = new goog.async.Deferred(
 239       goog.bind(sendDeferred.cancel, sendDeferred));
 240
 241   // Call user back with object that was set by the script.
 242   sendDeferred.addCallback(function() {
 243     var result = verifyObjs[verificationObjName];
 244     if (goog.isDef(result)) {
 245       deferred.callback(result);
 246       delete verifyObjs[verificationObjName];
 247     } else {
 248       // Error: script was not loaded properly.
 249       deferred.errback(new goog.net.jsloader.Error(
 250           goog.net.jsloader.ErrorCode.VERIFY_ERROR,
 251           'Script ' + uri + ' loaded, but verification object ' +
 252           verificationObjName + ' was not defined.'));
 253     }
 254   });
 255
 256   // Pass error to new deferred object.
 257   sendDeferred.addErrback(function(error) {
 258     if (goog.isDef(verifyObjs[verificationObjName])) {
 259       delete verifyObjs[verificationObjName];
 260     }
 261     deferred.errback(error);
 262   });
 263
 264   return deferred;
 265 };
 266
 267
 268 /**
 269  * Gets the DOM element under which we should add new script elements.
 270  * How? Take the first head element, and if not found take doc.documentElement,
 271  * which always exists.
 272  *
 273  * @param {!HTMLDocument} doc The relevant document.
 274  * @return {!Element} The script parent element.
 275  * @private
 276  */
 277 goog.net.jsloader.getScriptParentElement_ = function(doc) {
 278   var headElements = doc.getElementsByTagName(goog.dom.TagName.HEAD);
 279   if (!headElements || goog.array.isEmpty(headElements)) {
 280     return doc.documentElement;
 281   } else {
 282     return headElements[0];
 283   }
 284 };
 285
 286
 287 /**
 288  * Cancels a given request.
 289  * @this {{script_: Element, timeout_: number}} The request context.
 290  * @private
 291  */
 292 goog.net.jsloader.cancel_ = function() {
 293   var request = this;
 294   if (request && request.script_) {
 295     var scriptNode = request.script_;
 296     if (scriptNode && scriptNode.tagName == 'SCRIPT') {
 297       goog.net.jsloader.cleanup_(scriptNode, true, request.timeout_);
 298     }
 299   }
 300 };
 301
 302
 303 /**
 304  * Removes the script node and the timeout.
 305  *
 306  * @param {Node} scriptNode The node to be cleaned up.
 307  * @param {boolean} removeScriptNode If true completely remove the script node.
 308  * @param {?number=} opt_timeout The timeout handler to cleanup.
 309  * @private
 310  */
 311 goog.net.jsloader.cleanup_ = function(scriptNode, removeScriptNode,
 312                                       opt_timeout) {
 313   if (goog.isDefAndNotNull(opt_timeout)) {
 314     goog.global.clearTimeout(opt_timeout);
 315   }
 316
 317   scriptNode.onload = goog.nullFunction;
 318   scriptNode.onerror = goog.nullFunction;
 319   scriptNode.onreadystatechange = goog.nullFunction;
 320
 321   // Do this after a delay (removing the script node of a running script can
 322   // confuse older IEs).
 323   if (removeScriptNode) {
 324     window.setTimeout(function() {
 325       goog.dom.removeNode(scriptNode);
 326     }, 0);
 327   }
 328 };
 329
 330
 331 /**
 332  * Possible error codes for jsloader.
 333  * @enum {number}
 334  */
 335 goog.net.jsloader.ErrorCode = {
 336   LOAD_ERROR: 0,
 337   TIMEOUT: 1,
 338   VERIFY_ERROR: 2,
 339   VERIFY_OBJECT_ALREADY_EXISTS: 3
 340 };
 341
 342
 343
 344 /**
 345  * A jsloader error.
 346  *
 347  * @param {goog.net.jsloader.ErrorCode} code The error code.
 348  * @param {string=} opt_message Additional message.
 349  * @constructor
 350  * @extends {goog.debug.Error}
 351  * @final
 352  */
 353 goog.net.jsloader.Error = function(code, opt_message) {
 354   var msg = 'Jsloader error (code #' + code + ')';
 355   if (opt_message) {
 356     msg += ': ' + opt_message;
 357   }
 358   goog.net.jsloader.Error.base(this, 'constructor', msg);
 359
 360   /**
 361    * The code for this error.
 362    *
 363    * @type {goog.net.jsloader.ErrorCode}
 364    */
 365   this.code = code;
 366 };
 367 goog.inherits(goog.net.jsloader.Error, goog.debug.Error);