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