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