1 /*
2  * Copyright (C) 2016 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.preference;
18 
19 import android.annotation.Nullable;
20 
21 import java.util.Set;
22 
23 /**
24  * A data store interface to be implemented and provided to the Preferences framework. This can be
25  * used to replace the default {@link android.content.SharedPreferences}, if needed.
26  *
27  * <p>In most cases you want to use {@link android.content.SharedPreferences} as it is automatically
28  * backed up and migrated to new devices. However, providing custom data store to preferences can be
29  * useful if your app stores its preferences in a local db, cloud or they are device specific like
30  * "Developer settings". It might be also useful when you want to use the preferences UI but
31  * the data are not supposed to be stored at all because they are valid per session only.
32  *
33  * <p>Once a put method is called it is full responsibility of the data store implementation to
34  * safely store the given values. Time expensive operations need to be done in the background to
35  * prevent from blocking the UI. You also need to have a plan on how to serialize the data in case
36  * the activity holding this object gets destroyed.
37  *
38  * <p>By default, all "put" methods throw {@link UnsupportedOperationException}.
39  *
40  * @see Preference#setPreferenceDataStore(PreferenceDataStore)
41  * @see PreferenceManager#setPreferenceDataStore(PreferenceDataStore)
42  *
43  * @deprecated Use the <a href="{@docRoot}jetpack/androidx.html">AndroidX</a>
44  *      <a href="{@docRoot}reference/androidx/preference/package-summary.html">
45  *      Preference Library</a> for consistent behavior across all devices. For more information on
46  *      using the AndroidX Preference Library see
47  *      <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.
48  */
49 @Deprecated
50 public interface PreferenceDataStore {
51 
52     /**
53      * Set a String value to the data store.
54      *
55      * <p>Once the value is set the data store is responsible for holding it.
56      *
57      * @param key The name of the preference to modify.
58      * @param value The new value for the preference.
59      * @see #getString(String, String)
60      */
putString(String key, @Nullable String value)61     default void putString(String key, @Nullable String value) {
62         throw new UnsupportedOperationException("Not implemented on this data store");
63     }
64 
65     /**
66      * Set a set of String value to the data store.
67      *
68      * <p>Once the value is set the data store is responsible for holding it.
69      *
70      * @param key The name of the preference to modify.
71      * @param values The set of new values for the preference.
72      * @see #getStringSet(String, Set)
73      */
putStringSet(String key, @Nullable Set<String> values)74     default void putStringSet(String key, @Nullable Set<String> values) {
75         throw new UnsupportedOperationException("Not implemented on this data store");
76     }
77 
78     /**
79      * Set an int value to the data store.
80      *
81      * <p>Once the value is set the data store is responsible for holding it.
82      *
83      * @param key The name of the preference to modify.
84      * @param value The new value for the preference.
85      * @see #getInt(String, int)
86      */
putInt(String key, int value)87     default void putInt(String key, int value) {
88         throw new UnsupportedOperationException("Not implemented on this data store");
89     }
90 
91     /**
92      * Set a long value to the data store.
93      *
94      * <p>Once the value is set the data store is responsible for holding it.
95      *
96      * @param key The name of the preference to modify.
97      * @param value The new value for the preference.
98      * @see #getLong(String, long)
99      */
putLong(String key, long value)100     default void putLong(String key, long value) {
101         throw new UnsupportedOperationException("Not implemented on this data store");
102     }
103 
104     /**
105      * Set a float value to the data store.
106      *
107      * <p>Once the value is set the data store is responsible for holding it.
108      *
109      * @param key The name of the preference to modify.
110      * @param value The new value for the preference.
111      * @see #getFloat(String, float)
112      */
putFloat(String key, float value)113     default void putFloat(String key, float value) {
114         throw new UnsupportedOperationException("Not implemented on this data store");
115     }
116 
117     /**
118      * Set a boolean value to the data store.
119      *
120      * <p>Once the value is set the data store is responsible for holding it.
121      *
122      * @param key The name of the preference to modify.
123      * @param value The new value for the preference.
124      * @see #getBoolean(String, boolean)
125      */
putBoolean(String key, boolean value)126     default void putBoolean(String key, boolean value) {
127         throw new UnsupportedOperationException("Not implemented on this data store");
128     }
129 
130     /**
131      * Retrieve a String value from the data store.
132      *
133      * @param key The name of the preference to retrieve.
134      * @param defValue Value to return if this preference does not exist.
135      * @see #putString(String, String)
136      */
137     @Nullable
getString(String key, @Nullable String defValue)138     default String getString(String key, @Nullable String defValue) {
139         return defValue;
140     }
141 
142     /**
143      * Retrieve a set of String values from the data store.
144      *
145      * @param key The name of the preference to retrieve.
146      * @param defValues Values to return if this preference does not exist.
147      * @see #putStringSet(String, Set)
148      */
149     @Nullable
getStringSet(String key, @Nullable Set<String> defValues)150     default Set<String> getStringSet(String key, @Nullable Set<String> defValues) {
151         return defValues;
152     }
153 
154     /**
155      * Retrieve an int value from the data store.
156      *
157      * @param key The name of the preference to retrieve.
158      * @param defValue Value to return if this preference does not exist.
159      * @see #putInt(String, int)
160      */
getInt(String key, int defValue)161     default int getInt(String key, int defValue) {
162         return defValue;
163     }
164 
165     /**
166      * Retrieve a long value from the data store.
167      *
168      * @param key The name of the preference to retrieve.
169      * @param defValue Value to return if this preference does not exist.
170      * @see #putLong(String, long)
171      */
getLong(String key, long defValue)172     default long getLong(String key, long defValue) {
173         return defValue;
174     }
175 
176     /**
177      * Retrieve a float value from the data store.
178      *
179      * @param key The name of the preference to retrieve.
180      * @param defValue Value to return if this preference does not exist.
181      * @see #putFloat(String, float)
182      */
getFloat(String key, float defValue)183     default float getFloat(String key, float defValue) {
184         return defValue;
185     }
186 
187     /**
188      * Retrieve a boolean value from the data store.
189      *
190      * @param key The name of the preference to retrieve.
191      * @param defValue Value to return if this preference does not exist.
192      * @see #getBoolean(String, boolean)
193      */
getBoolean(String key, boolean defValue)194     default boolean getBoolean(String key, boolean defValue) {
195         return defValue;
196     }
197 }
198