diff options
Diffstat (limited to 'storage/mozIStorageAsyncConnection.idl')
| -rw-r--r-- | storage/mozIStorageAsyncConnection.idl | 336 |
1 files changed, 336 insertions, 0 deletions
diff --git a/storage/mozIStorageAsyncConnection.idl b/storage/mozIStorageAsyncConnection.idl new file mode 100644 index 0000000000..6c05385007 --- /dev/null +++ b/storage/mozIStorageAsyncConnection.idl @@ -0,0 +1,336 @@ +/* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +interface mozIStorageCompletionCallback; +interface mozIStorageFunction; +interface mozIStorageProgressHandler; +interface mozIStorageBaseStatement; +interface mozIStorageStatement; +interface mozIStorageAsyncStatement; +interface mozIStorageStatementCallback; +interface mozIStoragePendingStatement; +interface nsIFile; + +/** + * mozIStorageAsyncConnection represents an asynchronous database + * connection attached to a specific file or to an in-memory data + * storage. It is the primary interface for interacting with a + * database from the main thread, including creating prepared + * statements, executing SQL, and examining database errors. + */ +[scriptable, uuid(8bfd34d5-4ddf-4e4b-89dd-9b14f33534c6)] +interface mozIStorageAsyncConnection : nsISupports { + /** + * Transaction behavior constants. + */ + const int32_t TRANSACTION_DEFAULT = -1; + const int32_t TRANSACTION_DEFERRED = 0; + const int32_t TRANSACTION_IMMEDIATE = 1; + const int32_t TRANSACTION_EXCLUSIVE = 2; + + /** + * The default behavior for all transactions run on this connection. Defaults + * to `TRANSACTION_DEFERRED`, and can be overridden for individual + * transactions. + */ + attribute int32_t defaultTransactionType; + + /** + * The maximum number of bound parameters for statements executed on this + * connection. If your statement has more params than this limit, you'll + * need to chunk them into multiple statements. See `PlacesUtils.chunkArray` + * and its callers in Places for examples of how to do this, or read on for + * an overview. + * + * Keep in mind that the variable limit is for the _total_ number of + * parameters, including ones bound by name (using the `:VVV`, `@VVV`, or + * `?VVV` syntax) and index (`?` and `?NNN`). + * + * This means, when chunking: + * + * - If you're binding 1 param per 1 value per chunk (for example, if you + * have a list of GUIDs and a clause like `WHERE guid IN (?, ?, ?, ...)`, + * your chunk length is just `variableLimit`. + * - If you're binding 1 param per 1 value per chunk, but using that + * param in multiple positions in the query (for example, `WHERE url_hash + * IN (hash(?1), hash(?2), ...) AND url IN (?1, ?2, ...)`), you can use the + * `?NNN` syntax with a chunk length of `variableLimit`. + * - If you're binding N params per 1 value per chunk (for example, if you + * have a list of items with GUIDs and parent GUIDs, and you want to bind + * both), your chunk length is `variableLimit / N`, since you're binding + * two params for each element. + * - If you're binding K params per L values per chunk, plus M fixed ones + * (for example, `WHERE parentGuid = :parentGuid AND guid IN (?, ?, ...)`), + * your chunk length is `variableLimit - M`, to ensure there's space for the + * fixed variables. + * + * If you bind more params than this limit, `create{Async}Statement` will + * fail with a "too many SQL variables" error. + */ + readonly attribute int32_t variableLimit; + + /** + * Returns true if a transaction is active on this connection. + * + * Note that this is true if a transaction is active on the connection, + * regardless of how it was opened. There are several ways to open one: + * + * 1. Explicitly calling `beginTransaction` on a `mozIStorageConnection`. + * 2. Calling `executeSimpleSQL("BEGIN")` or + * `createStatement("BEGIN").execute()` on a `mozIStorageConnection`. + * 3. Executing an async statement, like + * `createAsyncStatement("BEGIN").executeAsync(...)`. This is what + * `Sqlite.sys.mjs` does under the hood. + * + * Because of this, it's important *not* to use this attribute to decide + * whether to *commit* the active transaction, because the caller that opened + * it may not expect that. This is why both `mozStorageTransaction` and + * `Sqlite.sys.mjs` use an internal variable (`mHasTransaction` for the former; + * `_hasInProgressTransaction` for the latter) to check if their transaction + * is already in progress, instead of just checking this attribute before + * committing. Otherwise, mozStorage might accidentally commit (or roll back!) + * a transaction started by `Sqlite.sys.mjs`, and vice versa. + */ + readonly attribute boolean transactionInProgress; + + /** + * Close this database connection, allowing all pending statements + * to complete first. + * + * @param aCallback [optional] + * A callback that will be notified when the close is completed, + * with the following arguments: + * - status: the status of the call + * - value: |null| + * + * @throws NS_ERROR_NOT_SAME_THREAD + * If called on a thread other than the one that opened it. The + * callback will not be dispatched. + * @throws NS_ERROR_NOT_INITIALIZED + * If called on a connection that has already been closed or was + * never properly opened. The callback will still be dispatched + * to the main thread despite the returned error. + * @note If this call should fail, the callback won't be invoked. + */ + void asyncClose([optional] in mozIStorageCompletionCallback aCallback); + + /** + * Forcibly closes a database connection synchronously. + * This should only be used when it's required to close and replace the + * database synchronously to return control to the consumer, for example in + * case of a detected corruption on database opening. + * Since this spins the events loop, it should be used only in very particular + * and rare situations, or it may cause unexpected consequences (crashes). + * + * @throws NS_ERROR_NOT_SAME_THREAD + * If called on a thread other than the one that opened it. + */ + [noscript] void spinningSynchronousClose(); + + /** + * Clone a database and make the clone read only if needed. + * SQL Functions and attached on-disk databases are applied to the new clone. + * + * @param aReadOnly + * If true, the returned database should be put into read-only mode. + * + * @param aCallback + * A callback that will be notified when the operation is complete, + * with the following arguments: + * - status: the status of the operation + * - value: in case of success, an intance of + * mozIStorageAsyncConnection cloned from this one. + * + * @throws NS_ERROR_NOT_SAME_THREAD + * If is called on a thread other than the one that opened it. + * @throws NS_ERROR_UNEXPECTED + * If this connection is a memory database. + * + * @note If your connection is already read-only, you will get a read-only + * clone. + * @note The resulting connection will implement `mozIStorageConnection`, but + * all synchronous methods will throw if called from the main thread. + * @note Due to a bug in SQLite, if you use the shared cache + * (see mozIStorageService), you end up with the same privileges as the + * first connection opened regardless of what is specified in aReadOnly. + * @note The following pragmas are copied over to a read-only clone: + * - cache_size + * - temp_store + * The following pragmas are copied over to a writeable clone: + * - cache_size + * - temp_store + * - foreign_keys + * - journal_size_limit + * - synchronous + * - wal_autocheckpoint + * All SQL functions are copied over to read-only and writeable clones. + * Additionally, all temporary tables, triggers, and views, as well as + * any indexes on temporary tables, are copied over to writeable clones. + * For temporary tables, only the schemas are copied, not their + * contents. + */ + void asyncClone(in boolean aReadOnly, + in mozIStorageCompletionCallback aCallback); + + /** + * The current database nsIFile. Null if the database + * connection refers to an in-memory database. + */ + readonly attribute nsIFile databaseFile; + + /** + * Causes any pending database operation to abort and return at the first + * opportunity. + * @note this cannot be used on mozIStorageConnection unless the connection is + * explicitly marked as `interruptible`. For more details, please + * refer to CONNECTION_INTERRUPTIBLE in mozIStorageService. + * @note operations that are nearly complete may still be able to complete. + * @throws if used on an unsupported connection type, or a closed connection. + */ + void interrupt(); + + /** + * Vacuum the main database plus all the attached one. + * If the database is in auto_vacuum = INCREMENTAL mode, this executes an + * incremental_vacuum, otherwise it will always execute a full vacuum. + * + * While it's possible to invoke this method directly, it's suggested, when + * possible, to use the VacuumManager instead. + * That means registering your component for the "vacuum-participant" XPCOM + * category, and implement the mozIStorageVacuumParticipant interface. + * + * @param [aCallback] Completion callback invoked once the operation is + * complete. + * @param [aUseIncremental] When set to true, this will try to convert the + * main schema to auto_vacuum = INCREMENTAL mode, if it's not set yet. + * When set to false, it will try to set auto_vacuum = NONE. + * Note a full vacuum will be executed if the auto_vacuum mode must be + * changed, otherwise an incremental vacuum will happen if the database + * is already in INCREMENTAL mode. + * @param [aSetPageSize] This can be used to change the database page_size, a + * full vacuum will be executed to persist the change. If the page + * size is already correct, or you pass 0, this will be a no-op. + * @throws If it's not possible to start the async vacuum operation, note in + * this case the callback won't be invoked. + * @note Vacuum will fail inside a transaction, or if there is an ongoing + * read statement. + */ + void asyncVacuum( + [optional] in mozIStorageCompletionCallback aCallback, + [optional] in boolean aUseIncremental, + [optional] in long aSetPageSize + ); + + ////////////////////////////////////////////////////////////////////////////// + //// Statement creation + + /** + * Create an asynchronous statement for the given SQL. An + * asynchronous statement can only be used to dispatch asynchronous + * requests to the asynchronous execution thread and cannot be used + * to take any synchronous actions on the database. + * + * The expression may use ? to indicate sequential numbered arguments, + * ?1, ?2 etc. to indicate specific numbered arguments or :name and + * $var to indicate named arguments. + * + * @param aSQLStatement + * The SQL statement to execute. + * @return a new mozIStorageAsyncStatement + * @note The statement is created lazily on first execution. + */ + mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement); + + /** + * Execute an array of statements created with this connection using + * any currently bound parameters. When the array contains multiple + * statements, the execution is wrapped in a single + * transaction. These statements can be reused immediately, and + * reset does not need to be called. + * + * @param aStatements + * The array of statements to execute asynchronously, in the order they + * are given in the array. + * @param aCallback [optional] + * The callback object that will be notified of progress, errors, and + * completion. + * @return an object that can be used to cancel the statements execution. + * + * @note If you have any custom defined functions, they must be + * re-entrant since they can be called on multiple threads. + */ + mozIStoragePendingStatement executeAsync( + in Array<mozIStorageBaseStatement> aStatements, + [optional] in mozIStorageStatementCallback aCallback + ); + + /** + * Execute asynchronously an SQL expression, expecting no arguments. + * + * @param aSQLStatement + * The SQL statement to execute + * @param aCallback [optional] + * The callback object that will be notified of progress, errors, and + * completion. + * @return an object that can be used to cancel the statement execution. + */ + mozIStoragePendingStatement executeSimpleSQLAsync( + in AUTF8String aSQLStatement, + [optional] in mozIStorageStatementCallback aCallback); + + ////////////////////////////////////////////////////////////////////////////// + //// Functions + + /** + * Create a new SQL function. If you use your connection on multiple threads, + * your function needs to be threadsafe, or it should only be called on one + * thread. + * + * @param aFunctionName + * The name of function to create, as seen in SQL. + * @param aNumArguments + * The number of arguments the function takes. Pass -1 for + * variable-argument functions. + * @param aFunction + * The instance of mozIStorageFunction, which implements the function + * in question. + */ + void createFunction(in AUTF8String aFunctionName, + in long aNumArguments, + in mozIStorageFunction aFunction); + + /** + * Delete custom SQL function. + * + * @param aFunctionName + * The name of function to remove. + */ + void removeFunction(in AUTF8String aFunctionName); + + /** + * Sets a progress handler. Only one handler can be registered at a time. + * If you need more than one, you need to chain them yourself. This progress + * handler should be threadsafe if you use this connection object on more than + * one thread. + * + * @param aGranularity + * The number of SQL virtual machine steps between progress handler + * callbacks. + * @param aHandler + * The instance of mozIStorageProgressHandler. + * @return previous registered handler. + */ + mozIStorageProgressHandler setProgressHandler(in int32_t aGranularity, + in mozIStorageProgressHandler aHandler); + + /** + * Remove a progress handler. + * + * @return previous registered handler. + */ + mozIStorageProgressHandler removeProgressHandler(); +}; |