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}