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.finishMigration()

Cleans up references to migrators and nsIProfileInstance instances.

MigrationUtils.getLegacyMigrationEntrypoint(entrypoint)

Translates an entrypoint string into the proper numeric value for the legacy FX_MIGRATION_ENTRY_POINT histogram.

Arguments

  • entrypoint (string) – The entrypoint to translate from MIGRATION_ENTRYPOINTS.

Returns

number – The numeric value for the legacy FX_MIGRATION_ENTRY_POINT histogram.

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 null otherwise.

If null is returned, either no data can be imported for the given migrator, or aMigratorKey is invalid (e.g. ie on mac, or mosaic everywhere). This method should be used rather than direct getService for future compatibility (see bug 718280).

Arguments

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

Returns

MigratorBase – 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.

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.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. On mac, this may just focus the wizard if it’s already running, in which case aOpener and aOptions are ignored.

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 the new content-modal migration dialog is enabled and 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 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 (The first option is hardcoded to be the most common browser for the OS we run on. See migration.xhtml).

  • 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.