Add support for Java API access to the several features:

developernotes · developernotes · commit 2adb82b5dec0 · 2018-05-31T16:19:54.000-05:00
SQLiteDatabase specific features:
- WAL mode (enable, disable, check if enabled)
- Get list of attached database
- Perform an integrity check
- Enable/disable foreign key constraints
- A few different beginTransaction functions for immediate and exclusive modes

SQLiteOpenHelper specific features:
- Support onConfigure callback
- Support onDowngrade callback
- Expose getting database name
- Expose setting WAL mode
diff --git a/android-database-sqlcipher/src/main/java/net/sqlcipher/database/SQLiteDatabase.java b/android-database-sqlcipher/src/main/java/net/sqlcipher/database/SQLiteDatabase.java
@@ -39,6 +39,7 @@
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
@@ -76,6 +77,12 @@ public class SQLiteDatabase extends SQLiteClosable {
     private static final int EVENT_DB_CORRUPT = 75004;
     private static final String KEY_ENCODING = "UTF-8";
 
+  private enum SQLiteDatabaseTransactionType {
+    Deferred,
+    Immediate,
+    Exclusive,
+  }
+
   /**
    * The version number of the SQLCipher for Android Java client library.
    */
@@ -635,6 +642,75 @@ private void checkLockHoldTime() {
         }
     }
 
+    /**
+     * Performs a PRAGMA integrity_check; command against the database.
+     * @return true if the integrity check is ok, otherwise false
+     */
+    public boolean isDatabaseIntegrityOk() {
+      Pair<Boolean, String> result = getResultFromPragma("PRAGMA integrity_check;");
+      return result.first ? result.second.equals("ok") : result.first;
+    }
+
+    /**
+     * Returns a list of attached databases including the main database
+     * by executing PRAGMA database_list
+     * @return a list of pairs of database name and filename
+     */
+    public List<Pair<String, String>> getAttachedDbs() {
+      return getAttachedDbs(this);
+    }
+
+   /**
+   * Sets the journal mode of the database to WAL
+   * @return true if successful, false otherwise
+   */
+    public boolean enableWriteAheadLogging() {
+      if(inTransaction()) {
+        String message = "Write Ahead Logging cannot be enabled while in a transaction";
+        throw new IllegalStateException(message);
+      }
+      List<Pair<String, String>> attachedDbs = getAttachedDbs(this);
+      if(attachedDbs != null && attachedDbs.size() > 1) return false;
+      if(isReadOnly() || getPath().equals(MEMORY)) return false;
+      String command = "PRAGMA journal_mode = WAL;";
+      rawExecSQL(command);
+      return true;
+    }
+
+   /**
+   * Sets the journal mode of the database to DELETE (the default mode)
+   */
+    public void disableWriteAheadLogging() {
+      if(inTransaction()) {
+        String message = "Write Ahead Logging cannot be disabled while in a transaction";
+        throw new IllegalStateException(message);
+      }
+      String command = "PRAGMA journal_mode = DELETE;";
+      rawExecSQL(command);
+    }
+
+   /**
+   * Sets the journal mode of the database to DELETE (the default mode)
+   */
+    public boolean isWriteAheadLoggingEnabled() {
+      Pair<Boolean, String> result = getResultFromPragma("PRAGMA journal_mode;");
+      return result.first ? result.second.equals("wal") : result.first;
+    }
+
+   /**
+   * Enables or disables foreign key constraints
+   * @param enable used to determine whether or not foreign key constraints are on
+   */
+    public void setForeignKeyConstraintsEnabled(boolean enable) {
+      if(inTransaction()) {
+        String message = "Foreign key constraints may not be changed while in a transaction";
+        throw new IllegalStateException(message);
+      }
+      String command = String.format("PRAGMA foreign_keys = %s;",
+                                     enable ? "ON" : "OFF");
+      execSQL(command);
+    }
+
     /**
      * Begins a transaction. Transactions can be nested. When the outer transaction is ended all of
      * the work done in that transaction and all of the nested transactions will be committed or
@@ -660,10 +736,12 @@ public void beginTransaction() {
     }
 
     /**
-     * Begins a transaction. Transactions can be nested. When the outer transaction is ended all of
-     * the work done in that transaction and all of the nested transactions will be committed or
-     * rolled back. The changes will be rolled back if any transaction is ended without being
-     * marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed.
+     * Begins a transaction in Exlcusive mode. Transactions can be nested. When
+     * the outer transaction is ended all of the work done in that transaction
+     * and all of the nested transactions will be committed or rolled back. The
+     * changes will be rolled back if any transaction is ended without being
+     * marked as clean (by calling setTransactionSuccessful). Otherwise they
+     * will be committed.
      *
      * <p>Here is the standard idiom for transactions:
      *
@@ -683,47 +761,25 @@ public void beginTransaction() {
      * @throws IllegalStateException if the database is not open
      */
     public void beginTransactionWithListener(SQLiteTransactionListener transactionListener) {
-        lockForced();
-        if (!isOpen()) {
-            throw new IllegalStateException("database not open");
-        }
-        boolean ok = false;
-        try {
-            // If this thread already had the lock then get out
-            if (mLock.getHoldCount() > 1) {
-                if (mInnerTransactionIsSuccessful) {
-                    String msg = "Cannot call beginTransaction between "
-                        + "calling setTransactionSuccessful and endTransaction";
-                    IllegalStateException e = new IllegalStateException(msg);
-                    Log.e(TAG, "beginTransaction() failed", e);
-                    throw e;
-                }
-                ok = true;
-                return;
-            }
+      beginTransactionWithListenerInternal(transactionListener,
+                                           SQLiteDatabaseTransactionType.Exclusive);
+    }
 
-            // This thread didn't already have the lock, so begin a database
-            // transaction now.
-            execSQL("BEGIN EXCLUSIVE;");
-            mTransactionListener = transactionListener;
-            mTransactionIsSuccessful = true;
-            mInnerTransactionIsSuccessful = false;
-            if (transactionListener != null) {
-                try {
-                    transactionListener.onBegin();
-                } catch (RuntimeException e) {
-                    execSQL("ROLLBACK;");
-                    throw e;
-                }
-            }
-            ok = true;
-        } finally {
-            if (!ok) {
-                // beginTransaction is called before the try block so we must release the lock in
-                // the case of failure.
-                unlockForced();
-            }
-        }
+  /**
+   * Begins a transaction in Immediate mode
+   */
+    public void beginTransactionNonExclusive() {
+      beginTransactionWithListenerInternal(null,
+                                           SQLiteDatabaseTransactionType.Immediate);
+    }
+
+  /**
+   * Begins a transaction in Immediate mode
+   * @param transactionListener is the listener used to report transaction events
+   */
+    public void beginTransactionWithListenerNonExclusive(SQLiteTransactionListener transactionListener) {
+      beginTransactionWithListenerInternal(transactionListener,
+                                           SQLiteDatabaseTransactionType.Immediate);
     }
 
     /**
@@ -2729,6 +2785,60 @@ public synchronized void setMaxSqlCacheSize(int cacheSize) {
         mMaxSqlCacheSize = cacheSize;
     }
 
+    private void beginTransactionWithListenerInternal(SQLiteTransactionListener transactionListener,
+                                                      SQLiteDatabaseTransactionType transactionType) {
+        lockForced();
+        if (!isOpen()) {
+            throw new IllegalStateException("database not open");
+        }
+        boolean ok = false;
+        try {
+            // If this thread already had the lock then get out
+            if (mLock.getHoldCount() > 1) {
+                if (mInnerTransactionIsSuccessful) {
+                    String msg = "Cannot call beginTransaction between "
+                        + "calling setTransactionSuccessful and endTransaction";
+                    IllegalStateException e = new IllegalStateException(msg);
+                    Log.e(TAG, "beginTransaction() failed", e);
+                    throw e;
+                }
+                ok = true;
+                return;
+            }
+            // This thread didn't already have the lock, so begin a database
+            // transaction now.
+            if(transactionType == SQLiteDatabaseTransactionType.Exclusive) {
+              execSQL("BEGIN EXCLUSIVE;");
+            } else if(transactionType == SQLiteDatabaseTransactionType.Immediate) {
+              execSQL("BEGIN IMMEDIATE;");
+            } else if(transactionType == SQLiteDatabaseTransactionType.Deferred) {
+              execSQL("BEGIN DEFERRED;");
+            } else {
+              String message = String.format("%s is an unsupported transaction type",
+                                             transactionType);
+              throw new IllegalArgumentException(message);
+            }
+            mTransactionListener = transactionListener;
+            mTransactionIsSuccessful = true;
+            mInnerTransactionIsSuccessful = false;
+            if (transactionListener != null) {
+                try {
+                    transactionListener.onBegin();
+                } catch (RuntimeException e) {
+                    execSQL("ROLLBACK;");
+                    throw e;
+                }
+            }
+            ok = true;
+        } finally {
+            if (!ok) {
+                // beginTransaction is called before the try block so we must release the lock in
+                // the case of failure.
+                unlockForced();
+            }
+        }
+    }
+
     /**
      * this method is used to collect data about ALL open databases in the current process.
      * bugreport is a user of this data.
@@ -2837,6 +2947,16 @@ private byte[] getBytes(char[] data) {
       return result;
     }
 
+    private Pair<Boolean, String> getResultFromPragma(String command) {
+      Cursor cursor = rawQuery(command, new Object[]{});
+      if(cursor == null) return new Pair(false, "");
+      cursor.moveToFirst();
+      String value = cursor.getString(0);
+      cursor.close();
+      return new Pair(true, value);
+    }
+
+
     /**
      * Sets the root directory to search for the ICU data file
      */
diff --git a/android-database-sqlcipher/src/main/java/net/sqlcipher/database/SQLiteOpenHelper.java b/android-database-sqlcipher/src/main/java/net/sqlcipher/database/SQLiteOpenHelper.java
@@ -43,6 +43,7 @@ public abstract class SQLiteOpenHelper {
     private final int mNewVersion;
     private final SQLiteDatabaseHook mHook;
     private final DatabaseErrorHandler mErrorHandler;
+    private boolean mEnableWriteAheadLogging;
 
     private SQLiteDatabase mDatabase = null;
     private boolean mIsInitializing = false;
@@ -161,16 +162,19 @@ public synchronized SQLiteDatabase getWritableDatabase(char[] password) {
 
                 db = SQLiteDatabase.openOrCreateDatabase(path, password, mFactory, mHook, mErrorHandler);
             }
-            
-
+            onConfigure(db);
             int version = db.getVersion();
             if (version != mNewVersion) {
                 db.beginTransaction();
                 try {
                     if (version == 0) {
                         onCreate(db);
                     } else {
+                      if(version > mNewVersion) {
+                        onDowngrade(db, version, mNewVersion);
+                      } else {
                         onUpgrade(db, version, mNewVersion);
+                      }
                     }
                     db.setVersion(mNewVersion);
                     db.setTransactionSuccessful();
@@ -274,6 +278,79 @@ public synchronized void close() {
         }
     }
 
+    /**
+     * Return the name of the SQLite database being opened, as given to
+     * the constructor.
+     */
+    public String getDatabaseName() {
+        return mName;
+    }
+
+    /**
+     * Enables or disables the use of write-ahead logging for the database.
+     *
+     * Write-ahead logging cannot be used with read-only databases so the value of
+     * this flag is ignored if the database is opened read-only.
+     *
+     * @param enabled True if write-ahead logging should be enabled, false if it
+     * should be disabled.
+     *
+     * @see SQLiteDatabase#enableWriteAheadLogging()
+     */
+    public void setWriteAheadLoggingEnabled(boolean enabled) {
+        synchronized (this) {
+            if (mEnableWriteAheadLogging != enabled) {
+                if (mDatabase != null && mDatabase.isOpen() && !mDatabase.isReadOnly()) {
+                    if (enabled) {
+                        mDatabase.enableWriteAheadLogging();
+                    } else {
+                        mDatabase.disableWriteAheadLogging();
+                    }
+                }
+                mEnableWriteAheadLogging = enabled;
+            }
+        }
+    }
+
+    /**
+     * Called when the database needs to be downgraded. This is strictly similar to
+     * {@link #onUpgrade} method, but is called whenever current version is newer than requested one.
+     * However, this method is not abstract, so it is not mandatory for a customer to
+     * implement it. If not overridden, default implementation will reject downgrade and
+     * throws SQLiteException
+     *
+     * <p>
+     * This method executes within a transaction.  If an exception is thrown, all changes
+     * will automatically be rolled back.
+     * </p>
+     *
+     * @param db The database.
+     * @param oldVersion The old database version.
+     * @param newVersion The new database version.
+     */
+    public void onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion) {
+        throw new SQLiteException("Can't downgrade database from version " +
+                oldVersion + " to " + newVersion);
+    }
+
+    /**
+     * Called when the database connection is being configured, to enable features
+     * such as write-ahead logging or foreign key support.
+     * <p>
+     * This method is called before {@link #onCreate}, {@link #onUpgrade},
+     * {@link #onDowngrade}, or {@link #onOpen} are called.  It should not modify
+     * the database except to configure the database connection as required.
+     * </p><p>
+     * This method should only call methods that configure the parameters of the
+     * database connection, such as {@link SQLiteDatabase#enableWriteAheadLogging}
+     * {@link SQLiteDatabase#setForeignKeyConstraintsEnabled},
+     * {@link SQLiteDatabase#setLocale}, or executing PRAGMA statements.
+     * </p>
+     *
+     * @param db The database.
+     */
+    public void onConfigure(SQLiteDatabase db) {}
+
     /**
      * Called when the database is created for the first time. This is where the
      * creation of tables and the initial population of the tables should happen.
