Migrators Reference¶
MigratorBase class¶
- class MigratorBase()¶
Shared prototype for migrators.
To implement a migrator: 1. Import this module. 2. Create a subclass of MigratorBase for your new migrator. 3. Override the key static getter with a unique identifier for the browser
that this migrator migrates from.
If the migrator supports multiple profiles, override the sourceProfiles Here we default for single-profile migrator.
Implement getResources(aProfile) (see below).
For startup-only migrators, override |startupOnlyMigrator|.
Add the migrator to the MIGRATOR_MODULES structure in MigrationUtils.sys.mjs.
- MigratorBase.enabled¶
Returns true if the migrator is configured to be enabled. This is controlled by the browser.migrate.<BROWSER_KEY>.enabled boolean preference.
- MigratorBase.startupOnlyMigrator¶
OVERRIDE IF AND ONLY IF the migrator is a startup-only migrator (For now, that is just the Firefox migrator, see bug 737381). Default: false.
Startup-only migrators are different in two ways: - they may only be used during startup. - the user-profile is half baked during migration. The folder exists,
but it’s only accessible through MigrationUtils.profileStartup. The migrator can call MigrationUtils.profileStartup.doStartup at any point in order to initialize the profile.
- MigratorBase.brandImage¶
type: string
This method should get overridden to return an icon url of the browser to be imported from. By default, this will just use the default Favicon image.
- MigratorBase.displayNameL10nID¶
type: string
This must be overridden to return a Fluent string ID mapping to the display name for this migrator. These strings should be defined in migrationWizard.ftl.
- MigratorBase.key¶
type: string
This must be overridden to return a simple string identifier for the migrator, for example “firefox”, “chrome”, “opera-gx”. This key is what is used as an identifier when calling MigrationUtils.getMigrator.
- MigratorBase.getLastUsedDate()¶
OVERRIDE in order to provide an estimate of when the last time was that somebody used the browser. It is OK that this is somewhat fuzzy - history may not be available (or be wiped or not present due to e.g. incognito mode).
If not overridden, the promise will resolve to the Unix epoch.
- Returns
Promise.<Date> – A Promise that resolves to the last used date.
- MigratorBase.getMigrateData(aProfile)¶
This method returns a number that is the bitwise OR of all resource types that are available in aProfile. See MigrationUtils.resourceTypes for each resource type.
- Arguments
aProfile (object|string) – The profile from which data may be imported, or an empty string in the case of a single-profile migrator.
- Returns
number –
- MigratorBase.getResources(aProfile)¶
MUST BE OVERRIDDEN.
Returns an array of “migration resources” objects for the given profile, or for the “default” profile, if the migrator does not support multiple profiles.
Each migration resource should provide: - a |type| getter, returning any of the migration resource types (see
MigrationUtils.resourceTypes).
a |migrate| method, taking a single argument, aCallback(bool success), for migrating the data for this resource. It may do its job synchronously or asynchronously. Either way, it must call aCallback(bool aSuccess) when it’s done. In the case of an exception thrown from |migrate|, it’s taken as if aCallback(false) is called.
Note: In the case of a simple asynchronous implementation, you may find MigrationUtils.wrapMigrateFunction handy for handling aCallback easily.
For each migration type listed in MigrationUtils.resourceTypes, multiple migration resources may be provided. This practice is useful when the data for a certain migration type is independently stored in few locations. For example, the mac version of Safari stores its “reading list” bookmarks in a separate property list.
Note that the importation of a particular migration type is reported as successful if _any_ of its resources succeeded to import (that is, called, |aCallback(true)|). However, completion-status for a particular migration type is reported to the UI only once all of its migrators have called aCallback.
NOTE: The returned array should only include resources from which data can be imported. So, for example, before adding a resource for the BOOKMARKS migration type, you should check if you should check that the bookmarks file exists.
- Arguments
aProfile (object|string) – The profile from which data may be imported, or an empty string in the case of a single-profile migrator. In the case of multiple-profiles migrator, it is guaranteed that aProfile is a value returned by the sourceProfiles getter (see above).
- Returns
Promise.<Array.<MigratorResource>>|Array.<MigratorResource> –
- MigratorBase.getSourceProfiles()¶
OVERRIDE IF AND ONLY IF the source supports multiple profiles.
Returns array of profile objects from which data may be imported. The object should have the following keys:
id - a unique string identifier for the profile name - a pretty name to display to the user in the UI
Only profiles from which data can be imported should be listed. Otherwise the behavior of the migration wizard isn’t well-defined.
For a single-profile source (e.g. safari, ie), this returns null, and not an empty array. That is the default implementation.
- Returns
Array.<object>|null –
- MigratorBase.isSourceAvailable()¶
Checks to see if one or more profiles exist for the browser that this migrator migrates from.
- Returns
Promise.<boolean> – True if one or more profiles exists that this migrator can migrate resources from.
- MigratorBase.migrate(aItems, aStartup, aProfile, aProgressCallback)¶
- Arguments
aItems (number) – A bitfield with bits from MigrationUtils.resourceTypes flipped to indicate what types of resources should be migrated.
aStartup (boolean) – True if this migration is occurring during startup.
aProfile (object|string) – The other browser profile that is being migrated from.
aProgressCallback (function|null) – An optional callback that will be fired once a resourceType has finished migrating. The callback will be passed the numeric representation of the resource type.
See also
Chrome and Chrome variant migrators¶
The ChromeProfileMigrator
is subclassed ino order to provide migration capabilities for variants of the Chrome browser.
ChromeProfileMigrator class¶
- class ChromeProfileMigrator()¶
Chrome profile migrator. This can also be used as a parent class for migrators for browsers that are variants of Chrome.
ChromeDevMigrator class¶
- class ChromeDevMigrator()¶
Chrome Dev - Linux only (not available in Mac and Windows)
EdgeProfileMigrator class¶
- class EdgeProfileMigrator()¶
Edge (EdgeHTML) profile migrator
- EdgeProfileMigrator.getSourceProfiles()¶
- Returns
Array|null – Somewhat counterintuitively, this returns: - |null| to indicate “There is only 1 (default) profile” (on win10+) - |[]| to indicate “There are no profiles” (on <=win8.1) which will avoid using this migrator. See MigrationUtils.sys.mjs for slightly more info on how sourceProfiles is used.
FirefoxProfileMigrator class¶
- class FirefoxProfileMigrator()¶
Firefox profile migrator. Currently, this class only does “pave over” migrations, where various parts of an old profile overwrite a new profile. This is distinct from other migrators which attempt to import old profile data into the existing profile.
This migrator is what powers the “Profile Refresh” mechanism.