Debian Codegraph @

closure-library/closure/goog/module/loader.js

raw
1 // Copyright 2006 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 *
17 * @fileoverview This class supports the dynamic loading of compiled
18 * javascript modules at runtime, as described in the designdoc.
19 *
20 * <http://go/js_modules_design>
21 *
22 */
23
24 goog.provide('goog.module.Loader');
25
26 goog.require('goog.Timer');
27 goog.require('goog.array');
28 goog.require('goog.asserts');
29 goog.require('goog.dom');
30 goog.require('goog.dom.TagName');
31 /** @suppress {extraRequire} */
32 goog.require('goog.module');
33 goog.require('goog.object');
34
35
36
37 /**
38 * The dynamic loading functionality is defined as a class. The class
39 * will be used as singleton. There is, however, a two step
40 * initialization procedure because parameters need to be passed to
41 * the goog.module.Loader instance.
42 *
43 * @constructor
44 * @final
45 */
46 goog.module.Loader = function() {
47 /**
48 * Map of module name/array of {symbol name, callback} pairs that are pending
49 * to be loaded.
50 * @type {Object}
51 * @private
52 */
53 this.pending_ = {};
54
55 /**
56 * Provides associative access to each module and the symbols of each module
57 * that have already been loaded (one lookup for the module, another lookup
58 * on the module for the symbol).
59 * @type {Object}
60 * @private
61 */
62 this.modules_ = {};
63
64 /**
65 * Map of module name to module url. Used to avoid fetching the same URL
66 * twice by keeping track of in-flight URLs.
67 * Note: this allows two modules to be bundled into the same file.
68 * @type {Object}
69 * @private
70 */
71 this.pendingModuleUrls_ = {};
72
73 /**
74 * The base url to load modules from. This property will be set in init().
75 * @type {?string}
76 * @private
77 */
78 this.urlBase_ = null;
79
80 /**
81 * Array of modules that have been requested before init() was called.
82 * If require() is called before init() was called, the required
83 * modules can obviously not yet be loaded, because their URL is
84 * unknown. The modules that are requested before init() are
85 * therefore stored in this array, and they are loaded at init()
86 * time.
87 * @type {Array<string>}
88 * @private
89 */
90 this.pendingBeforeInit_ = [];
91 };
92 goog.addSingletonGetter(goog.module.Loader);
93
94
95 /**
96 * Wrapper of goog.module.Loader.require() for use in modules.
97 * See method goog.module.Loader.require() for
98 * explanation of params.
99 *
100 * @param {string} module The name of the module. Usually, the value
101 * is defined as a constant whose name starts with MOD_.
102 * @param {number|string} symbol The ID of the symbol. Usually, the value is
103 * defined as a constant whose name starts with SYM_.
104 * @param {Function} callback This function will be called with the
105 * resolved symbol as the argument once the module is loaded.
106 */
107 goog.module.Loader.require = function(module, symbol, callback) {
108 goog.module.Loader.getInstance().require(module, symbol, callback);
109 };
110
111
112 /**
113 * Wrapper of goog.module.Loader.provide() for use in modules
114 * See method goog.module.Loader.provide() for explanation of params.
115 *
116 * @param {string} module The name of the module. Cf. parameter module
117 * of method require().
118 * @param {number|string=} opt_symbol The symbol being defined, or nothing
119 * when all symbols of the module are defined. Cf. parameter symbol of
120 * method require().
121 * @param {Object=} opt_object The object bound to the symbol, or nothing when
122 * all symbols of the module are defined.
123 */
124 goog.module.Loader.provide = function(module, opt_symbol, opt_object) {
125 goog.module.Loader.getInstance().provide(module, opt_symbol, opt_object);
126 };
127
128
129 /**
130 * Wrapper of init() so that we only need to export this single
131 * identifier instead of three. See method goog.module.Loader.init() for
132 * explanation of param.
133 *
134 * @param {string} urlBase The URL of the base library.
135 * @param {Function=} opt_urlFunction Function that creates the URL for the
136 * module file. It will be passed the base URL for module files and the
137 * module name and should return the fully-formed URL to the module file to
138 * load.
139 */
140 goog.module.Loader.init = function(urlBase, opt_urlFunction) {
141 goog.module.Loader.getInstance().init(urlBase, opt_urlFunction);
142 };
143
144
145 /**
146 * Produces a function that delegates all its arguments to a
147 * dynamically loaded function. This is used to export dynamically
148 * loaded functions.
149 *
150 * @param {string} module The module to load from.
151 * @param {number|string} symbol The ID of the symbol to load from the module.
152 * This symbol must resolve to a function.
153 * @return {!Function} A function that forwards all its arguments to
154 * the dynamically loaded function specified by module and symbol.
155 */
156 goog.module.Loader.loaderCall = function(module, symbol) {
157 return function() {
158 var args = arguments;
159 goog.module.Loader.require(
160 module, symbol, function(f) { f.apply(null, args); });
161 };
162 };
163
164
165 /**
166 * Creates a full URL to the compiled module code given a base URL and a
167 * module name. By default it's urlBase + '_' + module + '.js'.
168 * @param {string} urlBase URL to the module files.
169 * @param {string} module Module name.
170 * @return {string} The full url to the module binary.
171 * @private
172 */
173 goog.module.Loader.prototype.getModuleUrl_ = function(urlBase, module) {
174 return urlBase + '_' + module + '.js';
175 };
176
177
178 /**
179 * The globally exported name of the load callback. Matches the
180 * definition in the js_module_binary() BUILD rule.
181 * @type {string}
182 */
183 goog.module.Loader.LOAD_CALLBACK = '__gjsload__';
184
185
186 /**
187 * Loads the module by evaluating the javascript text in the current
188 * scope. Uncompiled, base identifiers are visible in the global scope;
189 * when compiled they are visible in the closure of the anonymous
190 * namespace. Notice that this cannot be replaced by the global eval,
191 * because the global eval isn't in the scope of the anonymous
192 * namespace function that the jscompiled code lives in.
193 *
194 * @param {string} t_ The javascript text to evaluate. IMPORTANT: The
195 * name of the identifier is chosen so that it isn't compiled and
196 * hence cannot shadow compiled identifiers in the surrounding scope.
197 * @private
198 */
199 goog.module.Loader.loaderEval_ = function(t_) {
200 eval(t_);
201 };
202
203
204 /**
205 * Initializes the Loader to be fully functional. Also executes load
206 * requests that were received before initialization. Must be called
207 * exactly once, with the URL of the base library. Module URLs are
208 * derived from the URL of the base library by inserting the module
209 * name, preceded by a period, before the .js prefix of the base URL.
210 *
211 * @param {string} baseUrl The URL of the base library.
212 * @param {Function=} opt_urlFunction Function that creates the URL for the
213 * module file. It will be passed the base URL for module files and the
214 * module name and should return the fully-formed URL to the module file to
215 * load.
216 */
217 goog.module.Loader.prototype.init = function(baseUrl, opt_urlFunction) {
218 // For the use by the module wrappers, loaderEval_ is exported to
219 // the page. Note that, despite the name, this is not part of the
220 // API, so it is here and not in api_app.js. Cf. BUILD. Note this is
221 // done before the first load requests are sent.
222 goog.exportSymbol(
223 goog.module.Loader.LOAD_CALLBACK, goog.module.Loader.loaderEval_);
224
225 this.urlBase_ = baseUrl.replace(/\.js$/, '');
226 if (opt_urlFunction) {
227 this.getModuleUrl_ = opt_urlFunction;
228 }
229
230 goog.array.forEach(
231 this.pendingBeforeInit_, function(module) { this.load_(module); }, this);
232 goog.array.clear(this.pendingBeforeInit_);
233 };
234
235
236 /**
237 * Requests the loading of a symbol from a module. When the module is
238 * loaded, the requested symbol will be passed as argument to the
239 * function callback.
240 *
241 * @param {string} module The name of the module. Usually, the value
242 * is defined as a constant whose name starts with MOD_.
243 * @param {number|string} symbol The ID of the symbol. Usually, the value is
244 * defined as a constant whose name starts with SYM_.
245 * @param {Function} callback This function will be called with the
246 * resolved symbol as the argument once the module is loaded.
247 */
248 goog.module.Loader.prototype.require = function(module, symbol, callback) {
249 var pending = this.pending_;
250 var modules = this.modules_;
251 if (modules[module]) {
252 // already loaded
253 callback(modules[module][symbol]);
254 } else if (pending[module]) {
255 // loading is pending from another require of the same module
256 pending[module].push([symbol, callback]);
257 } else {
258 // not loaded, and not requested
259 pending[module] = [[symbol, callback]]; // Yes, really [[ ]].
260 // Defer loading to initialization if Loader is not yet
261 // initialized, otherwise load the module.
262 if (goog.isString(this.urlBase_)) {
263 this.load_(module);
264 } else {
265 this.pendingBeforeInit_.push(module);
266 }
267 }
268 };
269
270
271 /**
272 * Registers a symbol in a loaded module. When called without symbol,
273 * registers the module to be fully loaded and executes all callbacks
274 * from pending require() callbacks for this module.
275 *
276 * @param {string} module The name of the module. Cf. parameter module
277 * of method require().
278 * @param {number|string=} opt_symbol The symbol being defined, or nothing when
279 * all symbols of the module are defined. Cf. parameter symbol of method
280 * require().
281 * @param {Object=} opt_object The object bound to the symbol, or nothing when
282 * all symbols of the module are defined.
283 */
284 goog.module.Loader.prototype.provide = function(
285 module, opt_symbol, opt_object) {
286 var modules = this.modules_;
287 var pending = this.pending_;
288 if (!modules[module]) {
289 modules[module] = {};
290 }
291 if (opt_object) {
292 // When an object is provided, just register it.
293 modules[module][opt_symbol] = opt_object;
294 } else if (pending[module]) {
295 // When no object is provided, and there are pending require()
296 // callbacks for this module, execute them.
297 for (var i = 0; i < pending[module].length; ++i) {
298 var symbol = pending[module][i][0];
299 var callback = pending[module][i][1];
300 callback(modules[module][symbol]);
301 }
302 delete pending[module];
303 delete this.pendingModuleUrls_[module];
304 }
305 };
306
307
308 /**
309 * Starts to load a module. Assumes that init() was called.
310 *
311 * @param {string} module The name of the module.
312 * @private
313 */
314 goog.module.Loader.prototype.load_ = function(module) {
315 // NOTE(user): If the module request happens inside a click handler
316 // (presumably inside any user event handler, but the onload event
317 // handler is fine), IE will load the script but not execute
318 // it. Thus we break out of the current flow of control before we do
319 // the load. For the record, for IE it would have been enough to
320 // just defer the assignment to src. Safari doesn't execute the
321 // script if the assignment to src happens *after* the script
322 // element is inserted into the DOM.
323 goog.Timer.callOnce(function() {
324 // The module might have been registered in the interim (if fetched as part
325 // of another module fetch because they share the same url)
326 if (this.modules_[module]) {
327 return;
328 }
329
330 goog.asserts.assertString(this.urlBase_);
331 var url = this.getModuleUrl_(this.urlBase_, module);
332
333 // Check if specified URL is already in flight
334 var urlInFlight = goog.object.containsValue(this.pendingModuleUrls_, url);
335 this.pendingModuleUrls_[module] = url;
336 if (urlInFlight) {
337 return;
338 }
339
340 var s = goog.dom.createDom(
341 goog.dom.TagName.SCRIPT, {'type': 'text/javascript', 'src': url});
342 document.body.appendChild(s);
343 }, 0, this);
344 };