Package resources

Class RawSettings

  • public class RawSettings
extends java.lang.Object
    Provides low-level access to the global and user settings tables. This class is used primarily to initialize settings during application startup. For general purpose setting access, use the abstractions provided by Settings.
    Since:
    3.0
    Author:
    Chris Jennings

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String getDefaultSettingValue​(java.lang.String key)
      Returns the value of a setting key in the default setting data.
      static java.lang.String getSetting​(java.lang.String key)
      Returns the inherited value of the setting key, or null if it is not defined.
      static java.lang.String getUserSetting​(java.lang.String key)
      Returns the value of a user setting.
      static void loadGlobalSettings​(java.lang.String resource)
      Merge settings from a resource file into the global settings table.
      static boolean migratePreferences()
      This is called during startup sometime after readUserSettings() is called.
      static java.lang.String obfuscate​(java.lang.String clearText)
      Obfuscates a string.
      static void readUserSettings()
      This method is called during application startup to load the user settings from the preferences file.
      static void removeUserSetting​(java.lang.String key)
      Removes a key from user settings.
      static void setGlobalSetting​(java.lang.String key, java.lang.String value)
      Sets the value of a global setting.
      static void setUserSetting​(java.lang.String key, java.lang.String value)
      Sets the value of a key in the user settings table.
      static java.lang.String unobfuscate​(java.lang.String obfuscatedText)
      Recovers the original text of an obfuscated string.
      static void writeUserSettings()
      Calling this method schedules the user settings to be written to the preference file in the near future.
      static void writeUserSettingsImmediately()
      Writes the user settings to the preference file immediately.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getSetting

        public static java.lang.String getSetting​(java.lang.String key)
        Returns the inherited value of the setting key, or null if it is not defined. This method will search both user settings and the global settings table, returning the first hit.
        Parameters:
        key - the setting key to return the value of
        Returns:
        the value of the key, or null
        Throws:
        java.lang.NullPointerException - if key is null

      • getUserSetting

        public static java.lang.String getUserSetting​(java.lang.String key)
        Returns the value of a user setting. If the key is not defined in the user settings table, null will be returned. The global settings table is never consulted.
        Parameters:
        key - the user setting key to return the value of
        Returns:
        the value of the key, or null
        Throws:
        java.lang.NullPointerException - if key is null

      • setUserSetting

        public static void setUserSetting​(java.lang.String key,
                                  java.lang.String value)
        Sets the value of a key in the user settings table.
        Parameters:
        key - the key to set
        value - the new value to set for the key
        Throws:
        java.lang.NullPointerException - if key or value is null

      • removeUserSetting

        public static void removeUserSetting​(java.lang.String key)
        Removes a key from user settings. If the key has a global value, it will revert to that value.
        Parameters:
        key - the user setting key to remove
        Throws:
        java.lang.NullPointerException - if key is null

      • readUserSettings

        public static void readUserSettings()
        This method is called during application startup to load the user settings from the preferences file. It is declared public in order to cross a package boundary, but it should not be called by user code.

      • writeUserSettings

        public static void writeUserSettings()
        Calling this method schedules the user settings to be written to the preference file in the near future. Call this method after changing a user preference so that the change is saved in the event that the application does not terminate normally. Because this method only schedules an update, it returns very quickly. This means that it can be called very often in response to user action even if the preferences are written to an unusually slow device.

      • writeUserSettingsImmediately

        public static void writeUserSettingsImmediately()
        Writes the user settings to the preference file immediately. This method is called during application shutdown to ensure that a final copy of any changes gets written. To store changes to user preferences at other times, call writeUserSettings().

      • loadGlobalSettings

        public static void loadGlobalSettings​(java.lang.String resource)
        Merge settings from a resource file into the global settings table. These settings will be visible from every context, including all game components (although their value may also be overridden).
        Parameters:
        resource - the resource file to read settings from
        Throws:
        java.lang.NullPointerException - if resource is null

      • getDefaultSettingValue

        public static java.lang.String getDefaultSettingValue​(java.lang.String key)
        Returns the value of a setting key in the default setting data.
        Parameters:
        key - the setting key to search for in the default setting data
        Returns:
        the default value of the key, or null

      • setGlobalSetting

        public static void setGlobalSetting​(java.lang.String key,
                                    java.lang.String value)
        Sets the value of a global setting. This setting will not persist after the application terminates. Moreover, if a user setting is defined with the same key name, it will take precedence over this one.
        Parameters:
        key - the key to set
        value - the new value to set for the key
        Throws:
        java.lang.NullPointerException - if key or value is null

      • migratePreferences

        public static boolean migratePreferences()
        This is called during startup sometime after readUserSettings() is called. If there was no user setting file to read settings from, or if the --migrateprefs option was set on the command line, this method will attempt to migrate compatible settings from a previous major version of the application.
        Returns:
        true if settings were migrated

      • obfuscate

        public static java.lang.String obfuscate​(java.lang.String clearText)
        Obfuscates a string. This converts a string into a form that is difficult for a human to associate with the original string without the help of a computer. This should be used as an additional layer of protection if you intend to store private information in the user's settings. The primary protection for such information is the file system permissions: a user's settings file should be owned by that user and should not be readable by other users. Obfuscating the private text is an additional precaution to protect the text from being read by a casual observer should the value happen to be displayed (for example, if the user's settings file is open in a text editor on the screen).

        This is not intended to be a secure encryption method. The original string can be readily recovered by passing the obfuscated string to unobfuscate(java.lang.String).

        Parameters:
        clearText - the text to obfuscate
        Returns:
        the obfuscated version of the text
        Throws:
        java.lang.NullPointerException - if the clear text string is null
        See Also:
        unobfuscate(java.lang.String)

      • unobfuscate

        public static java.lang.String unobfuscate​(java.lang.String obfuscatedText)
        Recovers the original text of an obfuscated string.
        Parameters:
        obfuscatedText - the obfuscated string
        Returns:
        the original clear text
        Throws:
        java.lang.NullPointerException - if the obfuscated string is null
        See Also:
        obfuscate(java.lang.String)