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

      • main

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

        public static 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 File getPreferenceFile()
        Returns the user preferences file (preferences.xml).
        Returns:
        The user preferences file (preferences.xml)
      • getDefaultsCacheFile

        public File getDefaultsCacheFile()
        Returns the cache file for default preferences.
        Returns:
        the cache file for default preferences
      • getPluginsDirectory

        public File getPluginsDirectory()
        Returns the user plugin directory.
        Returns:
        The user plugin directory
      • getAllPossiblePreferenceDirs

        public static Collection<StringgetAllPossiblePreferenceDirs()
        Returns a set of all existing directories where resources could be stored.
        Returns:
        A set of all existing directories where resources could be stored.
      • save

        public void save()
                  throws IOException
        Called after every put. In case of a problem, do nothing but output the error in log.
        Throws:
        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​(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​(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​(String key,
                                                   T def,
                                                   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 Set<StringgetKeySet()
        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
      • getOnlinePluginSites

        public Collection<StringgetOnlinePluginSites()
        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​(Collection<String> sites)
        Sets the collection of plugin site URLs.
        Parameters:
        sites - the site URLs
      • toXML

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

        public String toXML​(Collection<Map.Entry<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
      • 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