SharedPreferences.java revision edf32d01316bd3432c023f17747461b08ae36375
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; 20 21/** 22 * Interface for accessing and modifying preference data returned by {@link 23 * Context#getSharedPreferences}. For any particular set of preferences, 24 * there is a single instance of this class that all clients share. 25 * Modifications to the preferences must go through an {@link Editor} object 26 * to ensure the preference values remain in a consistent state and control 27 * when they are committed to storage. 28 * 29 * <p><em>Note: currently this class does not support use across multiple 30 * processes. This will be added later.</em> 31 * 32 * @see Context#getSharedPreferences 33 */ 34public interface SharedPreferences { 35 /** 36 * Interface definition for a callback to be invoked when a shared 37 * preference is changed. 38 */ 39 public interface OnSharedPreferenceChangeListener { 40 /** 41 * Called when a shared preference is changed, added, or removed. This 42 * may be called even if a preference is set to its existing value. 43 * 44 * @param sharedPreferences The {@link SharedPreferences} that received 45 * the change. 46 * @param key The key of the preference that was changed, added, or 47 * removed. 48 */ 49 void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key); 50 } 51 52 /** 53 * Interface used for modifying values in a {@link SharedPreferences} 54 * object. All changes you make in an editor are batched, and not copied 55 * back to the original {@link SharedPreferences} or persistent storage 56 * until you call {@link #commit}. 57 */ 58 public interface Editor { 59 /** 60 * Set a String value in the preferences editor, to be written back once 61 * {@link #commit} is called. 62 * 63 * @param key The name of the preference to modify. 64 * @param value The new value for the preference. 65 * 66 * @return Returns a reference to the same Editor object, so you can 67 * chain put calls together. 68 */ 69 Editor putString(String key, String value); 70 71 /** 72 * Set an int value in the preferences editor, to be written back once 73 * {@link #commit} is called. 74 * 75 * @param key The name of the preference to modify. 76 * @param value The new value for the preference. 77 * 78 * @return Returns a reference to the same Editor object, so you can 79 * chain put calls together. 80 */ 81 Editor putInt(String key, int value); 82 83 /** 84 * Set a long value in the preferences editor, to be written back once 85 * {@link #commit} is called. 86 * 87 * @param key The name of the preference to modify. 88 * @param value The new value for the preference. 89 * 90 * @return Returns a reference to the same Editor object, so you can 91 * chain put calls together. 92 */ 93 Editor putLong(String key, long value); 94 95 /** 96 * Set a float value in the preferences editor, to be written back once 97 * {@link #commit} is 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 */ 105 Editor putFloat(String key, float value); 106 107 /** 108 * Set a boolean value in the preferences editor, to be written back 109 * once {@link #commit} is 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 */ 117 Editor putBoolean(String key, boolean value); 118 119 /** 120 * Mark in the editor that a preference value should be removed, which 121 * will be done in the actual preferences once {@link #commit} is 122 * called. 123 * 124 * <p>Note that when committing back to the preferences, all removals 125 * are done first, regardless of whether you called remove before 126 * or after put methods on this editor. 127 * 128 * @param key The name of the preference to remove. 129 * 130 * @return Returns a reference to the same Editor object, so you can 131 * chain put calls together. 132 */ 133 Editor remove(String key); 134 135 /** 136 * Mark in the editor to remove <em>all</em> values from the 137 * preferences. Once commit is called, the only remaining preferences 138 * will be any that you have defined in this editor. 139 * 140 * <p>Note that when committing back to the preferences, the clear 141 * is done first, regardless of whether you called clear before 142 * or after put methods on this editor. 143 * 144 * @return Returns a reference to the same Editor object, so you can 145 * chain put calls together. 146 */ 147 Editor clear(); 148 149 /** 150 * Commit your preferences changes back from this Editor to the 151 * {@link SharedPreferences} object it is editing. This atomically 152 * performs the requested modifications, replacing whatever is currently 153 * in the SharedPreferences. 154 * 155 * <p>Note that when two editors are modifying preferences at the same 156 * time, the last one to call commit wins. 157 * 158 * <p>If you don't care about the return value and you're 159 * using this from your application's main thread, consider 160 * using {@link #startCommit} instead. 161 * 162 * @return Returns true if the new values were successfully written 163 * to persistent storage. 164 */ 165 boolean commit(); 166 167 /** 168 * Commit your preferences changes back from this Editor to the 169 * {@link SharedPreferences} object it is editing. This atomically 170 * performs the requested modifications, replacing whatever is currently 171 * in the SharedPreferences. 172 * 173 * <p>Note that when two editors are modifying preferences at the same 174 * time, the last one to call commit wins. 175 * 176 * <p>Unlike {@link #commit}, which writes its preferences out 177 * to persistent storage synchronously, {@link #startCommit} 178 * commits its changes to the in-memory 179 * {@link SharedPreferences} immediately but starts an 180 * asynchronous commit to disk and you won't be notified of 181 * any failures. If another editor on this 182 * {@link SharedPreferences} does a regular {@link #commit} 183 * while a {@link #startCommit} is still outstanding, the 184 * {@link #commit} will block until all async commits are 185 * completed as well as the commit itself. 186 * 187 * <p>If you call this from an {@link android.app.Activity}, 188 * the base class will wait for any async commits to finish in 189 * its {@link android.app.Activity#onPause}.</p> 190 * 191 * @return Returns true if the new values were successfully written 192 * to persistent storage. 193 */ 194 void startCommit(); 195 } 196 197 /** 198 * Retrieve all values from the preferences. 199 * 200 * @return Returns a map containing a list of pairs key/value representing 201 * the preferences. 202 * 203 * @throws NullPointerException 204 */ 205 Map<String, ?> getAll(); 206 207 /** 208 * Retrieve a String value from the preferences. 209 * 210 * @param key The name of the preference to retrieve. 211 * @param defValue Value to return if this preference does not exist. 212 * 213 * @return Returns the preference value if it exists, or defValue. Throws 214 * ClassCastException if there is a preference with this name that is not 215 * a String. 216 * 217 * @throws ClassCastException 218 */ 219 String getString(String key, String defValue); 220 221 /** 222 * Retrieve an int value from the preferences. 223 * 224 * @param key The name of the preference to retrieve. 225 * @param defValue Value to return if this preference does not exist. 226 * 227 * @return Returns the preference value if it exists, or defValue. Throws 228 * ClassCastException if there is a preference with this name that is not 229 * an int. 230 * 231 * @throws ClassCastException 232 */ 233 int getInt(String key, int defValue); 234 235 /** 236 * Retrieve a long value from the preferences. 237 * 238 * @param key The name of the preference to retrieve. 239 * @param defValue Value to return if this preference does not exist. 240 * 241 * @return Returns the preference value if it exists, or defValue. Throws 242 * ClassCastException if there is a preference with this name that is not 243 * a long. 244 * 245 * @throws ClassCastException 246 */ 247 long getLong(String key, long defValue); 248 249 /** 250 * Retrieve a float value from the preferences. 251 * 252 * @param key The name of the preference to retrieve. 253 * @param defValue Value to return if this preference does not exist. 254 * 255 * @return Returns the preference value if it exists, or defValue. Throws 256 * ClassCastException if there is a preference with this name that is not 257 * a float. 258 * 259 * @throws ClassCastException 260 */ 261 float getFloat(String key, float defValue); 262 263 /** 264 * Retrieve a boolean value from the preferences. 265 * 266 * @param key The name of the preference to retrieve. 267 * @param defValue Value to return if this preference does not exist. 268 * 269 * @return Returns the preference value if it exists, or defValue. Throws 270 * ClassCastException if there is a preference with this name that is not 271 * a boolean. 272 * 273 * @throws ClassCastException 274 */ 275 boolean getBoolean(String key, boolean defValue); 276 277 /** 278 * Checks whether the preferences contains a preference. 279 * 280 * @param key The name of the preference to check. 281 * @return Returns true if the preference exists in the preferences, 282 * otherwise false. 283 */ 284 boolean contains(String key); 285 286 /** 287 * Create a new Editor for these preferences, through which you can make 288 * modifications to the data in the preferences and atomically commit those 289 * changes back to the SharedPreferences object. 290 * 291 * <p>Note that you <em>must</em> call {@link Editor#commit} to have any 292 * changes you perform in the Editor actually show up in the 293 * SharedPreferences. 294 * 295 * @return Returns a new instance of the {@link Editor} interface, allowing 296 * you to modify the values in this SharedPreferences object. 297 */ 298 Editor edit(); 299 300 /** 301 * Registers a callback to be invoked when a change happens to a preference. 302 * 303 * @param listener The callback that will run. 304 * @see #unregisterOnSharedPreferenceChangeListener 305 */ 306 void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 307 308 /** 309 * Unregisters a previous callback. 310 * 311 * @param listener The callback that should be unregistered. 312 * @see #registerOnSharedPreferenceChangeListener 313 */ 314 void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 315} 316