1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.camera.settings; 18 19 import android.content.SharedPreferences; 20 21 import com.android.camera.debug.Log; 22 23 /** 24 * The SettingsUpgrader class can be used to define an upgrade flow that 25 * executes upgrade logic to a target version when a version number has changed. 26 */ 27 public abstract class SettingsUpgrader { 28 private static final Log.Tag TAG = new Log.Tag("SettingsUpgrader"); 29 30 private final String mVersionKey; 31 private final int mTargetVersion; 32 33 // These values were in use by the original preferences management, before 34 // SettingsManager, to represent string-based booleans via typed string 35 // resource arrays. We no longer utilize such value arrays, and reference 36 // these constants only within SettingsUpgraders to convert to new string- 37 // based booleans. 38 protected static final String OLD_SETTINGS_VALUE_NONE = "none"; 39 protected static final String OLD_SETTINGS_VALUE_ON = "on"; 40 protected static final String OLD_SETTINGS_VALUE_OFF = "off"; 41 SettingsUpgrader(String versionKey, int targetVersion)42 public SettingsUpgrader(String versionKey, int targetVersion) { 43 mVersionKey = versionKey; 44 mTargetVersion = targetVersion; 45 } 46 47 /** 48 * Execute an upgrade callback if an upgrade version has changed. Third 49 * party modules also use this to upgrade settings local to them. 50 */ upgrade(SettingsManager settingsManager)51 public void upgrade(SettingsManager settingsManager) { 52 int lastVersion = getLastVersion(settingsManager); 53 if (lastVersion != mTargetVersion) { 54 upgrade(settingsManager, lastVersion, mTargetVersion); 55 } 56 settingsManager.set(SettingsManager.SCOPE_GLOBAL, mVersionKey, mTargetVersion); 57 } 58 59 /** 60 * Perform upgrades to bring any settings up to date to the version 61 * specified in currentVersion, where the settings were last upgraded to 62 * lastVersion. Typically an Upgrader will check whether lastVersion is less 63 * than some known version for a particular setting, and apply upgrade logic 64 * if lastVersion is less than that known version. 65 */ upgrade(SettingsManager settingsManager, int lastVersion, int targetVersion)66 protected abstract void upgrade(SettingsManager settingsManager, int lastVersion, 67 int targetVersion); 68 69 /** 70 * Retrieve the last persisted version for the particular upgrader. 71 * Typically will be stored in SCOPE_GLOBAL in SettingsManager, but an 72 * Upgrader may need to perform an upgrade analysis on the version 73 * persistence itself and should do so here. 74 * 75 * @throws a {@link ClassCastException} if the value for Version is not a 76 * String 77 */ getLastVersion(SettingsManager settingsManager)78 protected int getLastVersion(SettingsManager settingsManager) { 79 return settingsManager.getInteger(SettingsManager.SCOPE_GLOBAL, mVersionKey); 80 } 81 82 /** 83 * A helper function that is used to remove a setting stored as a boolean, 84 * and return the value that was removed. 85 * <p> 86 * This is used in the upgrade path to change all underlying 87 * SharedPreferences values to Strings. It can be used by third party 88 * modules to upgrade their boolean settings to Strings. 89 */ removeBoolean(SharedPreferences oldPreferencesLocation, String key)90 protected boolean removeBoolean(SharedPreferences oldPreferencesLocation, String key) { 91 boolean value = false; 92 try { 93 value = oldPreferencesLocation.getBoolean(key, value); 94 } catch (ClassCastException e) { 95 Log.e(TAG, "error reading old value, removing and returning default", e); 96 } 97 oldPreferencesLocation.edit().remove(key).apply(); 98 return value; 99 } 100 101 /** 102 * A helper function that is used to remove a setting stored as an Integer, 103 * and return the value that was removed. 104 * <p> 105 * This is used in the upgrade path to change all underlying 106 * SharedPreferences values to Strings. It can be used by third party 107 * modules to upgrade their Integer settings to Strings. 108 */ removeInteger(SharedPreferences oldPreferencesLocation, String key)109 protected int removeInteger(SharedPreferences oldPreferencesLocation, String key) { 110 int value = 0; 111 try { 112 value = oldPreferencesLocation.getInt(key, value); 113 } catch (ClassCastException e) { 114 Log.e(TAG, "error reading old value, removing and returning default", e); 115 } 116 oldPreferencesLocation.edit().remove(key).apply(); 117 return value; 118 } 119 120 /** 121 * A helper function that is used to remove a setting stored as a String, 122 * and return the value that was removed. 123 * <p> 124 * This is used in the upgrade path to change all underlying 125 * SharedPreferences values to Strings. It can be used by third party 126 * modules to upgrade their boolean settings to Strings. 127 */ removeString(SharedPreferences oldPreferencesLocation, String key)128 protected String removeString(SharedPreferences oldPreferencesLocation, String key) { 129 String value = null; 130 try { 131 value = oldPreferencesLocation.getString(key, value); 132 } catch (ClassCastException e) { 133 Log.e(TAG, "error reading old value, removing and returning default", e); 134 } 135 oldPreferencesLocation.edit().remove(key).apply(); 136 return value; 137 } 138 139 } 140