storage/public/mozIStorageConnection.idl

   1 /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Oracle Corporation code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  *  Oracle Corporation
  19  * Portions created by the Initial Developer are Copyright (C) 2004
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
  24  *   Brett Wilson <brettw@gmail.com>
  25  *   Shawn Wilsher <me@shawnwilsher.com>
  26  *   Lev Serebryakov <lev@serebryakov.spb.ru>
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either the GNU General Public License Version 2 or later (the "GPL"), or
  30  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #include "nsISupports.idl"
  43
  44 interface mozIStorageAggregateFunction;
  45 interface mozIStorageCompletionCallback;
  46 interface mozIStorageFunction;
  47 interface mozIStorageProgressHandler;
  48 interface mozIStorageBaseStatement;
  49 interface mozIStorageStatement;
  50 interface mozIStorageAsyncStatement;
  51 interface mozIStorageStatementCallback;
  52 interface mozIStoragePendingStatement;
  53 interface nsIFile;
  54
  55 /**
  56  * mozIStorageConnection represents a database connection attached to
  57  * a specific file or to the in-memory data storage.  It is the
  58  * primary interface for interacting with a database, including
  59  * creating prepared statements, executing SQL, and examining database
  60  * errors.
  61  *
  62  * @threadsafe
  63  */
  64 [scriptable, uuid(ad035628-4ffb-42ff-a256-0ed9e410b859)]
  65 interface mozIStorageConnection : nsISupports {
  66   /**
  67    * The default size for SQLite database pages used by mozStorage for new
  68    * databases.
  69    * This value must stay in sync with the SQLITE_DEFAULT_PAGE_SIZE define in
  70    * /db/sqlite3/src/Makefile.in
  71    */
  72   const long DEFAULT_PAGE_SIZE = 32768;
  73
  74   /**
  75    * Closes a database connection.  Callers must finalize all statements created
  76    * for this connection prior to calling this method.  It is illegal to use
  77    * call this method if any asynchronous statements have been executed on this
  78    * connection.
  79    *
  80    * @throws NS_ERROR_UNEXPECTED
  81    *         If any statement has been executed asynchronously on this object.
  82    * @throws NS_ERROR_UNEXPECTED
  83    *         If is called on a thread other than the one that opened it.
  84    */
  85   void close();
  86
  87   /**
  88    * Asynchronously closes a database connection, allowing all pending
  89    * asynchronous statements to complete first.
  90    *
  91    * @param aCallback [optional]
  92    *        A callback that will be notified when the close is completed.
  93    *
  94    * @throws NS_ERROR_UNEXPECTED
  95    *         If is called on a thread other than the one that opened it.
  96    */
  97   void asyncClose([optional] in mozIStorageCompletionCallback aCallback);
  98
  99   /**
 100    * Clones a database and makes the clone read only if needed.
 101    *
 102    * @note If your connection is already read-only, you will get a read-only
 103    *       clone.
 104    * @note Due to a bug in SQLite, if you use the shared cache (openDatabase),
 105    *       you end up with the same privileges as the first connection opened
 106    *       regardless of what is specified in aReadOnly.
 107    *
 108    * @throws NS_ERROR_UNEXPECTED
 109    *         If this connection is a memory database.
 110    *
 111    * @param aReadOnly
 112    *        If true, the returned database should be put into read-only mode.
 113    *        Defaults to false.
 114    * @return the cloned database connection.
 115    */
 116   mozIStorageConnection clone([optional] in boolean aReadOnly);
 117
 118   /**
 119    * Indicates if the connection is open and ready to use.  This will be false
 120    * if the connection failed to open, or it has been closed.
 121    */
 122   readonly attribute boolean connectionReady;
 123
 124   /**
 125    * The current database nsIFile.  Null if the database
 126    * connection refers to an in-memory database.
 127    */
 128   readonly attribute nsIFile databaseFile;
 129
 130   /**
 131    * lastInsertRowID returns the row ID from the last INSERT
 132    * operation.
 133    */
 134   readonly attribute long long lastInsertRowID;
 135
 136   /**
 137    * The last error SQLite error code.
 138    */
 139   readonly attribute long lastError;
 140
 141   /**
 142    * The last SQLite error as a string (in english, straight from the
 143    * sqlite library).
 144    */
 145   readonly attribute AUTF8String lastErrorString;
 146
 147   /**
 148    * The schema version of the database.  This should not be used until the
 149    * database is ready.  The schema will be reported as zero if it is not set.
 150    */
 151   attribute long schemaVersion;
 152
 153   //////////////////////////////////////////////////////////////////////////////
 154   //// Statement creation
 155
 156   /**
 157    * Create a mozIStorageStatement for the given SQL expression.  The
 158    * expression may use ? to indicate sequential numbered arguments,
 159    * ?1, ?2 etc. to indicate specific numbered arguments or :name and
 160    * $var to indicate named arguments.
 161    *
 162    * @param aSQLStatement
 163    *        The SQL statement to execute.
 164    * @return a new mozIStorageStatement
 165    */
 166   mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
 167
 168   /**
 169    * Create an asynchronous statement (mozIStorageAsyncStatement) for the given
 170    * SQL expression.  An asynchronous statement can only be used to dispatch
 171    * asynchronous requests to the asynchronous execution thread and cannot be
 172    * used to take any synchronous actions on the database.
 173    *
 174    * The expression may use ? to indicate sequential numbered arguments,
 175    * ?1, ?2 etc. to indicate specific numbered arguments or :name and
 176    * $var to indicate named arguments.
 177    *
 178    * @param aSQLStatement
 179    *        The SQL statement to execute.
 180    * @return a new mozIStorageAsyncStatement
 181    */
 182   mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement);
 183
 184   /**
 185    * Execute a SQL expression, expecting no arguments.
 186    *
 187    * @param aSQLStatement  The SQL statement to execute
 188    */
 189   void executeSimpleSQL(in AUTF8String aSQLStatement);
 190
 191   /**
 192    * Execute an array of queries created with this connection asynchronously
 193    * using any currently bound parameters.  The statements are ran wrapped in a
 194    * transaction.  These statements can be reused immediately, and reset does
 195    * not need to be called.
 196    *
 197    * Note:  If you have any custom defined functions, they must be re-entrant
 198    *        since they can be called on multiple threads.
 199    *
 200    * @param aStatements
 201    *        The array of statements to execute asynchronously, in the order they
 202    *        are given in the array.
 203    * @param aNumStatements
 204    *        The number of statements in aStatements.
 205    * @param aCallback [optional]
 206    *        The callback object that will be notified of progress, errors, and
 207    *        completion.
 208    * @return an object that can be used to cancel the statements execution.
 209    */
 210   mozIStoragePendingStatement executeAsync(
 211     [array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements,
 212     in unsigned long aNumStatements,
 213     [optional] in mozIStorageStatementCallback aCallback
 214   );
 215
 216   /**
 217    * Check if the given table exists.
 218    *
 219    * @param aTableName
 220    *        The table to check
 221    * @return TRUE if table exists, FALSE otherwise.
 222    */
 223   boolean tableExists(in AUTF8String aTableName);
 224
 225   /**
 226    * Check if the given index exists.
 227    *
 228    * @param aIndexName   The index to check
 229    * @return TRUE if the index exists, FALSE otherwise.
 230    */
 231   boolean indexExists(in AUTF8String aIndexName);
 232
 233   //////////////////////////////////////////////////////////////////////////////
 234   //// Transactions
 235
 236   /**
 237    * Returns true if a transaction is active on this connection.
 238    */
 239   readonly attribute boolean transactionInProgress;
 240
 241   /**
 242    * Begin a new transaction.  sqlite default transactions are deferred.
 243    * If a transaction is active, throws an error.
 244    */
 245   void beginTransaction();
 246
 247   /**
 248    * Begins a new transaction with the given type.
 249    */
 250   const PRInt32 TRANSACTION_DEFERRED = 0;
 251   const PRInt32 TRANSACTION_IMMEDIATE = 1;
 252   const PRInt32 TRANSACTION_EXCLUSIVE = 2;
 253   void beginTransactionAs(in PRInt32 transactionType);
 254
 255   /**
 256    * Commits the current transaction.  If no transaction is active,
 257    * @throws NS_ERROR_UNEXPECTED.
 258    * @throws NS_ERROR_NOT_INITIALIZED.
 259    */
 260   void commitTransaction();
 261
 262   /**
 263    * Rolls back the current transaction.  If no transaction is active,
 264    * @throws NS_ERROR_UNEXPECTED.
 265    * @throws NS_ERROR_NOT_INITIALIZED.
 266    */
 267   void rollbackTransaction();
 268
 269   //////////////////////////////////////////////////////////////////////////////
 270   //// Tables
 271
 272   /**
 273    * Create the table with the given name and schema.
 274    *
 275    * If the table already exists, NS_ERROR_FAILURE is thrown.
 276    * (XXX at some point in the future it will check if the schema is
 277    * the same as what is specified, but that doesn't happen currently.)
 278    *
 279    * @param aTableName
 280    *        The table name to be created, consisting of [A-Za-z0-9_], and
 281    *        beginning with a letter.
 282    * @param aTableSchema
 283    *        The schema of the table; what would normally go between the parens
 284    *        in a CREATE TABLE statement: e.g., "foo  INTEGER, bar STRING".
 285    *
 286    * @throws NS_ERROR_FAILURE
 287    *         If the table already exists or could not be created for any other
 288    *         reason.
 289    */
 290   void createTable(in string aTableName,
 291                    in string aTableSchema);
 292
 293   //////////////////////////////////////////////////////////////////////////////
 294   //// Functions
 295
 296   /**
 297    * Create a new SQL function.  If you use your connection on multiple threads,
 298    * your function needs to be threadsafe, or it should only be called on one
 299    * thread.
 300    *
 301    * @param aFunctionName
 302    *        The name of function to create, as seen in SQL.
 303    * @param aNumArguments
 304    *        The number of arguments the function takes. Pass -1 for
 305    *        variable-argument functions.
 306    * @param aFunction
 307    *        The instance of mozIStorageFunction, which implements the function
 308    *        in question.
 309    */
 310   void createFunction(in AUTF8String aFunctionName,
 311                       in long aNumArguments,
 312                       in mozIStorageFunction aFunction);
 313
 314   /**
 315    * Create a new SQL aggregate function.  If you use your connection on
 316    * multiple threads, your function needs to be threadsafe, or it should only
 317    * be called on one thread.
 318    *
 319    * @param aFunctionName
 320    *        The name of aggregate function to create, as seen in SQL.
 321    * @param aNumArguments
 322    *        The number of arguments the function takes. Pass -1 for
 323    *        variable-argument functions.
 324    * @param aFunction
 325    *        The instance of mozIStorageAggreagteFunction, which implements the
 326    *        function in question.
 327    */
 328   void createAggregateFunction(in AUTF8String aFunctionName,
 329                                in long aNumArguments,
 330                                in mozIStorageAggregateFunction aFunction);
 331   /**
 332    * Delete custom SQL function (simple or aggregate one).
 333    *
 334    * @param aFunctionName
 335    *        The name of function to remove.
 336    */
 337   void removeFunction(in AUTF8String aFunctionName);
 338
 339   /**
 340    * Sets a progress handler. Only one handler can be registered at a time.
 341    * If you need more than one, you need to chain them yourself.  This progress
 342    * handler should be threadsafe if you use this connection object on more than
 343    * one thread.
 344    *
 345    * @param aGranularity
 346    *        The number of SQL virtual machine steps between progress handler
 347    *        callbacks.
 348    * @param aHandler
 349    *        The instance of mozIStorageProgressHandler.
 350    * @return previous registered handler.
 351    */
 352   mozIStorageProgressHandler setProgressHandler(in PRInt32 aGranularity,
 353                                                 in mozIStorageProgressHandler aHandler);
 354
 355   /**
 356    * Remove a progress handler.
 357    *
 358    * @return previous registered handler.
 359    */
 360   mozIStorageProgressHandler removeProgressHandler();
 361
 362   /**
 363    * Controls SQLITE_FCNTL_CHUNK_SIZE setting in sqlite. This helps avoid fragmentation
 364    * by growing/shrinking the database file in SQLITE_FCNTL_CHUNK_SIZE increments.
 365    *
 366    * @param aIncrement
 367    *        The database file will grow in multiples of chunkSize.
 368    * @param aDatabaseName
 369    *        Sqlite database name. "" means pass NULL for zDbName to sqlite3_file_control.
 370    *        See http://sqlite.org/c3ref/file_control.html for more details.
 371    */
 372   void setGrowthIncrement(in PRInt32 aIncrement, in AUTF8String aDatabaseName);
 373 };