MigrationUtils Reference

class MigrationUtils()

The singleton MigrationUtils service. This service is the primary mechanism by which migrations from other browsers to this browser occur. The singleton instance of this class is exported from this module as MigrationUtils.

MigrationUtils.MIGRATION_ENTRYPOINTS

Returns an enum that should be used to record the entrypoint for starting a migration.

MigrationUtils._importQuantities

This is only pseudo-private because some tests and helper functions still expect to be able to directly access it.

MigrationUtils.isStartupMigration

type: boolean

True if we’re in the process of a startup migration.

MigrationUtils.profileStartup

type: nsIProfileStartup|null

In the case of startup migration, this is set to the nsIProfileStartup instance passed to ProfileMigrator’s migrate.

See also

MigrationUtils.canGetPermissionsOnPlatform()

Determines whether or not the underlying platform supports creating native file pickers that can do folder selection, which is a pre-requisite for getting read-access permissions for data from other browsers that we can import from.

Returns:

Promise.<boolean> –

MigrationUtils.finishMigration()

Cleans up references to migrators and nsIProfileInstance instances.

MigrationUtils.getLocalizedString(aKey, aArgs)

Gets localized string corresponding to l10n-id

Arguments:

  • aKey (string) – The key of the id of the localization to retrieve.

  • aArgs (object) – An optional map of arguments to the id.

Returns:

Promise.<string> – A promise that resolves to the retrieved localization.

MigrationUtils.getMigrator(aKey)

Returns the migrator for the given source, if any data is available for this source, or if permissions are required in order to read data from this source. Returns null otherwise.

Arguments:

  • aKey (string) – Internal name of the migration source. See availableMigratorKeys for supported values by OS.

Returns:

Promise.<(MigratorBase|null)> – A profile migrator implementing nsIBrowserProfileMigrator, if it can import any data, null otherwise.

MigrationUtils.getMigratorKeyForDefaultBrowser()

Figure out what is the default browser, and if there is a migrator for it, return that migrator’s internal name.

For the time being, the “internal name” of a migrator is its contract-id trailer (e.g. ie for @mozilla.org/profile/migrator;1?app=browser&type=ie), but it will soon be exposed properly.

Returns:

string –

MigrationUtils.getRowsFromDBWithoutLocks(path, description, selectQuery, testDelayPromise=null)

Get all the rows corresponding to a select query from a database, without requiring a lock on the database. If fetching data fails (because someone else tried to write to the DB at the same time, for example), we will retry the fetch after a 100ms timeout, up to 10 times.

Arguments:

  • path (string) – The file path to the database we want to open.

  • description (string) – A developer-readable string identifying what kind of database we’re trying to open.

  • selectQuery (string) – The SELECT query to use to fetch the rows.

  • testDelayPromise (Promise) – An optional promise to await for after the first loop, used in tests.

Returns:

Promise.<(Array.<object>|Error)> – A promise that resolves to an array of rows. The promise will be rejected if the read/fetch failed even after retrying.

MigrationUtils.insertManyFavicons(favicons)

Iterates through the favicons, sniffs for a mime type, and uses the mime type to properly import the favicon.

Note: You may not want to await on the returned promise, especially if by

doing so there’s risk of interrupting the migration of more critical data (e.g. bookmarks).

Arguments:

  • favicons (Array.<object>) – An array of Objects with these properties: {Uint8Array} faviconData: The binary data of a favicon {nsIURI} uri: The URI of the associated page

MigrationUtils.installExtensionsWrapper(migratorKey, extensionIDs)

Responsible for calling the AddonManager API that ultimately installs the matched add-ons.

Arguments:

  • migratorKey (string) – a migrator key that we pass to AMBrowserExtensionsImport as the “browser identifier” used to match add-ons

  • extensionIDs (Array.<string>) – a list of extension IDs from another browser

Returns:

MigrationUtils.migratorExists(aKey)

Returns true if a migrator is registered with key aKey. No check is made to determine if a profile exists that the migrator can migrate from.

Arguments:

  • aKey (string) – Internal name of the migration source. See availableMigratorKeys for supported values by OS.

Returns:

boolean –

MigrationUtils.showMigrationWizard(aOpener=null, aOptions=null)

Show the migration wizard in about:preferences, or if there is not an existing browser window open, in a new top-level dialog window.

NB: If you add new consumers, please add a migration entry point constant to MIGRATION_ENTRYPOINTS and supply that entrypoint with the entrypoint property in the aOptions argument.

Arguments:

  • aOpener (Window) – optional; the window that asks to open the wizard.

  • aOptions (object) – optional named arguments for the migration wizard.

  • aOptions.entrypoint (string) – migration entry point constant. See MIGRATION_ENTRYPOINTS.

  • aOptions.migratorKey (string) – The key for which migrator to use automatically. This is the key that is exposed as a static getter on the migrator class.

  • aOptions.migrator (MigratorBase) – A migrator instance to use automatically.

  • aOptions.isStartupMigration (boolean) – True if this is a startup migration.

  • aOptions.skipSourceSelection (boolean) – True if the source selection page of the wizard should be skipped.

  • aOptions.profileId (string) – An identifier for the profile to use when migrating.

Returns:

Promise.<undefined> – If an about:preferences tab can be opened, this will resolve when that tab has been switched to. Otherwise, this will resolve just after opening the top-level dialog window.

MigrationUtils.startupMigration(aProfileStartup, aMigratorKey="null", aProfileToMigrate="null")

Show the migration wizard for startup-migration. This should only be called by ProfileMigrator (see ProfileMigrator.js), which implements nsIProfileMigrator. This runs asynchronously if we are running an automigration.

Arguments:

  • aProfileStartup (nsIProfileStartup) – the nsIProfileStartup instance provided to ProfileMigrator.migrate.

  • aMigratorKey (string|null) – If set, the migration wizard will import from the corresponding migrator, bypassing the source-selection page. Otherwise, the source-selection page will be displayed, either with the default browser selected, if it could be detected and if there is a migrator for it, or with the first option selected as a fallback

  • aProfileToMigrate (string|null) – If set, the migration wizard will import from the profile indicated.

Throws:

if aMigratorKey is invalid or if it points to a non-existent source.

MigrationUtils.wrapMigrateFunction(aFunction, aCallback)

Helper for implementing simple asynchronous cases of migration resources’ migrate(aCallback) (see MigratorBase). If your migrate method just waits for some file to be read, for example, and then migrates everything right away, you can wrap the async-function with this helper and not worry about notifying the callback.

Arguments:

  • aFunction (function) – the function that will be called sometime later. If aFunction throws when it’s called, aCallback(false) is called, otherwise aCallback(true) is called.

  • aCallback (function) – the callback function passed to migrate.

Returns:

function – the wrapped function.

Examples:

// For example, instead of writing:
setTimeout(function() {
  try {
    ....
    aCallback(true);
  }
  catch() {
    aCallback(false);
  }
}, 0);

// You may write:
setTimeout(MigrationUtils.wrapMigrateFunction(function() {
  if (importingFromMosaic)
    throw Cr.NS_ERROR_UNEXPECTED;
}, aCallback), 0);

// ... and aCallback will be called with aSuccess=false when importing
// from Mosaic, or with aSuccess=true otherwise.