Package org.openstreetmap.josm.data

Class Preferences

  • All Implemented Interfaces:
    IPreferences
    public class Preferences
extends AbstractPreferences
    This class holds all preferences for JOSM. Other classes can register their beloved properties here. All properties will be saved upon set-access. Each property is a key=setting pair, where key is a String and setting can be one of 4 types: string, list, list of lists and list of maps. In addition, each key has a unique default value that is set when the value is first accessed using one of the get...() methods. You can use the same preference key in different parts of the code, but the default value must be the same everywhere. A default value of null means, the setting has been requested, but no default value was set. This is used in advanced preferences to present a list off all possible settings. At the moment, you cannot put the empty string for string properties. put(key, "") means, the property is removed.
    Since:
    74

    • Constructor Detail

      • Preferences

        public Preferences()
        Constructs a new Preferences.

      • Preferences

        public Preferences​(IBaseDirectories dirs)
        Constructs a new Preferences.
        Parameters:
        dirs - the directories to use for saving the preferences

      • Preferences

        public Preferences​(Preferences pref)
        Constructs a new Preferences from an existing instance.
        Parameters:
        pref - existing preferences to copy
        Since:
        12634

    • Method Detail

      • getUpdatePrefKeys

        private static java.util.Map<java.lang.String,​java.lang.String> getUpdatePrefKeys()

      • main

        public static Preferences main()
        Returns the main (default) preferences instance.
        Returns:
        the main (default) preferences instance
        Since:
        14149

      • addKeyPreferenceChangeListener

        public void addKeyPreferenceChangeListener​(java.lang.String key,
                                           PreferenceChangedListener listener)
        Adds a listener that only listens to changes in one preference
        Parameters:
        key - The preference key to listen to
        listener - The listener to add.
        Since:
        12881

      • addWeakKeyPreferenceChangeListener

        public void addWeakKeyPreferenceChangeListener​(java.lang.String key,
                                               PreferenceChangedListener listener)
        Adds a weak listener that only listens to changes in one preference
        Parameters:
        key - The preference key to listen to
        listener - The listener to add.
        Since:
        10824

      • removeKeyPreferenceChangeListener

        public void removeKeyPreferenceChangeListener​(java.lang.String key,
                                              PreferenceChangedListener listener)
        Removes a listener that only listens to changes in one preference
        Parameters:
        key - The preference key to listen to
        listener - The listener to add.
        Since:
        12881

      • getJOSMDirectoryBaseName

        public static java.lang.String getJOSMDirectoryBaseName()
        Get the base name of the JOSM directories for preferences, cache and user data. Default value is "JOSM", unless overridden by system property "josm.dir.name".
        Returns:
        the base name of the JOSM directories for preferences, cache and user data

      • getDirs

        public IBaseDirectories getDirs()
        Get the base directories associated with this preference instance.
        Returns:
        the base directories

      • getPreferenceFile

        public java.io.File getPreferenceFile()
        Returns the user preferences file (preferences.xml).
        Returns:
        The user preferences file (preferences.xml)

      • getDefaultsCacheFile

        public java.io.File getDefaultsCacheFile()
        Returns the cache file for default preferences.
        Returns:
        the cache file for default preferences

      • getPluginsDirectory

        public java.io.File getPluginsDirectory()
        Returns the user plugin directory.
        Returns:
        The user plugin directory

      • addPossibleResourceDir

        private static void addPossibleResourceDir​(java.util.Set<java.lang.String> locations,
                                           java.lang.String s)

      • getAllPossiblePreferenceDirs

        public static java.util.Collection<java.lang.String> getAllPossiblePreferenceDirs()
        Returns a set of all existing directories where resources could be stored.
        Returns:
        A set of all existing directories where resources could be stored.

      • getAllNamedColors

        public java.util.Map<java.lang.String,​ColorInfo> getAllNamedColors()
        Get all named colors, including customized and the default ones.
        Returns:
        a map of all named colors (maps preference key to ColorInfo)

      • save

        public void save()
          throws java.io.IOException
        Called after every put. In case of a problem, do nothing but output the error in log.
        Throws:
        java.io.IOException - if any I/O error occurs

      • saveDefaults

        public void saveDefaults()
                  throws java.io.IOException
        Stores the defaults to the defaults file
        Throws:
        java.io.IOException - If the file could not be saved

      • save

        protected void save​(java.io.File prefFile,
                    java.util.stream.Stream<java.util.Map.Entry<java.lang.String,​Setting<?>>> settings,
                    boolean defaults)
             throws java.io.IOException
        Throws:
        java.io.IOException

      • checkFileValidity

        private static void checkFileValidity​(java.io.File file,
                                      Preferences.ThrowingConsumer<java.io.File,​java.io.IOException> consumer)
                               throws java.io.IOException
        Ensure that a preferences file is "ok" before copying/moving it over another preferences file
        Parameters:
        file - The file to check
        consumer - The consumer that will perform the copy/move action
        Throws:
        java.io.IOException - If there is an issue reading/writing the file

      • load

        protected void load()
             throws java.io.IOException,
                    org.xml.sax.SAXException,
                    javax.xml.stream.XMLStreamException
        Loads preferences from settings file.
        Throws:
        java.io.IOException - if any I/O error occurs while reading the file
        org.xml.sax.SAXException - if the settings file does not contain valid XML
        javax.xml.stream.XMLStreamException - if an XML error occurs while parsing the file (after validation)

      • loadDefaults

        protected void loadDefaults()
                     throws java.io.IOException,
                            javax.xml.stream.XMLStreamException,
                            org.xml.sax.SAXException
        Loads default preferences from default settings cache file. Discards entries older than MAX_AGE_DEFAULT_PREFERENCES.
        Throws:
        java.io.IOException - if any I/O error occurs while reading the file
        org.xml.sax.SAXException - if the settings file does not contain valid XML
        javax.xml.stream.XMLStreamException - if an XML error occurs while parsing the file (after validation)

      • fromXML

        public void fromXML​(java.io.Reader in)
             throws javax.xml.stream.XMLStreamException,
                    java.io.IOException
        Loads preferences from XML reader.
        Parameters:
        in - XML reader
        Throws:
        javax.xml.stream.XMLStreamException - if any XML stream error occurs
        java.io.IOException - if any I/O error occurs

      • init

        public void init​(boolean reset)
        Initializes preferences.
        Parameters:
        reset - if true, current settings file is replaced by the default one

      • resetToInitialState

        public void resetToInitialState()
        Resets the preferences to their initial state. This resets all values and file associations. The default values and listeners are not removed.

        It is meant to be called before init(boolean)

        Since:
        10876

      • resetToDefault

        public final void resetToDefault()
        Reset all values stored in this map to the default values. This clears the preferences.

      • putSetting

        public boolean putSetting​(java.lang.String key,
                          Setting<?> setting)
        Set a value for a certain setting. The changed setting is saved to the preference file immediately. Due to caching mechanisms on modern operating systems and hardware, this shouldn't be a performance problem.
        Specified by:
        putSetting in class AbstractPreferences
        Parameters:
        key - the unique identifier for the setting
        setting - the value of the setting. In case it is null, the key-value entry will be removed.
        Returns:
        true, if something has changed (i.e. value is different than before)

      • getSetting

        public Setting<?> getSetting​(java.lang.String key,
                             Setting<?> def)
        Get a setting of any type
        Parameters:
        key - The key for the setting
        def - The default value to use if it was not found
        Returns:
        The setting

      • getSetting

        public <T extends Setting<?>> T getSetting​(java.lang.String key,
                                           T def,
                                           java.lang.Class<T> klass)
        Get settings value for a certain key and provide default a value.
        Specified by:
        getSetting in class AbstractPreferences
        Type Parameters:
        T - the setting type
        Parameters:
        key - the identifier for the setting
        def - the default value. For each call of getSetting() with a given key, the default value must be the same. def must not be null, but the value of def can be null.
        klass - the setting type (same as T)
        Returns:
        the corresponding value if the property has been set before, def otherwise

      • getKeySet

        public java.util.Set<java.lang.String> getKeySet()
        Description copied from interface: IPreferences
        Get the set of all keys that are mapped to a value in this preferences.
        Returns:
        the set of all keys

      • getAllDefaults

        public java.util.Map<java.lang.String,​Setting<?>> getAllDefaults()
        Gets a map of all currently known defaults
        Returns:
        The map (key/setting)

      • getPluginSites

        public java.util.Collection<java.lang.String> getPluginSites()
        Replies the collection of plugin site URLs from where plugin lists can be downloaded.
        Returns:
        the collection of plugin site URLs
        See Also:
        getOnlinePluginSites()

      • getOnlinePluginSites

        public java.util.Collection<java.lang.String> getOnlinePluginSites()
        Returns the list of plugin sites available according to offline mode settings.
        Returns:
        the list of available plugin sites
        Since:
        8471

      • setPluginSites

        public void setPluginSites​(java.util.Collection<java.lang.String> sites)
        Sets the collection of plugin site URLs.
        Parameters:
        sites - the site URLs

      • toXML

        public java.lang.String toXML​(boolean nopass)
        Returns XML describing these preferences.
        Parameters:
        nopass - if password must be excluded
        Returns:
        XML

      • toXML

        public java.lang.String toXML​(java.util.Collection<java.util.Map.Entry<java.lang.String,​Setting<?>>> settings,
                              boolean nopass,
                              boolean defaults)
        Returns XML describing the given preferences.
        Parameters:
        settings - preferences settings
        nopass - if password must be excluded
        defaults - true, if default values are converted to XML, false for regular preferences
        Returns:
        XML

      • removeAndUpdateObsolete

        private void removeAndUpdateObsolete​(int loadedVersion)
        Removes and updates obsolete preference settings. If you throw out a once-used preference setting, add it to the list here with an expiry date (written as comment). If you see something with an expiry date in the past, remove it from the list.
        Parameters:
        loadedVersion - JOSM version when the preferences file was written

      • updateMapPaintKnownDefaults

        private void updateMapPaintKnownDefaults()
        Update the known defaults for the map paintstyles. This should be removed sometime after 2024-06-01.

      • enableSaveOnPut

        public final void enableSaveOnPut​(boolean enable)
        Enables or not the preferences file auto-save mechanism (save each time a setting is changed). This behaviour is enabled by default.
        Parameters:
        enable - if true, makes JOSM save preferences file each time a setting is changed
        Since:
        7085