1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 * Implements low-overhead integration between components of the application.
7 * This may have different uses depending on the component, including:
9 * - Providing product-specific implementations registered at startup.
10 * - Using alternative implementations during unit tests.
11 * - Allowing add-ons to change specific behaviors.
13 * Components may define one or more integration points, each defined by a
14 * root integration object whose properties and methods are the public interface
15 * and default implementation of the integration point. For example:
17 * const DownloadIntegration = {
18 * getTemporaryDirectory() {
22 * getTemporaryFile(name) {
23 * return this.getTemporaryDirectory() + name;
27 * Other parts of the application may register overrides for some or all of the
28 * defined properties and methods. The component defining the integration point
29 * does not have to be loaded at this stage, because the name of the integration
30 * point is the only information required. For example, if the integration point
31 * is called "downloads":
33 * Integration.downloads.register(base => ({
34 * getTemporaryDirectory() {
35 * return base.getTemporaryDirectory.call(this) + "subdir/";
39 * When the component defining the integration point needs to call a method on
40 * the integration object, instead of using it directly the component would use
41 * the "getCombined" method to retrieve an object that includes all overrides.
44 * let combined = Integration.downloads.getCombined(DownloadIntegration);
45 * Assert.is(combined.getTemporaryFile("file"), "/tmp/subdir/file");
47 * Overrides can be registered at startup or at any later time, so each call to
48 * "getCombined" may return a different object. The simplest way to create a
49 * reference to the combined object that stays updated to the latest version is
50 * to define the root object in a JSM and use the "defineModuleGetter" method.
52 * *** Registration ***
54 * Since the interface is not declared formally, the registrations can happen
55 * at startup without loading the component, so they do not affect performance.
57 * Hovever, this module does not provide a startup registry, this means that the
58 * code that registers and implements the override must be loaded at startup.
60 * If performance for the override code is a concern, you can take advantage of
61 * the fact that the function used to create the override is called lazily, and
62 * include only a stub loader for the final code in an existing startup module.
64 * The registration of overrides should be repeated for each process where the
65 * relevant integration methods will be called.
67 * *** Accessing base methods and properties ***
69 * Overrides are included in the prototype chain of the combined object in the
70 * same order they were registered, where the first is closest to the root.
72 * When defining overrides, you do not need to set the "__proto__" property of
73 * the objects you create, because their properties and methods are moved to a
74 * new object with the correct prototype. If you do, however, you can call base
75 * properties and methods using the "super" keyword. For example:
77 * Integration.downloads.register(base => ({
79 * getTemporaryDirectory() {
80 * return super.getTemporaryDirectory() + "subdir/";
84 * *** State handling ***
86 * Storing state directly on the combined integration object using the "this"
87 * reference is not recommended. When a new integration is registered, own
88 * properties stored on the old combined object are copied to the new combined
89 * object using a shallow copy, but the "this" reference for new invocations
90 * of the methods will be different.
92 * If the root object defines a property that always points to the same object,
93 * for example a "state" property, you can safely use it across registrations.
95 * Integration overrides provided by restartless add-ons should not use the
96 * "this" reference to store state, to avoid conflicts with other add-ons.
98 * *** Interaction with XPCOM ***
100 * Providing the combined object as an argument to any XPCOM method will
101 * generate a console error message, and will throw an exception where possible.
102 * For example, you cannot register observers directly on the combined object.
103 * This helps preventing mistakes due to the fact that the combined object
104 * reference changes when new integration overrides are registered.
109 var EXPORTED_SYMBOLS = ["Integration"];
111 const { XPCOMUtils } = ChromeUtils.import(
112 "resource://gre/modules/XPCOMUtils.jsm"
116 * Maps integration point names to IntegrationPoint objects.
118 const gIntegrationPoints = new Map();
121 * This Proxy object creates IntegrationPoint objects using their name as key.
122 * The objects will be the same for the duration of the process. For example:
124 * Integration.downloads.register(...);
125 * Integration["addon-provided-integration"].register(...);
127 var Integration = new Proxy(
131 let integrationPoint = gIntegrationPoints.get(name);
132 if (!integrationPoint) {
133 integrationPoint = new IntegrationPoint();
134 gIntegrationPoints.set(name, integrationPoint);
136 return integrationPoint;
142 * Individual integration point for which overrides can be registered.
144 var IntegrationPoint = function() {
145 this._overrideFns = new Set();
147 // eslint-disable-next-line mozilla/use-chromeutils-generateqi
149 let ex = new Components.Exception(
150 "Integration objects should not be used with XPCOM because" +
151 " they change when new overrides are registered.",
152 Cr.NS_ERROR_NO_INTERFACE
160 this.IntegrationPoint.prototype = {
162 * Ordered set of registered functions defining integration overrides.
167 * Combined integration object. When this reference changes, properties
168 * defined directly on this object are copied to the new object.
170 * Initially, the only property of this object is a "QueryInterface" method
171 * that throws an exception, to prevent misuse as a permanent XPCOM listener.
176 * Indicates whether the integration object is current based on the list of
177 * registered integration overrides.
179 _combinedIsCurrent: false,
182 * Registers new overrides for the integration methods. For example:
184 * Integration.nameOfIntegrationPoint.register(base => ({
185 * asyncMethod: Task.async(function* () {
186 * return yield base.asyncMethod.apply(this, arguments);
191 * Function returning an object defining the methods that should be
192 * overridden. Its only parameter is an object that contains the base
193 * implementation of all the available methods.
195 * @note The override function is called every time the list of registered
196 * override functions changes. Thus, it should not have any side
197 * effects or do any other initialization.
199 register(overrideFn) {
200 this._overrideFns.add(overrideFn);
201 this._combinedIsCurrent = false;
205 * Removes a previously registered integration override.
207 * Overrides don't usually need to be unregistered, unless they are added by a
208 * restartless add-on, in which case they should be unregistered when the
209 * add-on is disabled or uninstalled.
212 * This must be the same function object passed to "register".
214 unregister(overrideFn) {
215 this._overrideFns.delete(overrideFn);
216 this._combinedIsCurrent = false;
220 * Retrieves the dynamically generated object implementing the integration
221 * methods. Platform-specific code and add-ons can override methods of this
222 * object using the "register" method.
225 if (this._combinedIsCurrent) {
226 return this._combined;
229 // In addition to enumerating all the registered integration overrides in
230 // order, we want to keep any state that was previously stored in the
231 // combined object using the "this" reference in integration methods.
232 let overrideFnArray = [...this._overrideFns, () => this._combined];
235 for (let overrideFn of overrideFnArray) {
237 // Obtain a new set of methods from the next override function in the
238 // list, specifying the current combined object as the base argument.
239 let override = overrideFn(combined);
241 // Retrieve a list of property descriptors from the returned object, and
242 // use them to build a new combined object whose prototype points to the
243 // previous combined object.
244 let descriptors = {};
245 for (let name of Object.getOwnPropertyNames(override)) {
246 descriptors[name] = Object.getOwnPropertyDescriptor(override, name);
248 combined = Object.create(combined, descriptors);
250 // Any error will result in the current override being skipped.
255 this._combinedIsCurrent = true;
256 return (this._combined = combined);
260 * Defines a getter to retrieve the dynamically generated object implementing
261 * the integration methods, loading the root implementation lazily from the
262 * specified JSM module. For example:
264 * Integration.test.defineModuleGetter(this, "TestIntegration",
265 * "resource://testing-common/TestIntegration.jsm");
267 * @param targetObject
268 * The object on which the lazy getter will be defined.
270 * The name of the getter to define.
272 * The URL used to obtain the module.
273 * @param symbol [optional]
274 * The name of the symbol exported by the module. This can be omitted
275 * if the name of the exported symbol is equal to the getter name.
277 defineModuleGetter(targetObject, name, moduleUrl, symbol) {
278 let moduleHolder = {};
279 XPCOMUtils.defineLazyModuleGetter(moduleHolder, name, moduleUrl, symbol);
280 Object.defineProperty(targetObject, name, {
281 get: () => this.getCombined(moduleHolder[name]),