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