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