Module bus.setting
Package org.miaixz.bus.setting

Class Setting

java.lang.Object
org.miaixz.bus.setting.magic.AbstractSetting
org.miaixz.bus.setting.Setting
All Implemented Interfaces:
Serializable, Map<String,String>, org.miaixz.bus.core.lang.getter.GroupedTypeGetter<CharSequence,CharSequence>, org.miaixz.bus.core.lang.getter.TypeGetter<CharSequence>
public class Setting extends AbstractSetting implements Map<String,String>
A utility class for handling .setting files, which are an enhanced version of Java's .properties files with backward compatibility.

Features:

  1. Supports variable substitution using the ${variable_name} syntax.
  2. Supports grouping of properties under section headers (e.g., [group_name]). Keys under a group are accessed as group.key.
  3. Treats lines starting with '#' as comments.
Note: The store methods do not preserve comments.
Since:
Java 17+
Author:
Kimi Liu
See Also:

  • Field Details

    • DEFAULT_CHARSET

      public static final Charset DEFAULT_CHARSET
      The default character set (UTF-8).

    • EXT_NAME

      public static final String EXT_NAME
      The default file extension for settings files.
      See Also:

    • charset

      protected Charset charset
      The character set for this settings instance.

    • isUseVariable

      protected boolean isUseVariable
      Whether variable substitution is enabled.

    • resource

      protected org.miaixz.bus.core.io.resource.Resource resource
      The resource representing the settings file.

  • Constructor Details

    • Setting

      public Setting()
      Constructs a new, empty Setting instance.

    • Setting

      public Setting(String path)
      Constructs a Setting by loading a file from a relative or absolute path.
      Parameters:
      path - The path to the settings file.

    • Setting

      public Setting(String path, boolean isUseVariable)
      Constructs a Setting by loading a file.
      Parameters:
      path - The path to the settings file.
      isUseVariable - true to enable variable substitution.

    • Setting

      public Setting(String path, Charset charset, boolean isUseVariable)
      Constructs a Setting by loading a file from the classpath.
      Parameters:
      path - The path to the file (relative or absolute).
      charset - The character set to use.
      isUseVariable - true to enable variable substitution.

    • Setting

      public Setting(File configFile, Charset charset, boolean isUseVariable)
      Constructs a Setting from a File.
      Parameters:
      configFile - The configuration file.
      charset - The character set to use.
      isUseVariable - true to enable variable substitution.

    • Setting

      public Setting(org.miaixz.bus.core.io.resource.Resource resource, Charset charset, boolean isUseVariable)
      Constructs a Setting from a Resource.
      Parameters:
      resource - The resource representing the settings file.
      charset - The character set to use.
      isUseVariable - true to enable variable substitution.

    • Setting

      public Setting(org.miaixz.bus.core.io.resource.Resource resource, Loader loader)
      Constructs a Setting from a Resource using a custom loader.
      Parameters:
      resource - The resource representing the settings file.
      loader - The custom loader to use for parsing.

  • Method Details

    • of

      public static Setting of()
      Creates a new, empty Setting instance for manual population.
      Returns:
      A new Setting instance.

    • load

      public Setting load()
      Reloads the configuration from the original resource file.
      Returns:
      This Setting instance for chaining.

    • autoLoad

      public void autoLoad()
      Enables automatic reloading of the configuration file when it changes on the filesystem.

    • autoLoad

      public void autoLoad(Consumer<Setting> callback)
      Enables automatic reloading of the configuration file when it changes, with a callback.
      Parameters:
      callback - A consumer to be called after the file has been successfully reloaded.

    • stopAutoLoad

      public void stopAutoLoad()
      Stops the automatic reloading of the configuration file.

    • getSettingUrl

      public URL getSettingUrl()
      Gets the URL of the loaded settings file.
      Returns:
      The URL of the settings file.

    • getSettingPath

      public String getSettingPath()
      Gets the file path of the loaded settings file.
      Returns:
      The path of the settings file.

    • size

      public int size()
      Specified by:
      size in interface Map<String,String>

    • getObjectByGroup

      public Object getObjectByGroup(CharSequence key, CharSequence group, Object defaultValue)
      Specified by:
      getObjectByGroup in interface org.miaixz.bus.core.lang.getter.GroupedTypeGetter<CharSequence,CharSequence>

    • getAndRemove

      public String getAndRemove(String... keys)
      Gets and removes a property value. It tries each key in the provided list until a non-null value is found, which is then returned and removed.
      Parameters:
      keys - A list of keys to try, often used for aliases.
      Returns:
      The string value, or null if no key is found.

    • getMap

      public Map<String,String> getMap(String group)
      Gets all key-value pairs for a specific group as a mutable map.
      Parameters:
      group - The group name.
      Returns:
      A map of the settings in the group.

    • getSetting

      public Setting getSetting(String group)
      Gets all settings under a specific group as a new Setting object.
      Parameters:
      group - The group name.
      Returns:
      A new Setting instance containing the properties of the group.

    • getProperties

      public Properties getProperties(String group)
      Gets all settings under a specific group as a Properties object.
      Parameters:
      group - The group name.
      Returns:
      A new Properties object.

    • getProps

      public Props getProps(String group)
      Gets all settings under a specific group as a Props object.
      Parameters:
      group - The group name.
      Returns:
      A new Props object.

    • store

      public void store()
      Stores the current settings to the original file, overwriting its content. This will not work if the file is inside a JAR.

    • store

      public void store(String absolutePath)
      Stores the current settings to a file at the specified absolute path.
      Parameters:
      absolutePath - The absolute path to the destination file.

    • store

      public void store(File file)
      Stores the current settings to the specified file.
      Parameters:
      file - The destination file.

    • toProps

      public Props toProps()
      Converts this Setting to a Props object, flattening the groups into keys with prefixes (e.g., "group.key").
      Returns:
      A Props object.

    • getGroupedMap

      public GroupedMap getGroupedMap()
      Gets the underlying GroupedMap that stores the settings.
      Returns:
      The underlying GroupedMap used for storage.

    • getGroups

      public List<String> getGroups()
      Gets a list of all group names defined in this setting.
      Returns:
      A list of all group names in this setting.

    • setVarRegex

      public Setting setVarRegex(String regex)
      Sets the regular expression for identifying variables.
      Parameters:
      regex - The regular expression.
      Returns:
      this Setting instance for chaining.

    • setLogIfNull

      public Setting setLogIfNull(boolean logIfNull)
      Sets whether to log a debug message when a requested key is not found.
      Parameters:
      logIfNull - true to enable logging.
      Returns:
      this Setting instance for chaining.

    • isEmpty

      public boolean isEmpty(String group)
      Checks if a specific group is empty.
      Parameters:
      group - The group name.
      Returns:
      true if the group is empty or does not exist.

    • containsKey

      public boolean containsKey(String group, String key)
      Checks if a specific group contains a given key.
      Parameters:
      group - The group name.
      key - The key.
      Returns:
      true if the key exists in the group.

    • containsValue

      public boolean containsValue(String group, String value)
      Checks if a specific group contains a given value.
      Parameters:
      group - The group name.
      value - The value.
      Returns:
      true if the value exists in the group.

    • putByGroup

      public String putByGroup(String key, String group, String value)
      Puts a key-value pair into a specific group.
      Parameters:
      key - The key.
      group - The group name.
      value - The value.
      Returns:
      The previous value associated with the key, or null.

    • remove

      public String remove(String group, Object key)
      Removes a key from a specific group.
      Parameters:
      group - The group name.
      key - The key to remove.
      Returns:
      The removed value, or null if not found.

    • putAll

      public Setting putAll(String group, Map<? extends String,? extends String> m)
      Puts all key-value pairs from a map into a specific group.
      Parameters:
      group - The group name.
      m - The map of key-value pairs.
      Returns:
      this Setting instance for chaining.

    • addSetting

      public Setting addSetting(Setting setting)
      Merges all groups and settings from another Setting instance into this one.
      Parameters:
      setting - The Setting instance to merge.
      Returns:
      this Setting instance for chaining.

    • clear

      public Setting clear(String group)
      Clears all key-value pairs from a specific group.
      Parameters:
      group - The group name.
      Returns:
      this Setting instance for chaining.

    • keySet

      public Set<String> keySet(String group)
      Returns a set of all keys within a specific group.
      Parameters:
      group - The group name.
      Returns:
      The set of keys.

    • values

      public Collection<String> values(String group)
      Returns a collection of all values within a specific group.
      Parameters:
      group - The group name.
      Returns:
      The collection of values.

    • entrySet

      public Set<Map.Entry<String,String>> entrySet(String group)
      Returns a set of all key-value entries within a specific group.
      Parameters:
      group - The group name.
      Returns:
      The set of entries.

    • set

      public Setting set(String key, String value)
      Sets a value in the default (empty) group.
      Parameters:
      key - The key.
      value - The value.
      Returns:
      this Setting instance for chaining.

    • setFields

      public Setting setFields(org.miaixz.bus.core.center.function.SupplierX<String>... fields)
      Sets multiple properties using an array of lambda method reference suppliers.

      Example: 

       User user = new User("test", "Test User");
 Setting.of().setFields(user::getUsername, user::getNickname);
      Parameters:
      fields - An array of suppliers, where each supplier returns a property value.
      Returns:
      this Setting instance for chaining.

    • setByGroup

      public Setting setByGroup(String key, String group, String value)
      Sets a value in a specific group.
      Parameters:
      key - The key.
      group - The group name.
      value - The value.
      Returns:
      this Setting instance for chaining.

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Map<String,String>

    • containsKey

      public boolean containsKey(Object key)
      Specified by:
      containsKey in interface Map<String,String>

    • containsValue

      public boolean containsValue(Object value)
      Specified by:
      containsValue in interface Map<String,String>

    • get

      public String get(Object key)
      Specified by:
      get in interface Map<String,String>

    • put

      public String put(String key, String value)
      Specified by:
      put in interface Map<String,String>

    • remove

      public String remove(Object key)
      Specified by:
      remove in interface Map<String,String>

    • putAll

      public void putAll(Map<? extends String,? extends String> m)
      Specified by:
      putAll in interface Map<String,String>

    • clear

      public void clear()
      Specified by:
      clear in interface Map<String,String>

    • keySet

      public Set<String> keySet()
      Specified by:
      keySet in interface Map<String,String>

    • values

      public Collection<String> values()
      Specified by:
      values in interface Map<String,String>

    • entrySet

      public Set<Map.Entry<String,String>> entrySet()
      Specified by:
      entrySet in interface Map<String,String>

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Map<String,String>
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface Map<String,String>
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object