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