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