SharedPreferences.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c 
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         * @param sharedPreferences The {@link SharedPreferences} that received
45         *            the change.
46         * @param key The key of the preference that was changed, added, or
47         *            removed.
48         */
49        void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key);
50    }
51
52    /**
53     * Interface used for modifying values in a {@link SharedPreferences}
54     * object.  All changes you make in an editor are batched, and not copied
55     * back to the original {@link SharedPreferences} or persistent storage
56     * until you call {@link #commit}.
57     */
58    public interface Editor {
59        /**
60         * Set a String value in the preferences editor, to be written back once
61         * {@link #commit} is called.
62         *
63         * @param key The name of the preference to modify.
64         * @param value The new value for the preference.
65         *
66         * @return Returns a reference to the same Editor object, so you can
67         * chain put calls together.
68         */
69        Editor putString(String key, String value);
70
71        /**
72         * Set an int value in the preferences editor, to be written back once
73         * {@link #commit} is called.
74         *
75         * @param key The name of the preference to modify.
76         * @param value The new value for the preference.
77         *
78         * @return Returns a reference to the same Editor object, so you can
79         * chain put calls together.
80         */
81        Editor putInt(String key, int value);
82
83        /**
84         * Set a long value in the preferences editor, to be written back once
85         * {@link #commit} is called.
86         *
87         * @param key The name of the preference to modify.
88         * @param value The new value for the preference.
89         *
90         * @return Returns a reference to the same Editor object, so you can
91         * chain put calls together.
92         */
93        Editor putLong(String key, long value);
94
95        /**
96         * Set a float value in the preferences editor, to be written back once
97         * {@link #commit} is called.
98         *
99         * @param key The name of the preference to modify.
100         * @param value The new value for the preference.
101         *
102         * @return Returns a reference to the same Editor object, so you can
103         * chain put calls together.
104         */
105        Editor putFloat(String key, float value);
106
107        /**
108         * Set a boolean value in the preferences editor, to be written back
109         * once {@link #commit} is called.
110         *
111         * @param key The name of the preference to modify.
112         * @param value The new value for the preference.
113         *
114         * @return Returns a reference to the same Editor object, so you can
115         * chain put calls together.
116         */
117        Editor putBoolean(String key, boolean value);
118
119        /**
120         * Mark in the editor that a preference value should be removed, which
121         * will be done in the actual preferences once {@link #commit} is
122         * called.
123         *
124         * <p>Note that when committing back to the preferences, all removals
125         * are done first, regardless of whether you called remove before
126         * or after put methods on this editor.
127         *
128         * @param key The name of the preference to remove.
129         *
130         * @return Returns a reference to the same Editor object, so you can
131         * chain put calls together.
132         */
133        Editor remove(String key);
134
135        /**
136         * Mark in the editor to remove <em>all</em> values from the
137         * preferences.  Once commit is called, the only remaining preferences
138         * will be any that you have defined in this editor.
139         *
140         * <p>Note that when committing back to the preferences, the clear
141         * is done first, regardless of whether you called clear before
142         * or after put methods on this editor.
143         *
144         * @return Returns a reference to the same Editor object, so you can
145         * chain put calls together.
146         */
147        Editor clear();
148
149        /**
150         * Commit your preferences changes back from this Editor to the
151         * {@link SharedPreferences} object it is editing.  This atomically
152         * performs the requested modifications, replacing whatever is currently
153         * in the SharedPreferences.
154         *
155         * <p>Note that when two editors are modifying preferences at the same
156         * time, the last one to call commit wins.
157         *
158         * @return Returns true if the new values were successfully written
159         * to persistent storage.
160         */
161        boolean commit();
162    }
163
164    /**
165     * Retrieve all values from the preferences.
166     *
167     * @return Returns a map containing a list of pairs key/value representing
168     * the preferences.
169     *
170     * @throws NullPointerException
171     */
172    Map<String, ?> getAll();
173
174    /**
175     * Retrieve a String value from the preferences.
176     *
177     * @param key The name of the preference to retrieve.
178     * @param defValue Value to return if this preference does not exist.
179     *
180     * @return Returns the preference value if it exists, or defValue.  Throws
181     * ClassCastException if there is a preference with this name that is not
182     * a String.
183     *
184     * @throws ClassCastException
185     */
186    String getString(String key, String defValue);
187
188    /**
189     * Retrieve an int value from the preferences.
190     *
191     * @param key The name of the preference to retrieve.
192     * @param defValue Value to return if this preference does not exist.
193     *
194     * @return Returns the preference value if it exists, or defValue.  Throws
195     * ClassCastException if there is a preference with this name that is not
196     * an int.
197     *
198     * @throws ClassCastException
199     */
200    int getInt(String key, int defValue);
201
202    /**
203     * Retrieve a long value from the preferences.
204     *
205     * @param key The name of the preference to retrieve.
206     * @param defValue Value to return if this preference does not exist.
207     *
208     * @return Returns the preference value if it exists, or defValue.  Throws
209     * ClassCastException if there is a preference with this name that is not
210     * a long.
211     *
212     * @throws ClassCastException
213     */
214    long getLong(String key, long defValue);
215
216    /**
217     * Retrieve a float value from the preferences.
218     *
219     * @param key The name of the preference to retrieve.
220     * @param defValue Value to return if this preference does not exist.
221     *
222     * @return Returns the preference value if it exists, or defValue.  Throws
223     * ClassCastException if there is a preference with this name that is not
224     * a float.
225     *
226     * @throws ClassCastException
227     */
228    float getFloat(String key, float defValue);
229
230    /**
231     * Retrieve a boolean value from the preferences.
232     *
233     * @param key The name of the preference to retrieve.
234     * @param defValue Value to return if this preference does not exist.
235     *
236     * @return Returns the preference value if it exists, or defValue.  Throws
237     * ClassCastException if there is a preference with this name that is not
238     * a boolean.
239     *
240     * @throws ClassCastException
241     */
242    boolean getBoolean(String key, boolean defValue);
243
244    /**
245     * Checks whether the preferences contains a preference.
246     *
247     * @param key The name of the preference to check.
248     * @return Returns true if the preference exists in the preferences,
249     *         otherwise false.
250     */
251    boolean contains(String key);
252
253    /**
254     * Create a new Editor for these preferences, through which you can make
255     * modifications to the data in the preferences and atomically commit those
256     * changes back to the SharedPreferences object.
257     *
258     * <p>Note that you <em>must</em> call {@link Editor#commit} to have any
259     * changes you perform in the Editor actually show up in the
260     * SharedPreferences.
261     *
262     * @return Returns a new instance of the {@link Editor} interface, allowing
263     * you to modify the values in this SharedPreferences object.
264     */
265    Editor edit();
266
267    /**
268     * Registers a callback to be invoked when a change happens to a preference.
269     *
270     * @param listener The callback that will run.
271     * @see #unregisterOnSharedPreferenceChangeListener
272     */
273    void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
274
275    /**
276     * Unregisters a previous callback.
277     *
278     * @param listener The callback that should be unregistered.
279     * @see #registerOnSharedPreferenceChangeListener
280     */
281    void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
282}
283