• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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          */
onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key)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          */
putString(String key, String value)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          */
putStringSet(String key, Set<String> values)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          */
putInt(String key, int value)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          */
putLong(String key, long value)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          */
putFloat(String key, float value)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          */
putBoolean(String key, boolean value)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          */
remove(String key)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          */
clear()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          */
commit()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          */
apply()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      */
getAll()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      */
getString(String key, String defValue)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      */
getStringSet(String key, Set<String> defValues)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      */
getInt(String key, int defValue)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      */
getLong(String key, long defValue)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      */
getFloat(String key, float defValue)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      */
getBoolean(String key, boolean defValue)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      */
contains(String key)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      */
edit()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      */
registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener)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      */
unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener)370     void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
371 }
372