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 public interface PreferenceDataStore { 44 45 /** 46 * Set a String value to the data store. 47 * 48 * <p>Once the value is set the data store is responsible for holding it. 49 * 50 * @param key The name of the preference to modify. 51 * @param value The new value for the preference. 52 * @see #getString(String, String) 53 */ 54 default void putString(String key, @Nullable String value) { 55 throw new UnsupportedOperationException("Not implemented on this data store"); 56 } 57 58 /** 59 * Set a set of String value to the data store. 60 * 61 * <p>Once the value is set the data store is responsible for holding it. 62 * 63 * @param key The name of the preference to modify. 64 * @param values The set of new values for the preference. 65 * @see #getStringSet(String, Set) 66 */ 67 default void putStringSet(String key, @Nullable Set<String> values) { 68 throw new UnsupportedOperationException("Not implemented on this data store"); 69 } 70 71 /** 72 * Set an int value to the data store. 73 * 74 * <p>Once the value is set the data store is responsible for holding it. 75 * 76 * @param key The name of the preference to modify. 77 * @param value The new value for the preference. 78 * @see #getInt(String, int) 79 */ 80 default void putInt(String key, int value) { 81 throw new UnsupportedOperationException("Not implemented on this data store"); 82 } 83 84 /** 85 * Set a long value to the data store. 86 * 87 * <p>Once the value is set the data store is responsible for holding it. 88 * 89 * @param key The name of the preference to modify. 90 * @param value The new value for the preference. 91 * @see #getLong(String, long) 92 */ 93 default void putLong(String key, long value) { 94 throw new UnsupportedOperationException("Not implemented on this data store"); 95 } 96 97 /** 98 * Set a float value to the data store. 99 * 100 * <p>Once the value is set the data store is responsible for holding it. 101 * 102 * @param key The name of the preference to modify. 103 * @param value The new value for the preference. 104 * @see #getFloat(String, float) 105 */ 106 default void putFloat(String key, float value) { 107 throw new UnsupportedOperationException("Not implemented on this data store"); 108 } 109 110 /** 111 * Set a boolean value to the data store. 112 * 113 * <p>Once the value is set the data store is responsible for holding it. 114 * 115 * @param key The name of the preference to modify. 116 * @param value The new value for the preference. 117 * @see #getBoolean(String, boolean) 118 */ 119 default void putBoolean(String key, boolean value) { 120 throw new UnsupportedOperationException("Not implemented on this data store"); 121 } 122 123 /** 124 * Retrieve a String value from the data store. 125 * 126 * @param key The name of the preference to retrieve. 127 * @param defValue Value to return if this preference does not exist. 128 * @see #putString(String, String) 129 */ 130 @Nullable 131 default String getString(String key, @Nullable String defValue) { 132 return defValue; 133 } 134 135 /** 136 * Retrieve a set of String values from the data store. 137 * 138 * @param key The name of the preference to retrieve. 139 * @param defValues Values to return if this preference does not exist. 140 * @see #putStringSet(String, Set) 141 */ 142 @Nullable 143 default Set<String> getStringSet(String key, @Nullable Set<String> defValues) { 144 return defValues; 145 } 146 147 /** 148 * Retrieve an int value from the data store. 149 * 150 * @param key The name of the preference to retrieve. 151 * @param defValue Value to return if this preference does not exist. 152 * @see #putInt(String, int) 153 */ 154 default int getInt(String key, int defValue) { 155 return defValue; 156 } 157 158 /** 159 * Retrieve a long value from the data store. 160 * 161 * @param key The name of the preference to retrieve. 162 * @param defValue Value to return if this preference does not exist. 163 * @see #putLong(String, long) 164 */ 165 default long getLong(String key, long defValue) { 166 return defValue; 167 } 168 169 /** 170 * Retrieve a float value from the data store. 171 * 172 * @param key The name of the preference to retrieve. 173 * @param defValue Value to return if this preference does not exist. 174 * @see #putFloat(String, float) 175 */ 176 default float getFloat(String key, float defValue) { 177 return defValue; 178 } 179 180 /** 181 * Retrieve a boolean value from the data store. 182 * 183 * @param key The name of the preference to retrieve. 184 * @param defValue Value to return if this preference does not exist. 185 * @see #getBoolean(String, boolean) 186 */ 187 default boolean getBoolean(String key, boolean defValue) { 188 return defValue; 189 } 190 } 191