1 /* 2 * Copyright (C) 2017 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 android.support.v7.preference; 18 19 import android.support.annotation.Nullable; 20 21 import java.util.Set; 22 23 /** 24 * A data store interface to be implemented and provided to the Preferences framework. This can be 25 * used to replace the default {@link android.content.SharedPreferences}, if needed. 26 * 27 * <p>In most cases you want to use {@link android.content.SharedPreferences} as it is automatically 28 * backed up and migrated to new devices. However, providing custom data store to preferences can be 29 * useful if your app stores its preferences in a local db, cloud or they are device specific like 30 * "Developer settings". It might be also useful when you want to use the preferences UI but 31 * the data are not supposed to be stored at all because they are valid per session only. 32 * 33 * <p>Once a put method is called it is full responsibility of the data store implementation to 34 * safely store the given values. Time expensive operations need to be done in the background to 35 * prevent from blocking the UI. You also need to have a plan on how to serialize the data in case 36 * the activity holding this object gets destroyed. 37 * 38 * <p>By default, all "put" methods throw {@link UnsupportedOperationException}. 39 * 40 * @see Preference#setPreferenceDataStore(PreferenceDataStore) 41 * @see PreferenceManager#setPreferenceDataStore(PreferenceDataStore) 42 */ 43 public abstract class PreferenceDataStore { 44 45 /** 46 * Sets a {@link String} value to the data store. 47 * 48 * <p>Once the value is set the data store is responsible for holding it. 49 * 50 * @param key the name of the preference to modify 51 * @param value the new value for the preference 52 * @see #getString(String, String) 53 */ putString(String key, @Nullable String value)54 public void putString(String key, @Nullable String value) { 55 throw new UnsupportedOperationException("Not implemented on this data store"); 56 } 57 58 /** 59 * Sets a set of Strings to the data store. 60 * 61 * <p>Once the value is set the data store is responsible for holding it. 62 * 63 * @param key the name of the preference to modify 64 * @param values the set of new values for the preference 65 * @see #getStringSet(String, Set<String>) 66 */ putStringSet(String key, @Nullable Set<String> values)67 public void putStringSet(String key, @Nullable Set<String> values) { 68 throw new UnsupportedOperationException("Not implemented on this data store"); 69 } 70 71 /** 72 * Sets an {@link Integer} value to the data store. 73 * 74 * <p>Once the value is set the data store is responsible for holding it. 75 * 76 * @param key the name of the preference to modify 77 * @param value the new value for the preference 78 * @see #getInt(String, int) 79 */ putInt(String key, int value)80 public void putInt(String key, int value) { 81 throw new UnsupportedOperationException("Not implemented on this data store"); 82 } 83 84 /** 85 * Sets a {@link Long} value to the data store. 86 * 87 * <p>Once the value is set the data store is responsible for holding it. 88 * 89 * @param key the name of the preference to modify 90 * @param value the new value for the preference 91 * @see #getLong(String, long) 92 */ putLong(String key, long value)93 public void putLong(String key, long value) { 94 throw new UnsupportedOperationException("Not implemented on this data store"); 95 } 96 97 /** 98 * Sets a {@link Float} value to the data store. 99 * 100 * <p>Once the value is set the data store is responsible for holding it. 101 * 102 * @param key the name of the preference to modify 103 * @param value the new value for the preference 104 * @see #getFloat(String, float) 105 */ putFloat(String key, float value)106 public void putFloat(String key, float value) { 107 throw new UnsupportedOperationException("Not implemented on this data store"); 108 } 109 110 /** 111 * Sets a {@link Boolean} value to the data store. 112 * 113 * <p>Once the value is set the data store is responsible for holding it. 114 * 115 * @param key the name of the preference to modify 116 * @param value the new value for the preference 117 * @see #getBoolean(String, boolean) 118 */ putBoolean(String key, boolean value)119 public void putBoolean(String key, boolean value) { 120 throw new UnsupportedOperationException("Not implemented on this data store"); 121 } 122 123 /** 124 * Retrieves a {@link String} value from the data store. 125 * 126 * @param key the name of the preference to retrieve 127 * @param defValue value to return if this preference does not exist in the storage 128 * @return the value from the data store or the default return value 129 * @see #putString(String, String) 130 */ 131 @Nullable getString(String key, @Nullable String defValue)132 public String getString(String key, @Nullable String defValue) { 133 return defValue; 134 } 135 136 /** 137 * Retrieves a set of Strings from the data store. 138 * 139 * @param key the name of the preference to retrieve 140 * @param defValues values to return if this preference does not exist in the storage 141 * @return the values from the data store or the default return values 142 * @see #putStringSet(String, Set<String>) 143 */ 144 @Nullable getStringSet(String key, @Nullable Set<String> defValues)145 public Set<String> getStringSet(String key, @Nullable Set<String> defValues) { 146 return defValues; 147 } 148 149 /** 150 * Retrieves an {@link Integer} value from the data store. 151 * 152 * @param key the name of the preference to retrieve 153 * @param defValue value to return if this preference does not exist in the storage 154 * @return the value from the data store or the default return value 155 * @see #putInt(String, int) 156 */ getInt(String key, int defValue)157 public int getInt(String key, int defValue) { 158 return defValue; 159 } 160 161 /** 162 * Retrieves a {@link Long} value from the data store. 163 * 164 * @param key the name of the preference to retrieve 165 * @param defValue value to return if this preference does not exist in the storage 166 * @return the value from the data store or the default return value 167 * @see #putLong(String, long) 168 */ getLong(String key, long defValue)169 public long getLong(String key, long defValue) { 170 return defValue; 171 } 172 173 /** 174 * Retrieves a {@link Float} value from the data store. 175 * 176 * @param key the name of the preference to retrieve 177 * @param defValue value to return if this preference does not exist in the storage 178 * @return the value from the data store or the default return value 179 * @see #putFloat(String, float) 180 */ getFloat(String key, float defValue)181 public float getFloat(String key, float defValue) { 182 return defValue; 183 } 184 185 /** 186 * Retrieves a {@link Boolean} value from the data store. 187 * 188 * @param key the name of the preference to retrieve 189 * @param defValue value to return if this preference does not exist in the storage 190 * @return the value from the data store or the default return value 191 * @see #getBoolean(String, boolean) 192 */ getBoolean(String key, boolean defValue)193 public boolean getBoolean(String key, boolean defValue) { 194 return defValue; 195 } 196 } 197 198