1 /* 2 * Copyright (C) 2006 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.content; 18 19 import android.annotation.Nullable; 20 21 import java.util.Map; 22 import java.util.Set; 23 24 /** 25 * Interface for accessing and modifying preference data returned by {@link 26 * Context#getSharedPreferences}. For any particular set of preferences, 27 * there is a single instance of this class that all clients share. 28 * Modifications to the preferences must go through an {@link Editor} object 29 * to ensure the preference values remain in a consistent state and control 30 * when they are committed to storage. Objects that are returned from the 31 * various <code>get</code> methods must be treated as immutable by the application. 32 * 33 * <p><em>Note: currently this class does not support use across multiple 34 * processes. This will be added later.</em> 35 * 36 * <div class="special reference"> 37 * <h3>Developer Guides</h3> 38 * <p>For more information about using SharedPreferences, read the 39 * <a href="{@docRoot}guide/topics/data/data-storage.html#pref">Data Storage</a> 40 * developer guide.</p></div> 41 * 42 * @see Context#getSharedPreferences 43 */ 44 public interface SharedPreferences { 45 /** 46 * Interface definition for a callback to be invoked when a shared 47 * preference is changed. 48 */ 49 public interface OnSharedPreferenceChangeListener { 50 /** 51 * Called when a shared preference is changed, added, or removed. This 52 * may be called even if a preference is set to its existing value. 53 * 54 * <p>This callback will be run on your main thread. 55 * 56 * @param sharedPreferences The {@link SharedPreferences} that received 57 * the change. 58 * @param key The key of the preference that was changed, added, or 59 * removed. 60 */ onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key)61 void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key); 62 } 63 64 /** 65 * Interface used for modifying values in a {@link SharedPreferences} 66 * object. All changes you make in an editor are batched, and not copied 67 * back to the original {@link SharedPreferences} until you call {@link #commit} 68 * or {@link #apply} 69 */ 70 public interface Editor { 71 /** 72 * Set a String value in the preferences editor, to be written back once 73 * {@link #commit} or {@link #apply} are called. 74 * 75 * @param key The name of the preference to modify. 76 * @param value The new value for the preference. 77 * 78 * @return Returns a reference to the same Editor object, so you can 79 * chain put calls together. 80 */ putString(String key, @Nullable String value)81 Editor putString(String key, @Nullable String value); 82 83 /** 84 * Set a set of String values in the preferences editor, to be written 85 * back once {@link #commit} or {@link #apply} is called. 86 * 87 * @param key The name of the preference to modify. 88 * @param values The set of new values for the preference. Passing {@code null} 89 * for this argument is equivalent to calling {@link #remove(String)} with 90 * this key. 91 * @return Returns a reference to the same Editor object, so you can 92 * chain put calls together. 93 */ putStringSet(String key, @Nullable Set<String> values)94 Editor putStringSet(String key, @Nullable Set<String> values); 95 96 /** 97 * Set an int value in the preferences editor, to be written back once 98 * {@link #commit} or {@link #apply} are called. 99 * 100 * @param key The name of the preference to modify. 101 * @param value The new value for the preference. 102 * 103 * @return Returns a reference to the same Editor object, so you can 104 * chain put calls together. 105 */ putInt(String key, int value)106 Editor putInt(String key, int value); 107 108 /** 109 * Set a long value in the preferences editor, to be written back once 110 * {@link #commit} or {@link #apply} are called. 111 * 112 * @param key The name of the preference to modify. 113 * @param value The new value for the preference. 114 * 115 * @return Returns a reference to the same Editor object, so you can 116 * chain put calls together. 117 */ putLong(String key, long value)118 Editor putLong(String key, long value); 119 120 /** 121 * Set a float value in the preferences editor, to be written back once 122 * {@link #commit} or {@link #apply} are called. 123 * 124 * @param key The name of the preference to modify. 125 * @param value The new value for the preference. 126 * 127 * @return Returns a reference to the same Editor object, so you can 128 * chain put calls together. 129 */ putFloat(String key, float value)130 Editor putFloat(String key, float value); 131 132 /** 133 * Set a boolean value in the preferences editor, to be written back 134 * once {@link #commit} or {@link #apply} are called. 135 * 136 * @param key The name of the preference to modify. 137 * @param value The new value for the preference. 138 * 139 * @return Returns a reference to the same Editor object, so you can 140 * chain put calls together. 141 */ putBoolean(String key, boolean value)142 Editor putBoolean(String key, boolean value); 143 144 /** 145 * Mark in the editor that a preference value should be removed, which 146 * will be done in the actual preferences once {@link #commit} is 147 * called. 148 * 149 * <p>Note that when committing back to the preferences, all removals 150 * are done first, regardless of whether you called remove before 151 * or after put methods on this editor. 152 * 153 * @param key The name of the preference to remove. 154 * 155 * @return Returns a reference to the same Editor object, so you can 156 * chain put calls together. 157 */ remove(String key)158 Editor remove(String key); 159 160 /** 161 * Mark in the editor to remove <em>all</em> values from the 162 * preferences. Once commit is called, the only remaining preferences 163 * will be any that you have defined in this editor. 164 * 165 * <p>Note that when committing back to the preferences, the clear 166 * is done first, regardless of whether you called clear before 167 * or after put methods on this editor. 168 * 169 * @return Returns a reference to the same Editor object, so you can 170 * chain put calls together. 171 */ clear()172 Editor clear(); 173 174 /** 175 * Commit your preferences changes back from this Editor to the 176 * {@link SharedPreferences} object it is editing. This atomically 177 * performs the requested modifications, replacing whatever is currently 178 * in the SharedPreferences. 179 * 180 * <p>Note that when two editors are modifying preferences at the same 181 * time, the last one to call commit wins. 182 * 183 * <p>If you don't care about the return value and you're 184 * using this from your application's main thread, consider 185 * using {@link #apply} instead. 186 * 187 * @return Returns true if the new values were successfully written 188 * to persistent storage. 189 */ commit()190 boolean commit(); 191 192 /** 193 * Commit your preferences changes back from this Editor to the 194 * {@link SharedPreferences} object it is editing. This atomically 195 * performs the requested modifications, replacing whatever is currently 196 * in the SharedPreferences. 197 * 198 * <p>Note that when two editors are modifying preferences at the same 199 * time, the last one to call apply wins. 200 * 201 * <p>Unlike {@link #commit}, which writes its preferences out 202 * to persistent storage synchronously, {@link #apply} 203 * commits its changes to the in-memory 204 * {@link SharedPreferences} immediately but starts an 205 * asynchronous commit to disk and you won't be notified of 206 * any failures. If another editor on this 207 * {@link SharedPreferences} does a regular {@link #commit} 208 * while a {@link #apply} is still outstanding, the 209 * {@link #commit} will block until all async commits are 210 * completed as well as the commit itself. 211 * 212 * <p>As {@link SharedPreferences} instances are singletons within 213 * a process, it's safe to replace any instance of {@link #commit} with 214 * {@link #apply} if you were already ignoring the return value. 215 * 216 * <p>You don't need to worry about Android component 217 * lifecycles and their interaction with <code>apply()</code> 218 * writing to disk. The framework makes sure in-flight disk 219 * writes from <code>apply()</code> complete before switching 220 * states. 221 * 222 * <p class='note'>The SharedPreferences.Editor interface 223 * isn't expected to be implemented directly. However, if you 224 * previously did implement it and are now getting errors 225 * about missing <code>apply()</code>, you can simply call 226 * {@link #commit} from <code>apply()</code>. 227 */ apply()228 void apply(); 229 } 230 231 /** 232 * Retrieve all values from the preferences. 233 * 234 * <p>Note that you <em>must not</em> modify the collection returned 235 * by this method, or alter any of its contents. The consistency of your 236 * stored data is not guaranteed if you do. 237 * 238 * @return Returns a map containing a list of pairs key/value representing 239 * the preferences. 240 * 241 * @throws NullPointerException 242 */ getAll()243 Map<String, ?> getAll(); 244 245 /** 246 * Retrieve a String value from the preferences. 247 * 248 * @param key The name of the preference to retrieve. 249 * @param defValue Value to return if this preference does not exist. 250 * 251 * @return Returns the preference value if it exists, or defValue. Throws 252 * ClassCastException if there is a preference with this name that is not 253 * a String. 254 * 255 * @throws ClassCastException 256 */ 257 @Nullable getString(String key, @Nullable String defValue)258 String getString(String key, @Nullable String defValue); 259 260 /** 261 * Retrieve a set of String values from the preferences. 262 * 263 * <p>Note that you <em>must not</em> modify the set instance returned 264 * by this call. The consistency of the stored data is not guaranteed 265 * if you do, nor is your ability to modify the instance at all. 266 * 267 * @param key The name of the preference to retrieve. 268 * @param defValues Values to return if this preference does not exist. 269 * 270 * @return Returns the preference values if they exist, or defValues. 271 * Throws ClassCastException if there is a preference with this name 272 * that is not a Set. 273 * 274 * @throws ClassCastException 275 */ 276 @Nullable getStringSet(String key, @Nullable Set<String> defValues)277 Set<String> getStringSet(String key, @Nullable Set<String> defValues); 278 279 /** 280 * Retrieve an int value from the preferences. 281 * 282 * @param key The name of the preference to retrieve. 283 * @param defValue Value to return if this preference does not exist. 284 * 285 * @return Returns the preference value if it exists, or defValue. Throws 286 * ClassCastException if there is a preference with this name that is not 287 * an int. 288 * 289 * @throws ClassCastException 290 */ getInt(String key, int defValue)291 int getInt(String key, int defValue); 292 293 /** 294 * Retrieve a long value from the preferences. 295 * 296 * @param key The name of the preference to retrieve. 297 * @param defValue Value to return if this preference does not exist. 298 * 299 * @return Returns the preference value if it exists, or defValue. Throws 300 * ClassCastException if there is a preference with this name that is not 301 * a long. 302 * 303 * @throws ClassCastException 304 */ getLong(String key, long defValue)305 long getLong(String key, long defValue); 306 307 /** 308 * Retrieve a float value from the preferences. 309 * 310 * @param key The name of the preference to retrieve. 311 * @param defValue Value to return if this preference does not exist. 312 * 313 * @return Returns the preference value if it exists, or defValue. Throws 314 * ClassCastException if there is a preference with this name that is not 315 * a float. 316 * 317 * @throws ClassCastException 318 */ getFloat(String key, float defValue)319 float getFloat(String key, float defValue); 320 321 /** 322 * Retrieve a boolean value from the preferences. 323 * 324 * @param key The name of the preference to retrieve. 325 * @param defValue Value to return if this preference does not exist. 326 * 327 * @return Returns the preference value if it exists, or defValue. Throws 328 * ClassCastException if there is a preference with this name that is not 329 * a boolean. 330 * 331 * @throws ClassCastException 332 */ getBoolean(String key, boolean defValue)333 boolean getBoolean(String key, boolean defValue); 334 335 /** 336 * Checks whether the preferences contains a preference. 337 * 338 * @param key The name of the preference to check. 339 * @return Returns true if the preference exists in the preferences, 340 * otherwise false. 341 */ contains(String key)342 boolean contains(String key); 343 344 /** 345 * Create a new Editor for these preferences, through which you can make 346 * modifications to the data in the preferences and atomically commit those 347 * changes back to the SharedPreferences object. 348 * 349 * <p>Note that you <em>must</em> call {@link Editor#commit} to have any 350 * changes you perform in the Editor actually show up in the 351 * SharedPreferences. 352 * 353 * @return Returns a new instance of the {@link Editor} interface, allowing 354 * you to modify the values in this SharedPreferences object. 355 */ edit()356 Editor edit(); 357 358 /** 359 * Registers a callback to be invoked when a change happens to a preference. 360 * 361 * <p class="caution"><strong>Caution:</strong> The preference manager does 362 * not currently store a strong reference to the listener. You must store a 363 * strong reference to the listener, or it will be susceptible to garbage 364 * collection. We recommend you keep a reference to the listener in the 365 * instance data of an object that will exist as long as you need the 366 * listener.</p> 367 * 368 * @param listener The callback that will run. 369 * @see #unregisterOnSharedPreferenceChangeListener 370 */ registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener)371 void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 372 373 /** 374 * Unregisters a previous callback. 375 * 376 * @param listener The callback that should be unregistered. 377 * @see #registerOnSharedPreferenceChangeListener 378 */ unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener)379 void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 380 } 381