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} until you call {@link #commit}
58     * or {@link #apply}
59     */
60    public interface Editor {
61        /**
62         * Set a String value in the preferences editor, to be written back once
63         * {@link #commit} or {@link #apply} are 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} or {@link #apply} are 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} or {@link #apply} are 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} or {@link #apply} are 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} or {@link #apply} are 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 #apply} 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 apply wins.
177         *
178         * <p>Unlike {@link #commit}, which writes its preferences out
179         * to persistent storage synchronously, {@link #apply}
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 #apply} 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>As {@link SharedPreferences} instances are singletons within
190         * a process, it's safe to replace any instance of {@link #commit} with
191         * {@link #apply} if you were already ignoring the return value.
192         *
193         * <p>You don't need to worry about Android component
194         * lifecycles and their interaction with <code>apply()</code>
195         * writing to disk.  The framework makes sure in-flight disk
196         * writes from <code>apply()</code> complete before switching
197         * states.
198         *
199         * <p class='note'>The SharedPreferences.Editor interface
200         * isn't expected to be implemented directly.  However, if you
201         * previously did implement it and are now getting errors
202         * about missing <code>apply()</code>, you can simply call
203         * {@link #commit} from <code>apply()</code>.
204         */
205        void apply();
206    }
207
208    /**
209     * Retrieve all values from the preferences.
210     *
211     * @return Returns a map containing a list of pairs key/value representing
212     * the preferences.
213     *
214     * @throws NullPointerException
215     */
216    Map<String, ?> getAll();
217
218    /**
219     * Retrieve a String value from the preferences.
220     *
221     * @param key The name of the preference to retrieve.
222     * @param defValue Value to return if this preference does not exist.
223     *
224     * @return Returns the preference value if it exists, or defValue.  Throws
225     * ClassCastException if there is a preference with this name that is not
226     * a String.
227     *
228     * @throws ClassCastException
229     */
230    String getString(String key, String defValue);
231
232    /**
233     * Retrieve an int value from the preferences.
234     *
235     * @param key The name of the preference to retrieve.
236     * @param defValue Value to return if this preference does not exist.
237     *
238     * @return Returns the preference value if it exists, or defValue.  Throws
239     * ClassCastException if there is a preference with this name that is not
240     * an int.
241     *
242     * @throws ClassCastException
243     */
244    int getInt(String key, int defValue);
245
246    /**
247     * Retrieve a long value from the preferences.
248     *
249     * @param key The name of the preference to retrieve.
250     * @param defValue Value to return if this preference does not exist.
251     *
252     * @return Returns the preference value if it exists, or defValue.  Throws
253     * ClassCastException if there is a preference with this name that is not
254     * a long.
255     *
256     * @throws ClassCastException
257     */
258    long getLong(String key, long defValue);
259
260    /**
261     * Retrieve a float value from the preferences.
262     *
263     * @param key The name of the preference to retrieve.
264     * @param defValue Value to return if this preference does not exist.
265     *
266     * @return Returns the preference value if it exists, or defValue.  Throws
267     * ClassCastException if there is a preference with this name that is not
268     * a float.
269     *
270     * @throws ClassCastException
271     */
272    float getFloat(String key, float defValue);
273
274    /**
275     * Retrieve a boolean value from the preferences.
276     *
277     * @param key The name of the preference to retrieve.
278     * @param defValue Value to return if this preference does not exist.
279     *
280     * @return Returns the preference value if it exists, or defValue.  Throws
281     * ClassCastException if there is a preference with this name that is not
282     * a boolean.
283     *
284     * @throws ClassCastException
285     */
286    boolean getBoolean(String key, boolean defValue);
287
288    /**
289     * Checks whether the preferences contains a preference.
290     *
291     * @param key The name of the preference to check.
292     * @return Returns true if the preference exists in the preferences,
293     *         otherwise false.
294     */
295    boolean contains(String key);
296
297    /**
298     * Create a new Editor for these preferences, through which you can make
299     * modifications to the data in the preferences and atomically commit those
300     * changes back to the SharedPreferences object.
301     *
302     * <p>Note that you <em>must</em> call {@link Editor#commit} to have any
303     * changes you perform in the Editor actually show up in the
304     * SharedPreferences.
305     *
306     * @return Returns a new instance of the {@link Editor} interface, allowing
307     * you to modify the values in this SharedPreferences object.
308     */
309    Editor edit();
310
311    /**
312     * Registers a callback to be invoked when a change happens to a preference.
313     *
314     * @param listener The callback that will run.
315     * @see #unregisterOnSharedPreferenceChangeListener
316     */
317    void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
318
319    /**
320     * Unregisters a previous callback.
321     *
322     * @param listener The callback that should be unregistered.
323     * @see #registerOnSharedPreferenceChangeListener
324     */
325    void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
326}
327