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