Debian Codegraph @

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

raw
1 // Copyright 2008 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 Defines the goog.module.ModuleInfo class.
17 *
18 */
19
20 goog.provide('goog.module.ModuleInfo');
21
22 goog.require('goog.Disposable');
23 goog.require('goog.async.throwException');
24 goog.require('goog.functions');
25 goog.require('goog.html.TrustedResourceUrl');
26 /** @suppress {extraRequire} */
27 goog.require('goog.module');
28 goog.require('goog.module.BaseModule');
29 goog.require('goog.module.ModuleLoadCallback');
30
31 goog.forwardDeclare('goog.loader.AbstractModuleManager.FailureType');
32
33
34
35 /**
36 * A ModuleInfo object is used by the ModuleManager to hold information about a
37 * module of js code that may or may not yet be loaded into the environment.
38 *
39 * @param {Array<string>} deps Ids of the modules that must be loaded before
40 * this one. The ids must be in dependency order (i.e. if the ith module
41 * depends on the jth module, then i > j).
42 * @param {string} id The module's ID.
43 * @constructor
44 * @extends {goog.Disposable}
45 * @final
46 */
47 goog.module.ModuleInfo = function(deps, id) {
48 goog.Disposable.call(this);
49
50 /**
51 * A list of the ids of the modules that must be loaded before this module.
52 * @type {Array<string>}
53 * @private
54 */
55 this.deps_ = deps;
56
57 /**
58 * The module's ID.
59 * @type {string}
60 * @private
61 */
62 this.id_ = id;
63
64 /**
65 * Callbacks to execute once this module is loaded.
66 * @type {Array<goog.module.ModuleLoadCallback>}
67 * @private
68 */
69 this.onloadCallbacks_ = [];
70
71 /**
72 * Callbacks to execute if the module load errors.
73 * @type {Array<goog.module.ModuleLoadCallback>}
74 * @private
75 */
76 this.onErrorCallbacks_ = [];
77
78 /**
79 * Early callbacks to execute once this module is loaded. Called after
80 * module initialization but before regular onload callbacks.
81 * @type {Array<goog.module.ModuleLoadCallback>}
82 * @private
83 */
84 this.earlyOnloadCallbacks_ = [];
85 };
86 goog.inherits(goog.module.ModuleInfo, goog.Disposable);
87
88
89 /**
90 * The uris that can be used to retrieve this module's code.
91 * @type {?Array<!goog.html.TrustedResourceUrl>}
92 * @private
93 */
94 goog.module.ModuleInfo.prototype.uris_ = null;
95
96
97 /**
98 * The constructor to use to instantiate the module object after the module
99 * code is loaded. This must be either goog.module.BaseModule or a subclass of
100 * it.
101 * @type {Function}
102 * @private
103 */
104 goog.module.ModuleInfo.prototype.moduleConstructor_ = goog.module.BaseModule;
105
106
107 /**
108 * The module object. This will be null until the module is loaded.
109 * @type {goog.module.BaseModule?}
110 * @private
111 */
112 goog.module.ModuleInfo.prototype.module_ = null;
113
114
115 /**
116 * Gets the dependencies of this module.
117 * @return {Array<string>} The ids of the modules that this module depends on.
118 */
119 goog.module.ModuleInfo.prototype.getDependencies = function() {
120 return this.deps_;
121 };
122
123
124 /**
125 * Gets the ID of this module.
126 * @return {string} The ID.
127 */
128 goog.module.ModuleInfo.prototype.getId = function() {
129 return this.id_;
130 };
131
132
133 /**
134 * Sets the uris of this module.
135 * @param {!Array<!goog.html.TrustedResourceUrl>} uris Uris for this module's
136 * code.
137 */
138 goog.module.ModuleInfo.prototype.setTrustedUris = function(uris) {
139 this.uris_ = uris;
140 };
141
142
143 /**
144 * Gets the uris of this module.
145 * @return {!Array<!goog.html.TrustedResourceUrl>} Uris for this module's code.
146 */
147 goog.module.ModuleInfo.prototype.getUris = function() {
148 if (!this.uris_) {
149 this.uris_ = [];
150 }
151 return this.uris_;
152 };
153
154
155 /**
156 * Sets the constructor to use to instantiate the module object after the
157 * module code is loaded.
158 * @param {Function} constructor The constructor of a goog.module.BaseModule
159 * subclass.
160 */
161 goog.module.ModuleInfo.prototype.setModuleConstructor = function(constructor) {
162 if (this.moduleConstructor_ === goog.module.BaseModule) {
163 this.moduleConstructor_ = constructor;
164 } else {
165 throw new Error('Cannot set module constructor more than once.');
166 }
167 };
168
169
170 /**
171 * Registers a function that should be called after the module is loaded. These
172 * early callbacks are called after {@link Module#initialize} is called but
173 * before the other callbacks are called.
174 * @param {Function} fn A callback function that takes a single argument which
175 * is the module context.
176 * @param {Object=} opt_handler Optional handler under whose scope to execute
177 * the callback.
178 * @return {!goog.module.ModuleLoadCallback} Reference to the callback
179 * object.
180 */
181 goog.module.ModuleInfo.prototype.registerEarlyCallback = function(
182 fn, opt_handler) {
183 return this.registerCallback_(this.earlyOnloadCallbacks_, fn, opt_handler);
184 };
185
186
187 /**
188 * Registers a function that should be called after the module is loaded.
189 * @param {Function} fn A callback function that takes a single argument which
190 * is the module context.
191 * @param {Object=} opt_handler Optional handler under whose scope to execute
192 * the callback.
193 * @return {!goog.module.ModuleLoadCallback} Reference to the callback
194 * object.
195 */
196 goog.module.ModuleInfo.prototype.registerCallback = function(fn, opt_handler) {
197 return this.registerCallback_(this.onloadCallbacks_, fn, opt_handler);
198 };
199
200
201 /**
202 * Registers a function that should be called if the module load fails.
203 * @param {Function} fn A callback function that takes a single argument which
204 * is the failure type.
205 * @param {Object=} opt_handler Optional handler under whose scope to execute
206 * the callback.
207 * @return {!goog.module.ModuleLoadCallback} Reference to the callback
208 * object.
209 */
210 goog.module.ModuleInfo.prototype.registerErrback = function(fn, opt_handler) {
211 return this.registerCallback_(this.onErrorCallbacks_, fn, opt_handler);
212 };
213
214
215 /**
216 * Registers a function that should be called after the module is loaded.
217 * @param {Array<goog.module.ModuleLoadCallback>} callbacks The array to
218 * add the callback to.
219 * @param {Function} fn A callback function that takes a single argument which
220 * is the module context.
221 * @param {Object=} opt_handler Optional handler under whose scope to execute
222 * the callback.
223 * @return {!goog.module.ModuleLoadCallback} Reference to the callback
224 * object.
225 * @private
226 */
227 goog.module.ModuleInfo.prototype.registerCallback_ = function(
228 callbacks, fn, opt_handler) {
229 var callback = new goog.module.ModuleLoadCallback(fn, opt_handler);
230 callbacks.push(callback);
231 return callback;
232 };
233
234
235 /**
236 * Determines whether the module has been loaded.
237 * @return {boolean} Whether the module has been loaded.
238 */
239 goog.module.ModuleInfo.prototype.isLoaded = function() {
240 return !!this.module_;
241 };
242
243
244 /**
245 * Gets the module.
246 * @return {goog.module.BaseModule?} The module if it has been loaded.
247 * Otherwise, null.
248 */
249 goog.module.ModuleInfo.prototype.getModule = function() {
250 return this.module_;
251 };
252
253
254 /**
255 * Sets this module as loaded.
256 * @param {function() : Object} contextProvider A function that provides the
257 * module context.
258 * @return {boolean} Whether any errors occurred while executing the onload
259 * callbacks.
260 */
261 goog.module.ModuleInfo.prototype.onLoad = function(contextProvider) {
262 // Instantiate and initialize the module object.
263 var module = new this.moduleConstructor_;
264 module.initialize(contextProvider());
265
266 // Keep an internal reference to the module.
267 this.module_ = module;
268
269 // Fire any early callbacks that were waiting for the module to be loaded.
270 var errors =
271 !!this.callCallbacks_(this.earlyOnloadCallbacks_, contextProvider());
272
273 // Fire any callbacks that were waiting for the module to be loaded.
274 errors =
275 errors || !!this.callCallbacks_(this.onloadCallbacks_, contextProvider());
276
277 if (!errors) {
278 // Clear the errbacks.
279 this.onErrorCallbacks_.length = 0;
280 }
281
282 return errors;
283 };
284
285
286 /**
287 * Calls the error callbacks for the module.
288 * @param {goog.loader.AbstractModuleManager.FailureType} cause What caused the
289 * error.
290 */
291 goog.module.ModuleInfo.prototype.onError = function(cause) {
292 var result = this.callCallbacks_(this.onErrorCallbacks_, cause);
293 if (result) {
294 // Throw an exception asynchronously. Do not let the exception leak
295 // up to the caller, or it will blow up the module loading framework.
296 window.setTimeout(
297 goog.functions.error('Module errback failures: ' + result), 0);
298 }
299 this.earlyOnloadCallbacks_.length = 0;
300 this.onloadCallbacks_.length = 0;
301 };
302
303
304 /**
305 * Helper to call the callbacks after module load.
306 * @param {Array<goog.module.ModuleLoadCallback>} callbacks The callbacks
307 * to call and then clear.
308 * @param {*} context The module context.
309 * @return {Array<*>} Any errors encountered while calling the callbacks,
310 * or null if there were no errors.
311 * @private
312 */
313 goog.module.ModuleInfo.prototype.callCallbacks_ = function(callbacks, context) {
314 // NOTE(nicksantos):
315 // In practice, there are two error-handling scenarios:
316 // 1) The callback does some mandatory initialization of the module.
317 // 2) The callback is for completion of some optional UI event.
318 // There's no good way to handle both scenarios.
319 //
320 // Our strategy here is to protect module manager from exceptions, so that
321 // the failure of one module doesn't affect the loading of other modules.
322 // Errors are thrown outside of the current stack frame, so they still
323 // get reported but don't interrupt execution.
324
325 // Call each callback in the order they were registered
326 var errors = [];
327 for (var i = 0; i < callbacks.length; i++) {
328 try {
329 callbacks[i].execute(context);
330 } catch (e) {
331 goog.async.throwException(e);
332 errors.push(e);
333 }
334 }
335
336 // Clear the list of callbacks.
337 callbacks.length = 0;
338 return errors.length ? errors : null;
339 };
340
341
342 /** @override */
343 goog.module.ModuleInfo.prototype.disposeInternal = function() {
344 goog.module.ModuleInfo.superClass_.disposeInternal.call(this);
345 goog.dispose(this.module_);
346 };