001// License: GPL. For details, see LICENSE file. 002package org.openstreetmap.josm.spi.preferences; 003 004import java.util.Collections; 005import java.util.List; 006import java.util.Map; 007import java.util.Set; 008 009/** 010 * Interface for preference handling. 011 * 012 * Allows to save and retrieve user defined settings. The backend storage depends 013 * on the implementation. 014 * @since 12847 015 */ 016public interface IPreferences { 017 018 /** 019 * Adds a new preferences listener. 020 * @param listener The listener to add 021 */ 022 void addPreferenceChangeListener(PreferenceChangedListener listener); 023 024 /** 025 * Removes a preferences listener. 026 * @param listener The listener to remove 027 */ 028 void removePreferenceChangeListener(PreferenceChangedListener listener); 029 030 /** 031 * Adds a listener that only listens to changes in one preference 032 * @param key The preference key to listen to 033 * @param listener The listener to add. 034 */ 035 void addKeyPreferenceChangeListener(String key, PreferenceChangedListener listener); 036 037 /** 038 * Removes a listener that only listens to changes in one preference 039 * @param key The preference key to listen to 040 * @param listener The listener to add. 041 */ 042 void removeKeyPreferenceChangeListener(String key, PreferenceChangedListener listener); 043 044 /** 045 * Get settings value for a certain key and provide a default value. 046 * @param key the identifier for the setting 047 * @param def the default value. For each call of get() with a given key, the 048 * default value must be the same. {@code def} may be null. 049 * @return the corresponding value if the property has been set before, {@code def} otherwise 050 */ 051 String get(String key, String def); 052 053 /** 054 * Get settings value for a certain key. 055 * @param key the identifier for the setting 056 * @return "" if there is nothing set for the preference key, the corresponding value otherwise. The result is not null. 057 */ 058 default String get(final String key) { 059 return get(key, ""); 060 } 061 062 /** 063 * Set a value for a certain setting. 064 * @param key the unique identifier for the setting 065 * @param value the value of the setting. Can be null or "" which both removes the key-value entry. 066 * @return {@code true}, if something has changed (i.e. value is different than before) 067 */ 068 boolean put(String key, String value); 069 070 /** 071 * Gets a boolean preference 072 * @param key The preference key 073 * @param def The default value to use 074 * @return The boolean, <code>false</code> if it could not be parsed, the default value if it is unset 075 */ 076 boolean getBoolean(String key, boolean def); 077 078 /** 079 * Gets a boolean preference 080 * @param key The preference key 081 * @return The boolean or <code>false</code> if it could not be parsed 082 */ 083 default boolean getBoolean(String key) { 084 return getBoolean(key, false); 085 } 086 087 /** 088 * Set a boolean value for a certain setting. 089 * @param key the unique identifier for the setting 090 * @param value The new value 091 * @return {@code true}, if something has changed (i.e. value is different than before) 092 * @since 12840 093 */ 094 boolean putBoolean(String key, boolean value); 095 096 /** 097 * Gets an integer preference 098 * @param key The preference key 099 * @param def The default value to use 100 * @return The integer 101 * @since 12840 102 */ 103 int getInt(String key, int def); 104 105 /** 106 * Set an integer value for a certain setting. 107 * @param key the unique identifier for the setting 108 * @param value The new value 109 * @return {@code true}, if something has changed (i.e. value is different than before) 110 * @since 12840 111 */ 112 boolean putInt(String key, int value); 113 114 /** 115 * Gets a long preference 116 * @param key The preference key 117 * @param def The default value to use 118 * @return The long value or the default value if it could not be parsed 119 */ 120 long getLong(String key, long def); 121 122 /** 123 * Set a long value for a certain setting. 124 * @param key the unique identifier for the setting 125 * @param value The new value 126 * @return {@code true}, if something has changed (i.e. value is different than before) 127 */ 128 boolean putLong(String key, long value); 129 130 /** 131 * Gets a double preference 132 * @param key The preference key 133 * @param def The default value to use 134 * @return The double value or the default value if it could not be parsed 135 */ 136 double getDouble(String key, double def); 137 138 /** 139 * Set a boolean value for a certain setting. 140 * @param key the unique identifier for the setting 141 * @param value The new value 142 * @return {@code true}, if something has changed (i.e. value is different than before) 143 * @since 12840 144 */ 145 boolean putDouble(String key, double value); 146 147 /** 148 * Get a list of values for a certain key 149 * @param key the identifier for the setting 150 * @param def the default value. 151 * @return the corresponding value if the property has been set before, {@code def} otherwise 152 * @since 12840 153 */ 154 List<String> getList(String key, List<String> def); 155 156 /** 157 * Get a list of values for a certain key 158 * @param key the identifier for the setting 159 * @return the corresponding value if the property has been set before, an 160 * empty list otherwise. 161 * @since 12840 162 */ 163 default List<String> getList(String key) { 164 List<String> val = getList(key, null); 165 return val == null ? Collections.emptyList() : val; 166 } 167 168 /** 169 * Set a list of values for a certain key. 170 * @param key the identifier for the setting 171 * @param value The new value 172 * @return {@code true}, if something has changed (i.e. value is different than before) 173 * @since 12840 174 */ 175 boolean putList(String key, List<String> value); 176 177 /** 178 * Get an array of values (list of lists) for a certain key 179 * @param key the identifier for the setting 180 * @param def the default value. 181 * @return the corresponding value if the property has been set before, {@code def} otherwise 182 * @since 12840 183 */ 184 List<List<String>> getListOfLists(String key, List<List<String>> def); 185 186 /** 187 * Get an array of values (list of lists) for a certain key 188 * @param key the identifier for the setting 189 * @return the corresponding value if the property has been set before, an 190 * empty list otherwise 191 * @since 12840 192 */ 193 default List<List<String>> getListOfLists(String key) { 194 List<List<String>> val = getListOfLists(key, null); 195 return val == null ? Collections.emptyList() : val; 196 } 197 198 /** 199 * Set an array of values (list of lists) for a certain key. 200 * @param key the identifier for the setting 201 * @param value the new value 202 * @return {@code true}, if something has changed (i.e. value is different than before) 203 * @since 12840 204 */ 205 boolean putListOfLists(String key, List<List<String>> value); 206 207 /** 208 * Gets a list of key/value maps. 209 * @param key the key to search at 210 * @param def the default value to use 211 * @return the corresponding value if the property has been set before, {@code def} otherwise 212 * @since 12840 213 */ 214 List<Map<String, String>> getListOfMaps(String key, List<Map<String, String>> def); 215 216 /** 217 * Gets a list of key/value maps. 218 * @param key the key to search at 219 * @return the corresponding value if the property has been set before, an 220 * empty list otherwise 221 * @since 12840 222 */ 223 default List<Map<String, String>> getListOfMaps(String key) { 224 List<Map<String, String>> val = getListOfMaps(key, null); 225 return val == null ? Collections.emptyList() : val; 226 } 227 228 /** 229 * Set an a list of key/value maps. 230 * @param key the key to store the list in 231 * @param value a list of key/value maps 232 * @return <code>true</code> if the value was changed 233 * @since 12840 234 */ 235 boolean putListOfMaps(String key, List<Map<String, String>> value); 236 237 /** 238 * Get the set of all keys that are mapped to a value in this preferences. 239 * @return the set of all keys 240 */ 241 Set<String> getKeySet(); 242}