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.  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         */
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} or {@link #apply} 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         */
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         */
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         */
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         */
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         */
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         */
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         */
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         */
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         */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
354    Editor edit();
355
356    /**
357     * Registers a callback to be invoked when a change happens to a preference.
358     *
359     * <p class="caution"><strong>Caution:</strong> The preference manager does
360     * not currently store a strong reference to the listener. You must store a
361     * strong reference to the listener, or it will be susceptible to garbage
362     * collection. We recommend you keep a reference to the listener in the
363     * instance data of an object that will exist as long as you need the
364     * listener.</p>
365     *
366     * @param listener The callback that will run.
367     * @see #unregisterOnSharedPreferenceChangeListener
368     */
369    void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
370
371    /**
372     * Unregisters a previous callback.
373     *
374     * @param listener The callback that should be unregistered.
375     * @see #registerOnSharedPreferenceChangeListener
376     */
377    void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
378}
379