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