mozIStorageService

This interface lets you open a mozIStorageConnection to a database file, as well as create backups of an unopened database file. This is the only way to open a database connection.
1.0
28
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

See mozIStorageConnection

Method overview

nsIFile backupDatabaseFile(in nsIFile aDBFile, in AString aBackupFileName, [optional] in nsIFile aBackupParentDirectory);
mozIStorageConnection openDatabase(in nsIFile aDatabaseFile);
mozIStorageConnection openSpecialDatabase(in string aStorageKey);
mozIStorageConnection openUnsharedDatabase(in nsIFile aDatabaseFile);

Methods

Requires Gecko 1.9 (Firefox 3)

backupDatabaseFile()

This method makes a backup of the specified file. The database should not be open, or you should ensure that no database activity is happening when you call this method. The filename provided is only used as a suggestion. If the filename is already taken, attempts will be made to ensure that it is unique. The actual backup file is returned, and the resulting filename can be obtained from that.

nsIFile backupDatabaseFile(
  in nsIFile aDBFile,
  in AString aBackupFileName,
  in nsIFile aBackupParentDirectory Optional
);
Parameters
aDBFile
The database file to back up.
aBackupFileName
The filename to give to the new backup file.
aBackupParentDirectory Optional
The directory to put the backup into. If this is not specified, the backup is placed in the same directory as the original file.
Return value

An nsIFile object representing the newly-created backup file.

openDatabase()

Opens a database connection to the specified file. The specified file is created if it does not already exist. If this method throws NS_ERROR_FILE_CORRUPTED, it's recommended that you call mozIStorageService.backupDatabaseFile() to back up the database so that user data is not lost (although we have no way of recovering this data yet).

Consumers should check mozIStorageConnection.connectionReady to ensure that they can use the database. If this value is false, it is strongly recommended that the database be backed up with mozIStorageConnection.backupDB() so user data is not lost. And then the database can be opened again with the mozIStorageService.openDatabase() method.

Warning: If you have more than one connection to a file, you must use the exact same name for the file each time, including case. The sqlite code uses a simple string comparison to see if there is already a connection. Opening a connection to "Foo.sqlite" and "foo.sqlite" will corrupt your database.

If your database contains virtual tables (for example, for full-text indexes), you must use mozIStorageService.openUnsharedDatabase() to open it, since those tables are not compatible with a shared cache. If you use this method to open a database containing virtual tables, it will think the database is corrupted and throw NS_ERROR_FILE_CORRUPTED.

Note: The connection object returned by this function is not threadsafe. You must use it only from the thread you created it from.

mozIStorageConnection openDatabase(
  in nsIFile aDatabaseFile
);
Parameters
aDatabaseFile
An nsIFile indicating the database file to open.
Return value

A mozIStorageConnection representing the connection to the opened database file.

Exceptions thrown
NS_ERROR_FAILURE
An error occurred attempting to open the database.
NS_ERROR_FILE_CORRUPTED
The database file is corrupted, or contains virtual tables and is not compatible with this method.
NS_ERROR_OUT_OF_MEMORY
Allocating a new storage object failed.

openSpecialDatabase()

Opens a connection to a named special database storage that identifies the type of storage requested.

Note: You should only access the profile database from the main thread since other callers may also be using it.

mozIStorageConnection openSpecialDatabase(
  in string aStorageKey
);
Parameters
aStorageKey
A string key identifying the type of storage requested. Valid values are "profile" and "memory".
Return value

A new mozIStorageConnection providing access to the requested database.

Exceptions thrown
NS_ERROR_INVALID_ARG
If aStorageKey is invalid.

Requires Gecko 1.9 (Firefox 3)

openUnsharedDatabase()

Opens a database connection to the specified file without using a shared cache. If this method throws NS_ERROR_FILE_CORRUPTED, it's recommended that you call mozIStorageService.backupDatabaseFile() to back up the database so that user data is not lost (although we have no way of recovering this data yet).

Each connection uses its own sqlite cache, which is inefficient, so you should use openDatabase() instead of this method unless you need a feature of SQLite that is incompatible with a shared cache, like virtual table and full text indexing support. If cache contention is expected, for instance when operating on a database from multiple threads, using unshared connections may be a performance win.

Warning: If you have more than one connection to a file, you must use the exact same name for the file each time, including case. The sqlite code uses a simple string comparison to see if there is already a connection. Opening a connection to "Foo.sqlite" and "foo.sqlite" will corrupt your database.

Note: The connection object returned by this function is not threadsafe. You must use it only from the thread you created it from.

mozIStorageConnection openUnsharedDatabase(
  in nsIFile aDatabaseFile
);
Parameters
aDatabaseFile
An nsIFile indicating the database file to open.
Return value

A mozIStorageConnection representing the connection to the opened database file.

Exceptions thrown
NS_ERROR_FAILURE
An error occurred attempting to open the database.
NS_ERROR_FILE_CORRUPTED
The database file is corrupted, or contains virtual tables and is not compatible with this method.
NS_ERROR_OUT_OF_MEMORY
Allocating a new storage object failed.

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, madarche, wesj, jswisher, trevorh, tomotaka, sdwilsh, Ancestor, Eff2k5, Arehman4, Dria, Briprowe
 Last updated by: Sheppy,