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