The Tor Browser: toolkit/components/places/Database.h@b8a032363ba2 (annotated)

toolkit/components/places/Database.h@b8a032363ba2 (annotated)

toolkit/components/places/Database.h

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* 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/. */
 #ifndef mozilla_places_Database_h_
 #define mozilla_places_Database_h_
 #include "MainThreadUtils.h"
 #include "nsWeakReference.h"
 #include "nsIInterfaceRequestorUtils.h"
 #include "nsIObserver.h"
 #include "mozilla/storage.h"
 #include "mozilla/storage/StatementCache.h"
 #include "mozilla/Attributes.h"
 #include "nsIEventTarget.h"
 // This is the schema version. Update it at any schema change and add a
 // corresponding migrateVxx method below.
 #define DATABASE_SCHEMA_VERSION 23
 // Fired after Places inited.
 #define TOPIC_PLACES_INIT_COMPLETE "places-init-complete"
 // Fired when initialization fails due to a locked database.
 #define TOPIC_DATABASE_LOCKED "places-database-locked"
 // This topic is received when the profile is about to be lost.  Places does
 // initial shutdown work and notifies TOPIC_PLACES_SHUTDOWN to all listeners.
 // Any shutdown work that requires the Places APIs should happen here.
 #define TOPIC_PROFILE_CHANGE_TEARDOWN "profile-change-teardown"
 // This topic is received just before the profile is lost.  Places begins
 // shutting down the connection and notifies TOPIC_PLACES_WILL_CLOSE_CONNECTION
 // to all listeners.  Only critical database cleanups should happen here,
 // some APIs may bail out already.
 #define TOPIC_PROFILE_BEFORE_CHANGE "profile-before-change"
 // Fired when Places is shutting down.  Any code should stop accessing Places
 // APIs after this notification.  If you need to listen for Places shutdown
 // you should only use this notification, next ones are intended only for
 // internal Places use.
 #define TOPIC_PLACES_SHUTDOWN "places-shutdown"
 // For Internal use only.  Fired when connection is about to be closed, only
 // cleanup tasks should run at this stage, nothing should be added to the
 // database, nor APIs should be called.
 #define TOPIC_PLACES_WILL_CLOSE_CONNECTION "places-will-close-connection"
 // Fired when the connection has gone, nothing will work from now on.
 #define TOPIC_PLACES_CONNECTION_CLOSED "places-connection-closed"
 class nsIStringBundle;
 class nsIRunnable;
 namespace mozilla {
 namespace places {
 enum JournalMode {
   // Default SQLite journal mode.
   JOURNAL_DELETE = 0
   // Can reduce fsyncs on Linux when journal is deleted (See bug 460315).
   // We fallback to this mode when WAL is unavailable.
 , JOURNAL_TRUNCATE
   // Unsafe in case of crashes on database swap or low memory.
 , JOURNAL_MEMORY
   // Can reduce number of fsyncs.  We try to use this mode by default.
 , JOURNAL_WAL
 };
 class Database MOZ_FINAL : public nsIObserver
                          , public nsSupportsWeakReference
 {
   typedef mozilla::storage::StatementCache<mozIStorageStatement> StatementCache;
   typedef mozilla::storage::StatementCache<mozIStorageAsyncStatement> AsyncStatementCache;
 public:
   NS_DECL_THREADSAFE_ISUPPORTS
   NS_DECL_NSIOBSERVER
   Database();
   /**
    * Initializes the database connection and the schema.
    * In case of corruption the database is copied to a backup file and replaced.
    */
   nsresult Init();
   /**
    * Finalizes the cached statements and closes the database connection.
    * A TOPIC_PLACES_CONNECTION_CLOSED notification is fired when done.
    */
   void Shutdown();
   /**
    * Getter to use when instantiating the class.
    *
    * @return Singleton instance of this class.
    */
   static already_AddRefed<Database> GetDatabase()
   {
     return GetSingleton();
   }
   /**
    * Returns last known database status.
    *
    * @return one of the nsINavHistoryService::DATABASE_STATUS_* constants.
    */
   uint16_t GetDatabaseStatus() const
   {
     return mDatabaseStatus;
   }
   /**
    * Returns a pointer to the storage connection.
    *
    * @return The connection handle.
    */
   mozIStorageConnection* MainConn() const
   {
     return mMainConn;
   }
   /**
    * Dispatches a runnable to the connection async thread, to be serialized
    * with async statements.
    *
    * @param aEvent
    *        The runnable to be dispatched.
    */
   void DispatchToAsyncThread(nsIRunnable* aEvent) const
   {
     if (mClosed) {
       return;
     }
     nsCOMPtr<nsIEventTarget> target = do_GetInterface(mMainConn);
     if (target) {
       (void)target->Dispatch(aEvent, NS_DISPATCH_NORMAL);
     }
   }
   //////////////////////////////////////////////////////////////////////////////
   //// Statements Getters.
   /**
    * Gets a cached synchronous statement.
    *
    * @param aQuery
    *        SQL query literal.
    * @return The cached statement.
    * @note Always null check the result.
    * @note Always use a scoper to reset the statement.
    */
   template<int N>
   already_AddRefed<mozIStorageStatement>
   GetStatement(const char (&aQuery)[N]) const
   {
     nsDependentCString query(aQuery, N - 1);
     return GetStatement(query);
   }
   /**
    * Gets a cached synchronous statement.
    *
    * @param aQuery
    *        nsCString of SQL query.
    * @return The cached statement.
    * @note Always null check the result.
    * @note Always use a scoper to reset the statement.
    */
   already_AddRefed<mozIStorageStatement>
   GetStatement(const nsACString& aQuery) const
   {
     if (mShuttingDown) {
       return nullptr;
     }
     if (NS_IsMainThread()) {
       return mMainThreadStatements.GetCachedStatement(aQuery);
     }
     return mAsyncThreadStatements.GetCachedStatement(aQuery);
   }
   /**
    * Gets a cached asynchronous statement.
    *
    * @param aQuery
    *        SQL query literal.
    * @return The cached statement.
    * @note Always null check the result.
    * @note AsyncStatements are automatically reset on execution.
    */
   template<int N>
   already_AddRefed<mozIStorageAsyncStatement>
   GetAsyncStatement(const char (&aQuery)[N]) const
   {
     nsDependentCString query(aQuery, N - 1);
     return GetAsyncStatement(query);
   }
   /**
    * Gets a cached asynchronous statement.
    *
    * @param aQuery
    *        nsCString of SQL query.
    * @return The cached statement.
    * @note Always null check the result.
    * @note AsyncStatements are automatically reset on execution.
    */
   already_AddRefed<mozIStorageAsyncStatement>
   GetAsyncStatement(const nsACString& aQuery) const
   {
     if (mShuttingDown) {
       return nullptr;
     }
     MOZ_ASSERT(NS_IsMainThread());
     return mMainThreadAsyncStatements.GetCachedStatement(aQuery);
   }
 protected:
   /**
    * Initializes the database file.  If the database does not exist or is
    * corrupt, a new one is created.  In case of corruption it also creates a
    * backup copy of the database.
    *
    * @param aStorage
    *        mozStorage service instance.
    * @param aNewDatabaseCreated
    *        whether a new database file has been created.
    */
   nsresult InitDatabaseFile(nsCOMPtr<mozIStorageService>& aStorage,
                             bool* aNewDatabaseCreated);
   /**
    * Creates a database backup and replaces the original file with a new
    * one.
    *
    * @param aStorage
    *        mozStorage service instance.
    */
   nsresult BackupAndReplaceDatabaseFile(nsCOMPtr<mozIStorageService>& aStorage);
   /**
    * Initializes the database.  This performs any necessary migrations for the
    * database.  All migration is done inside a transaction that is rolled back
    * if any error occurs.
    * @param aDatabaseMigrated
    *        Whether a schema upgrade happened.
    */
   nsresult InitSchema(bool* aDatabaseMigrated);
   /**
    * Creates bookmark roots in a new DB.
    */
   nsresult CreateBookmarkRoots();
   /**
    * Initializes additionale SQLite functions, defined in SQLFunctions.h
    */
   nsresult InitFunctions();
   /**
    * Initializes triggers defined in nsPlacesTriggers.h
    */
   nsresult InitTempTriggers();
   /**
    * Helpers used by schema upgrades.
    */
   nsresult MigrateV7Up();
   nsresult MigrateV8Up();
   nsresult MigrateV9Up();
   nsresult MigrateV10Up();
   nsresult MigrateV11Up();
   nsresult MigrateV13Up();
   nsresult MigrateV14Up();
   nsresult MigrateV15Up();
   nsresult MigrateV16Up();
   nsresult MigrateV17Up();
   nsresult MigrateV18Up();
   nsresult MigrateV19Up();
   nsresult MigrateV20Up();
   nsresult MigrateV21Up();
   nsresult MigrateV22Up();
   nsresult MigrateV23Up();
   nsresult UpdateBookmarkRootTitles();
   nsresult CheckAndUpdateGUIDs();
 private:
   ~Database();
   /**
    * Singleton getter, invoked by class instantiation.
    */
   static already_AddRefed<Database> GetSingleton();
   static Database* gDatabase;
   nsCOMPtr<mozIStorageConnection> mMainConn;
   mutable StatementCache mMainThreadStatements;
   mutable AsyncStatementCache mMainThreadAsyncStatements;
   mutable StatementCache mAsyncThreadStatements;
   int32_t mDBPageSize;
   uint16_t mDatabaseStatus;
   bool mShuttingDown;
   bool mClosed;
 };
 } // namespace places
 } // namespace mozilla
 #endif // mozilla_places_Database_h_

The Tor Browser / annotate

toolkit/components/places/Database.h@b8a032363ba2 (annotated)

toolkit/components/places/Database.h