Add support for downgrading database version in SQLiteOpenHelper

Provide an API to allow application to support downgrade in databases
managed with SQLiteOpenHelper. Since onUpgrade() is now called only
if requested version is newer than current one, this adds support for
a similar onDowngrade() method, so customers can implement graceful
downgrading. If no downgrade method is implemented by caller, this
fallback to current behavior by throwing an exception.

Bug: 1609474
Change-Id: I0e0166984d4a700b1c43ce780b91244bc2fc87a6

2 files changed, 39 insertions, 12 deletions

diff --git a/api/current.xml b/api/current.xml
index 0f461a2..7ac7dfa 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -70875,6 +70875,23 @@
 <parameter name="db" type="android.database.sqlite.SQLiteDatabase">
 </parameter>
 </method>
+<method name="onDowngrade"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="db" type="android.database.sqlite.SQLiteDatabase">
+</parameter>
+<parameter name="oldVersion" type="int">
+</parameter>
+<parameter name="newVersion" type="int">
+</parameter>
+</method>
 <method name="onOpen"
  return="void"
  abstract="false"
diff --git a/core/java/android/database/sqlite/SQLiteOpenHelper.java b/core/java/android/database/sqlite/SQLiteOpenHelper.java
index ccf8d68..e2befca 100644
--- a/core/java/android/database/sqlite/SQLiteOpenHelper.java
+++ b/core/java/android/database/sqlite/SQLiteOpenHelper.java
@@ -38,10 +38,7 @@ import android.util.Log;
  * in the <em>samples/</em> directory of the SDK.</p>
  *
  * <p class="note"><strong>Note:</strong> this class assumes
- * monotonically increasing version numbers for upgrades.  Also, there
- * is no concept of a database downgrade; installing a new version of
- * your app which uses a lower version number than a
- * previously-installed version will result in undefined behavior.</p>
+ * monotonically increasing version numbers for upgrades.</p>
  */
 public abstract class SQLiteOpenHelper {
     private static final String TAG = SQLiteOpenHelper.class.getSimpleName();
@@ -65,7 +62,8 @@ public abstract class SQLiteOpenHelper {
      * @param name of the database file, or null for an in-memory database
      * @param factory to use for creating cursor objects, or null for the default
      * @param version number of the database (starting at 1); if the database is older,
-     *     {@link #onUpgrade} will be used to upgrade the database
+     *     {@link #onUpgrade} will be used to upgrade the database; if the database is
+     *     newer, {@link #onDowngrade} will be used to downgrade the database
      */
     public SQLiteOpenHelper(Context context, String name, CursorFactory factory, int version) {
         this(context, name, factory, version, new DefaultDatabaseErrorHandler());
@@ -152,10 +150,6 @@ public abstract class SQLiteOpenHelper {
             }
 
             int version = db.getVersion();
-            if (version > mNewVersion) {
-                throw new IllegalStateException("Database " + mName +
-                        " cannot be downgraded. instead, please uninstall new version first.");
-            }
             if (version != mNewVersion) {
                 db.beginTransaction();
                 try {
@@ -163,10 +157,10 @@ public abstract class SQLiteOpenHelper {
                         onCreate(db);
                     } else {
                         if (version > mNewVersion) {
-                            Log.wtf(TAG, "Can't downgrade read-only database from version " +
-                                    version + " to " + mNewVersion + ": " + db.getPath());
+                            onDowngrade(db, version, mNewVersion);
+                        } else {
+                            onUpgrade(db, version, mNewVersion);
                         }
-                        onUpgrade(db, version, mNewVersion);
                     }
                     db.setVersion(mNewVersion);
                     db.setTransactionSuccessful();
@@ -291,6 +285,22 @@ public abstract class SQLiteOpenHelper {
     public abstract void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion);
 
     /**
+     * Called when the database needs to be downgraded. This is stricly similar to
+     * 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
+     *
+     * @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 has been opened.  The implementation
      * should check {@link SQLiteDatabase#isReadOnly} before updating the
      * database.