Merge "Clarify settings update code."

2 files changed, 69 insertions, 40 deletions

diff --git a/packages/SettingsProvider/src/com/android/providers/settings/DatabaseHelper.java b/packages/SettingsProvider/src/com/android/providers/settings/DatabaseHelper.java
index 729efcb..0b6ab99 100644
--- a/packages/SettingsProvider/src/com/android/providers/settings/DatabaseHelper.java
+++ b/packages/SettingsProvider/src/com/android/providers/settings/DatabaseHelper.java
@@ -61,10 +61,18 @@ import java.util.List;
 import java.util.Set;
 
 /**
- * Database helper class for {@link SettingsProvider}.
- * Mostly just has a bit {@link #onCreate} to initialize the database.
+ * Legacy settings database helper class for {@link SettingsProvider}.
+ *
+ * IMPORTANT: Do not add any more upgrade steps here as the global,
+ * secure, and system settings are no longer stored in a database
+ * but are kept in memory and persisted to XML.
+ *
+ * See: SettingsProvider.UpgradeController#onUpgradeLocked
+ *
+ * @deprecated The implementation is frozen.  Do not add any new code to this class!
  */
-public class DatabaseHelper extends SQLiteOpenHelper {
+@Deprecated
+class DatabaseHelper extends SQLiteOpenHelper {
     private static final String TAG = "SettingsProvider";
     private static final String DATABASE_NAME = "settings.db";
 
@@ -1932,19 +1940,14 @@ public class DatabaseHelper extends SQLiteOpenHelper {
             upgradeVersion = 118;
         }
 
-        /**
+        /*
          * IMPORTANT: Do not add any more upgrade steps here as the global,
          * secure, and system settings are no longer stored in a database
-         * but are kept in memory and persisted to XML. The correct places
-         * for adding upgrade steps are:
+         * but are kept in memory and persisted to XML.
          *
-         * Global: SettingsProvider.UpgradeController#onUpgradeGlobalSettings
-         * Secure: SettingsProvider.UpgradeController#onUpgradeSecureSettings
-         * System: SettingsProvider.UpgradeController#onUpgradeSystemSettings
+         * See: SettingsProvider.UpgradeController#onUpgradeLocked
          */
 
-        // *** Remember to update DATABASE_VERSION above!
-
         if (upgradeVersion != currentVersion) {
             recreateDatabase(db, oldVersion, upgradeVersion, currentVersion);
         }
@@ -2386,6 +2389,14 @@ public class DatabaseHelper extends SQLiteOpenHelper {
 
             loadIntegerSetting(stmt, Settings.System.POINTER_SPEED,
                     R.integer.def_pointer_speed);
+
+            /*
+             * IMPORTANT: Do not add any more upgrade steps here as the global,
+             * secure, and system settings are no longer stored in a database
+             * but are kept in memory and persisted to XML.
+             *
+             * See: SettingsProvider.UpgradeController#onUpgradeLocked
+             */
         } finally {
             if (stmt != null) stmt.close();
         }
@@ -2517,6 +2528,14 @@ public class DatabaseHelper extends SQLiteOpenHelper {
 
             loadIntegerSetting(stmt, Settings.Secure.SLEEP_TIMEOUT,
                     R.integer.def_sleep_timeout);
+
+            /*
+             * IMPORTANT: Do not add any more upgrade steps here as the global,
+             * secure, and system settings are no longer stored in a database
+             * but are kept in memory and persisted to XML.
+             *
+             * See: SettingsProvider.UpgradeController#onUpgradeLocked
+             */
         } finally {
             if (stmt != null) stmt.close();
         }
@@ -2693,7 +2712,14 @@ public class DatabaseHelper extends SQLiteOpenHelper {
                     R.bool.def_guest_user_enabled);
             loadSetting(stmt, Settings.Global.ENHANCED_4G_MODE_ENABLED,
                     ImsConfig.FeatureValueConstants.ON);
-            // --- New global settings start here
+
+            /*
+             * IMPORTANT: Do not add any more upgrade steps here as the global,
+             * secure, and system settings are no longer stored in a database
+             * but are kept in memory and persisted to XML.
+             *
+             * See: SettingsProvider.UpgradeController#onUpgradeLocked
+             */
         } finally {
             if (stmt != null) stmt.close();
         }
diff --git a/packages/SettingsProvider/src/com/android/providers/settings/SettingsProvider.java b/packages/SettingsProvider/src/com/android/providers/settings/SettingsProvider.java
index 8328d11..126b4aa 100644
--- a/packages/SettingsProvider/src/com/android/providers/settings/SettingsProvider.java
+++ b/packages/SettingsProvider/src/com/android/providers/settings/SettingsProvider.java
@@ -1859,40 +1859,43 @@ public class SettingsProvider extends ContentProvider {
                 return getSettingsLocked(SETTINGS_TYPE_SYSTEM, userId);
             }
 
+            /**
+             * You must perform all necessary mutations to bring the settings
+             * for this user from the old to the new version. When you add a new
+             * upgrade step you *must* update SETTINGS_VERSION.
+             *
+             * This is an example of moving a setting from secure to global.
+             *
+             * // v119: Example settings changes.
+             * if (currentVersion == 118) {
+             *     if (userId == UserHandle.USER_OWNER) {
+             *         // Remove from the secure settings.
+             *         SettingsState secureSettings = getSecureSettingsLocked(userId);
+             *         String name = "example_setting_to_move";
+             *         String value = secureSettings.getSetting(name);
+             *         secureSettings.deleteSetting(name);
+             *
+             *         // Add to the global settings.
+             *         SettingsState globalSettings = getGlobalSettingsLocked();
+             *         globalSettings.insertSetting(name, value, SettingsState.SYSTEM_PACKAGE_NAME);
+             *     }
+             *
+             *     // Update the current version.
+             *     currentVersion = 119;
+             * }
+             */
             private int onUpgradeLocked(int userId, int oldVersion, int newVersion) {
                 if (DEBUG) {
                     Slog.w(LOG_TAG, "Upgrading settings for user: " + userId + " from version: "
                             + oldVersion + " to version: " + newVersion);
                 }
 
-                // You must perform all necessary mutations to bring the settings
-                // for this user from the old to the new version. When you add a new
-                // upgrade step you *must* update SETTINGS_VERSION.
-
-                /**
-                 * This is an example of moving a setting from secure to global.
-                 *
-                 * int currentVersion = oldVersion;
-                 * if (currentVersion == 118) {
-                 *     // Remove from the secure settings.
-                 *     SettingsState secureSettings = getSecureSettingsLocked(userId);
-                 *     String name = "example_setting_to_move";
-                 *     String value = secureSettings.getSetting(name);
-                 *     secureSettings.deleteSetting(name);
-                 *
-                 *     // Add to the global settings.
-                 *     SettingsState globalSettings = getGlobalSettingsLocked();
-                 *     globalSettings.insertSetting(name, value, SettingsState.SYSTEM_PACKAGE_NAME);
-                 *
-                 *     // Update the current version.
-                 *     currentVersion = 119;
-                 * }
-                 *
-                 * // Return the current version.
-                 * return currentVersion;
-                 */
-
-                return SettingsState.VERSION_UNDEFINED;
+                int currentVersion = oldVersion;
+
+                // vXXX: Add new settings above this point.
+
+                // Return the current version.
+                return currentVersion;
             }
         }
     }