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