Module bus.setting
Package org.miaixz.bus.setting.metric.props

Class Props

java.lang.Object
java.util.Dictionary<Object,Object>
java.util.Hashtable<Object,Object>
java.util.Properties
org.miaixz.bus.setting.metric.props.Props
All Implemented Interfaces:
Serializable, Cloneable, Map<Object,Object>, org.miaixz.bus.core.lang.getter.TypeGetter<CharSequence>
public final class Props extends Properties implements org.miaixz.bus.core.lang.getter.TypeGetter<CharSequence>
A wrapper class for reading and handling .properties files. It extends java.util.Properties with additional convenience methods for typed data retrieval, automatic reloading, and bean mapping.
Since:
Java 17+
Author:
Kimi Liu
See Also:

  • Field Summary

    Fields inherited from class java.util.Properties

    defaults

  • Constructor Summary

    Constructors
    Constructor
    Description
    Props()
    Constructs a new, empty Props object.
    Props(File propertiesFile)
    Constructs a Props object from a File.
    Props(File propertiesFile, Charset charset)
    Constructs a Props object from a File with a specified charset.
    Props(String path)
    Constructs a Props object by loading a properties file from the classpath.
    Props(String path, Charset charset)
    Constructs a Props object by loading a properties file with a specified charset.
    Props(Properties properties)
    Constructs a Props object from an existing Properties object.
    Props(org.miaixz.bus.core.io.resource.Resource resource, Charset charset)
    Constructs a Props object from a Resource with a specified charset.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    autoLoad(boolean autoReload)
    Enables or disables automatic reloading of the properties file when it changes on the filesystem.
    static Props
    get(String name)
    Gets a cached Props instance for a given resource name.
    <P, T> T
    get(org.miaixz.bus.core.center.function.FunctionX<P,T> func)
    Gets a value using a lambda method reference to resolve the property name and return type.
    String
    getAndRemoveString(String... keys)
    Gets and removes a property value.
    static Props
    getFirstFound(String... names)
    Gets the first Props instance that can be successfully loaded from a list of resource names.
    Object
    getObject(CharSequence key, Object defaultValue)
     
    static Props
    getProperties()
    Gets a Props instance containing the current system properties.
    Props
    getSubProps(String prefix)
    Extracts a subset of properties that share a common prefix.
    void
    load()
    Reloads the properties from the original resource.
    void
    load(URL url)
    Initializes this Props object by loading from the given URL.
    void
    load(org.miaixz.bus.core.io.resource.Resource resource)
    Initializes this Props object by loading from the given Resource.
    static Props
    of()
    Creates a new, empty Props object.
    static Props
    of(String resource)
    Creates a Props object by loading a file from the classpath.
    static Props
    of(String resource, Charset charset)
    Creates a Props object by loading a file from the classpath with a specified charset.
    static Props
    of(Props properties)
    Creates a copy of an existing Props object.
    static void
    parse(Map<String,Object> result, String content)
    Parses a string content in .properties format and populates a map.
    void
    set(String key, Object value)
    Sets a property value.
    Props
    setFields(org.miaixz.bus.core.center.function.SupplierX<?>... fields)
    Sets multiple properties using an array of lambda method reference suppliers.
    void
    store(String absolutePath)
    Stores the current properties to a file at the specified absolute path, overwriting its previous content.
    void
    store(String path, Class<?> clazz)
    Stores the current properties to a file path relative to a given class.
    <T> T
    toBean(Class<T> beanClass)
    Maps the properties to a new Java Bean object.
    <T> T
    toBean(Class<T> beanClass, String prefix)
    Maps a subset of properties (filtered by a prefix) to a new Java Bean object.
    <T> T
    toBean(T bean)
    Maps the properties to an existing Java Bean object.
    <T> T
    toBean(T bean, String prefix)
    Maps a subset of properties (filtered by a prefix) to an existing Java Bean object.
    Props
    toProperties()
    Creates a new Props instance containing all the properties from this one.

    Methods inherited from class java.util.Properties

    clear, clone, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, get, getOrDefault, getProperty, getProperty, hashCode, isEmpty, keys, keySet, list, list, load, load, loadFromXML, merge, propertyNames, put, putAll, putIfAbsent, rehash, remove, remove, replace, replace, replaceAll, save, setProperty, size, store, store, storeToXML, storeToXML, storeToXML, stringPropertyNames, toString, values

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.miaixz.bus.core.lang.getter.TypeGetter

    get, get, get, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getChar, getChar, getDate, getDate, getDouble, getDouble, getEnum, getEnum, getFloat, getFloat, getInt, getInt, getLocalDate, getLocalDate, getLocalDateTime, getLocalDateTime, getLocalTime, getLocalTime, getLong, getLong, getNumber, getNumber, getObject, getShort, getShort, getSqlTime, getSqlTime, getSqlTimestamp, getSqlTimestamp, getString, getString

  • Constructor Details

    • Props

      public Props()
      Constructs a new, empty Props object.

    • Props

      public Props(String path)
      Constructs a Props object by loading a properties file from the classpath.
      Parameters:
      path - The path to the properties file, relative to the classpath root, or an absolute path.

    • Props

      public Props(String path, Charset charset)
      Constructs a Props object by loading a properties file with a specified charset.
      Parameters:
      path - The path to the properties file (relative or absolute).
      charset - The character set to use for reading the file.

    • Props

      public Props(File propertiesFile)
      Constructs a Props object from a File.
      Parameters:
      propertiesFile - The properties file.

    • Props

      public Props(File propertiesFile, Charset charset)
      Constructs a Props object from a File with a specified charset.
      Parameters:
      propertiesFile - The properties file.
      charset - The character set to use.

    • Props

      public Props(org.miaixz.bus.core.io.resource.Resource resource, Charset charset)
      Constructs a Props object from a Resource with a specified charset.
      Parameters:
      resource - The resource representing the properties file.
      charset - The character set to use.

    • Props

      public Props(Properties properties)
      Constructs a Props object from an existing Properties object.
      Parameters:
      properties - The properties to copy.

  • Method Details

    • of

      public static Props of()
      Creates a new, empty Props object.
      Returns:
      A new Props instance.

    • of

      public static Props of(String resource)
      Creates a Props object by loading a file from the classpath.
      Parameters:
      resource - The path to the resource, relative to the classpath root.
      Returns:
      A new Props instance.

    • of

      public static Props of(String resource, Charset charset)
      Creates a Props object by loading a file from the classpath with a specified charset.
      Parameters:
      resource - The path to the resource.
      charset - The character set to use.
      Returns:
      A new Props instance.

    • of

      public static Props of(Props properties)
      Creates a copy of an existing Props object.
      Parameters:
      properties - The Props object to copy.
      Returns:
      A new Props instance.

    • get

      public static Props get(String name)
      Gets a cached Props instance for a given resource name. If the name has no extension, .properties is assumed.
      Parameters:
      name - The name of the properties file.
      Returns:
      A cached or new Props instance.

    • parse

      public static void parse(Map<String,Object> result, String content)
      Parses a string content in .properties format and populates a map.
      Parameters:
      result - The map to populate with the parsed key-value pairs.
      content - The string content to parse.

    • getFirstFound

      public static Props getFirstFound(String... names)
      Gets the first Props instance that can be successfully loaded from a list of resource names.
      Parameters:
      names - The resource names to try.
      Returns:
      The first found Props instance, or null if none are found.

    • getProperties

      public static Props getProperties()
      Gets a Props instance containing the current system properties.
      Returns:
      A new Props instance with system properties.

    • load

      public void load(URL url)
      Initializes this Props object by loading from the given URL.
      Parameters:
      url - The URL of the properties file.

    • load

      public void load(org.miaixz.bus.core.io.resource.Resource resource)
      Initializes this Props object by loading from the given Resource.
      Parameters:
      resource - The resource to load.

    • load

      public void load()
      Reloads the properties from the original resource.

    • autoLoad

      public void autoLoad(boolean autoReload)
      Enables or disables automatic reloading of the properties file when it changes on the filesystem.
      Parameters:
      autoReload - true to enable auto-reloading, false to disable it.

    • getObject

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

    • get

      public <P, T> T get(org.miaixz.bus.core.center.function.FunctionX<P,T> func)
      Gets a value using a lambda method reference to resolve the property name and return type.
      Type Parameters:
      P - The type of the class containing the method.
      T - The return type of the method.
      Parameters:
      func - The method reference (e.g., Config::getUsername).
      Returns:
      The property value converted to the specified type.

    • getAndRemoveString

      public String getAndRemoveString(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.

    • getSubProps

      public Props getSubProps(String prefix)
      Extracts a subset of properties that share a common prefix. The prefix is removed from the keys in the resulting Props object.

      Example: 

       a.b = 1
 a.c = 2
 b.a = 3
      Calling getSubProps("a") would return a Props object containing: 
       b = 1
 c = 2
      Parameters:
      prefix - The prefix to match. A dot is automatically appended if not present.
      Returns:
      A new Props object containing the subset of properties.

    • toProperties

      public Props toProperties()
      Creates a new Props instance containing all the properties from this one.
      Returns:
      A new Props instance.

    • toBean

      public <T> T toBean(Class<T> beanClass)
      Maps the properties to a new Java Bean object. Supports nested properties.
      Type Parameters:
      T - The type of the bean.
      Parameters:
      beanClass - The class of the Java Bean to create and populate.
      Returns:
      The newly created and populated bean object.

    • toBean

      public <T> T toBean(Class<T> beanClass, String prefix)
      Maps a subset of properties (filtered by a prefix) to a new Java Bean object.
      Type Parameters:
      T - The type of the bean.
      Parameters:
      beanClass - The class of the Java Bean to create and populate.
      prefix - The prefix to filter properties by. Only properties starting with this prefix will be mapped.
      Returns:
      The newly created and populated bean object.

    • toBean

      public <T> T toBean(T bean)
      Maps the properties to an existing Java Bean object.
      Type Parameters:
      T - The type of the bean.
      Parameters:
      bean - The Java Bean object to populate.
      Returns:
      The populated bean object.

    • toBean

      public <T> T toBean(T bean, String prefix)
      Maps a subset of properties (filtered by a prefix) to an existing Java Bean object.
      Type Parameters:
      T - The type of the bean.
      Parameters:
      bean - The Java Bean object to populate.
      prefix - The prefix to filter properties by.
      Returns:
      The populated bean object.

    • set

      public void set(String key, Object value)
      Sets a property value. If the key does not exist, it is created. This change is not persisted to the file until store(String) is called.
      Parameters:
      key - The property key.
      value - The property value.

    • setFields

      public Props setFields(org.miaixz.bus.core.center.function.SupplierX<?>... fields)
      Sets multiple properties using an array of lambda method reference suppliers. This is useful for setting properties from a bean's getters.

      Example: 

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

    • store

      public void store(String absolutePath) throws org.miaixz.bus.core.lang.exception.InternalException
      Stores the current properties to a file at the specified absolute path, overwriting its previous content.
      Parameters:
      absolutePath - The absolute path to the destination file.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • store

      public void store(String path, Class<?> clazz)
      Stores the current properties to a file path relative to a given class.
      Parameters:
      path - The path relative to the class.
      clazz - The class to which the path is relative.