storage/src/mozStorageConnection.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Oracle Corporation code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  *  Oracle Corporation
  20  * Portions created by the Initial Developer are Copyright (C) 2004
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
  25  *   Lev Serebryakov <lev@serebryakov.spb.ru>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #ifndef mozilla_storage_Connection_h
  42 #define mozilla_storage_Connection_h
  43
  44 #include "nsAutoPtr.h"
  45 #include "nsCOMPtr.h"
  46 #include "mozilla/Mutex.h"
  47 #include "nsIInterfaceRequestor.h"
  48
  49 #include "nsString.h"
  50 #include "nsDataHashtable.h"
  51 #include "mozIStorageProgressHandler.h"
  52 #include "SQLiteMutex.h"
  53 #include "mozIStorageConnection.h"
  54 #include "mozStorageService.h"
  55
  56 #include "nsIMutableArray.h"
  57
  58 #include "sqlite3.h"
  59
  60 struct PRLock;
  61 class nsIFile;
  62 class nsIEventTarget;
  63 class nsIThread;
  64
  65 namespace mozilla {
  66 namespace storage {
  67
  68 class Connection : public mozIStorageConnection
  69                  , public nsIInterfaceRequestor
  70 {
  71 public:
  72   NS_DECL_ISUPPORTS
  73   NS_DECL_MOZISTORAGECONNECTION
  74   NS_DECL_NSIINTERFACEREQUESTOR
  75
  76   /**
  77    * Structure used to describe user functions on the database connection.
  78    */
  79   struct FunctionInfo {
  80     enum FunctionType {
  81       SIMPLE,
  82       AGGREGATE
  83     };
  84
  85     nsCOMPtr<nsISupports> function;
  86     FunctionType type;
  87     PRInt32 numArgs;
  88   };
  89
  90   /**
  91    * @param aService
  92    *        Pointer to the storage service.  Held onto for the lifetime of the
  93    *        connection.
  94    * @param aFlags
  95    *        The flags to pass to sqlite3_open_v2.
  96    */
  97   Connection(Service *aService, int aFlags);
  98
  99   /**
 100    * Creates the connection to the database.
 101    *
 102    * @param aDatabaseFile
 103    *        The nsIFile of the location of the database to open, or create if it
 104    *        does not exist.  Passing in nsnull here creates an in-memory
 105    *        database.
 106    * @param aVFSName
 107    *        The VFS that SQLite will use when opening this database. NULL means
 108    *        "default".
 109    */
 110   nsresult initialize(nsIFile *aDatabaseFile,
 111                       const char* aVFSName = NULL);
 112
 113   // fetch the native handle
 114   sqlite3 *GetNativeConnection() { return mDBConn; }
 115
 116   /**
 117    * Lazily creates and returns a background execution thread.  In the future,
 118    * the thread may be re-claimed if left idle, so you should call this
 119    * method just before you dispatch and not save the reference.
 120    *
 121    * @returns an event target suitable for asynchronous statement execution.
 122    */
 123   nsIEventTarget *getAsyncExecutionTarget();
 124
 125   /**
 126    * Mutex used by asynchronous statements to protect state.  The mutex is
 127    * declared on the connection object because there is no contention between
 128    * asynchronous statements (they are serialized on mAsyncExecutionThread).  It
 129    * also protects mPendingStatements.
 130    */
 131   Mutex sharedAsyncExecutionMutex;
 132
 133   /**
 134    * Wraps the mutex that SQLite gives us from sqlite3_db_mutex.  This is public
 135    * because we already expose the sqlite3* native connection and proper
 136    * operation of the deadlock detector requires everyone to use the same single
 137    * SQLiteMutex instance for correctness.
 138    */
 139   SQLiteMutex sharedDBMutex;
 140
 141   /**
 142    * References the thread this database was opened on.  This MUST be thread it is
 143    * closed on.
 144    */
 145   const nsCOMPtr<nsIThread> threadOpenedOn;
 146
 147   /**
 148    * Closes the SQLite database, and warns about any non-finalized statements.
 149    */
 150   nsresult internalClose();
 151
 152   /**
 153    * Obtains the filename of the connection.  Useful for logging.
 154    */
 155   nsCString getFilename();
 156
 157 private:
 158   ~Connection();
 159
 160   /**
 161    * Sets the database into a closed state so no further actions can be
 162    * performed.
 163    *
 164    * @note mDBConn is set to NULL in this method.
 165    */
 166   nsresult setClosedState();
 167
 168   /**
 169    * Describes a certain primitive type in the database.
 170    *
 171    * Possible Values Are:
 172    *  INDEX - To check for the existence of an index
 173    *  TABLE - To check for the existence of a table
 174    */
 175   enum DatabaseElementType {
 176     INDEX,
 177     TABLE
 178   };
 179
 180   /**
 181    * Determines if the specified primitive exists.
 182    *
 183    * @param aElementType
 184    *        The type of element to check the existence of
 185    * @param aElementName
 186    *        The name of the element to check for
 187    * @returns true if element exists, false otherwise
 188    */
 189   nsresult databaseElementExists(enum DatabaseElementType aElementType,
 190                                  const nsACString& aElementName,
 191                                  PRBool *_exists);
 192
 193   bool findFunctionByInstance(nsISupports *aInstance);
 194
 195   static int sProgressHelper(void *aArg);
 196   // Generic progress handler
 197   // Dispatch call to registered progress handler,
 198   // if there is one. Do nothing in other cases.
 199   int progressHandler();
 200
 201   sqlite3 *mDBConn;
 202   nsCOMPtr<nsIFile> mDatabaseFile;
 203
 204   /**
 205    * Lazily created thread for asynchronous statement execution.  Consumers
 206    * should use getAsyncExecutionTarget rather than directly accessing this
 207    * field.
 208    */
 209   nsCOMPtr<nsIThread> mAsyncExecutionThread;
 210   /**
 211    * Set to true by Close() prior to actually shutting down the thread.  This
 212    * lets getAsyncExecutionTarget() know not to hand out any more thread
 213    * references (or to create the thread in the first place).  This variable
 214    * should be accessed while holding the mAsyncExecutionMutex.
 215    */
 216   bool mAsyncExecutionThreadShuttingDown;
 217
 218   /**
 219    * Tracks if we have a transaction in progress or not.  Access protected by
 220    * mDBMutex.
 221    */
 222   PRBool mTransactionInProgress;
 223
 224   /**
 225    * Stores the mapping of a given function by name to its instance.  Access is
 226    * protected by mDBMutex.
 227    */
 228   nsDataHashtable<nsCStringHashKey, FunctionInfo> mFunctions;
 229
 230   /**
 231    * Stores the registered progress handler for the database connection.  Access
 232    * is protected by mDBMutex.
 233    */
 234   nsCOMPtr<mozIStorageProgressHandler> mProgressHandler;
 235
 236   /**
 237    * Stores the flags we passed to sqlite3_open_v2.
 238    */
 239   const int mFlags;
 240
 241   // This is here for two reasons: 1) It's used to make sure that the
 242   // connections do not outlive the service.  2) Our custom collating functions
 243   // call its localeCompareStrings() method.
 244   nsRefPtr<Service> mStorageService;
 245 };
 246
 247 } // namespace storage
 248 } // namespace mozilla
 249
 250 #endif // mozilla_storage_Connection_h