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