Class Config

java.lang.Object
io.avaje.config.Config
@NullMarked public class Config extends Object
Provides application Configuration based on loading properties and yaml files as well as plugins that supply properties (like dynamic configuration loaded from a db).

The "Default" configuration automatically loads from known files and resources and is available via asConfiguration(). The methods on Config are convenience methods that use the underlying "Default" configuration.

Refer to config loading for details on the "Default" configuration sources which include:

  1. - application.properties invalid input: '&' application.yaml resources invalid input: '&' files
  2. - system property load.properties
  3. - command line arguments
  4. - plugins (like the AWS AppConfig plugin)

Configuration can also be built giving full control - refer to Configuration.builder().

The application can register onChange listeners to handle changes to configuration properties at runtime. Plugins or code can dynamically load and change properties and this can fire any registered callback handlers.

Obtain the "default" configuration



  Configuration defaultConfiguration = Config.asConfiguration();

"Default" configuration usage examples



  int port = Config.getInt("app.port", 8090);

  String topicName = Config.get("app.topic.name");

  List<Integer> codes = Config.list().ofInt("my.codes", 42, 54);

Build a configuration



  var configuration = Configuration.builder()
    .put("myKey", "myValue")
    .load(someFile)           // load a yaml or properties file
    .load(someResource)       // load a yaml or properties resource from the classpath
    .build();

Use Configuration



  Configuration defaultConfiguration = Config.asConfiguration();

  int port = defaultConfiguration.getInt("port", 8080);
  String host = defaultConfiguration.get("host", "localhost");

  • Method Details

    • asProperties

      public static Properties asProperties()
      Return the loaded properties as standard Properties map.

    • forPath

      public static Configuration forPath(String pathPrefix)
      Return the configuration for a path.

      Examples

      Say you have a set of properties like this

      example.path.prefix1=1
      example.path.prefix2=2

      
 Configuration config = Config.forPath("example.path");
 Configuration config2 = Config.forPath("example").forPath("path");
 // will output "1"
 int number = config.getInt("prefix1");
 // will output "2"
 number = config2.getInt("prefix2");

    • asConfiguration

      public static Configuration asConfiguration()
      Return the underlying configuration.

    • loadIntoSystemProperties

      public static void loadIntoSystemProperties()
      Put all loaded properties into System properties.

    • get

      public static String get(String key)
      Return a required configuration value as String.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • get

      public static String get(String key, String defaultValue)
      Return a configuration string value with a given default.
      Parameters:
      key - The configuration key
      defaultValue - The default value used
      Returns:
      The configured or default value

    • getOptional

      public static Optional<String> getOptional(String key)
      Return a configuration value that might not exist.
      Parameters:
      key - The configuration key
      Returns:
      The configured value wrapped as optional

    • getOptional

      public static Optional<String> getOptional(String key, @Nullable String defaultValue)
      Return a configuration value that might not exist.
      Parameters:
      key - The configuration key
      defaultValue - The default value that can be null
      Returns:
      The configured value wrapped as optional

    • getNullable

      public static @Nullable String getNullable(String key)
      Return a configuration value as String or null if it is not defined.

      This is an alternative to getOptional(String) for cases where we prefer to work with null values rather than Optional.

      Parameters:
      key - The configuration key
      Returns:
      The configured value or null if not set

    • getNullable

      public static @Nullable String getNullable(String key, @Nullable String defaultValue)
      Return a configuration value as String or null if it is not defined.

      This is an alternative to getOptional(String) for cases where we prefer to work with null values rather than Optional.

      Parameters:
      key - The configuration key
      defaultValue - The default value that can be null
      Returns:
      The configured value or null if not set

    • enabled

      public static boolean enabled(String key)
      Return boolean configuration value with the given default value.

      This is the same as getBool(String).

      IllegalStateException is thrown if the value is not defined in configuration. 

      

   if (Config.enabled("feature.cleanup")) {
     ...
   }
      Parameters:
      key - The configuration key
      Returns:
      True when configuration value is true

    • enabled

      public static boolean enabled(String key, boolean enabledDefault)
      Return boolean configuration value with the given default value.

      This is the same as getBool(String, boolean). 

      

   if (Config.enabled("feature.cleanup", true)) {
     ...
   }
      Parameters:
      key - The configuration key
      Returns:
      True when configuration value is true

    • getBool

      public static boolean getBool(String key)
      Return a required boolean configuration value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • getBool

      public static boolean getBool(String key, boolean defaultValue)
      Return a configuration value as boolean given a default value.
      Parameters:
      key - The configuration key
      defaultValue - The default value used
      Returns:
      The configured or default value

    • getInt

      public static int getInt(String key)
      Return a required int configuration value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • getInt

      public static int getInt(String key, int defaultValue)
      Return a configuration value as int given a default value.
      Parameters:
      key - The configuration key
      defaultValue - The default value used
      Returns:
      The configured or default value

    • getLong

      public static long getLong(String key)
      Return a required long configuration value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • getLong

      public static long getLong(String key, long defaultValue)
      Return a configuration value as long given a default value.
      Parameters:
      key - The configuration key
      defaultValue - The default value used
      Returns:
      The configured or default value

    • getDecimal

      public static BigDecimal getDecimal(String key)
      Return a decimal configuration value.
      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • getDecimal

      public static BigDecimal getDecimal(String key, String defaultValue)
      Return a decimal configuration value with a default value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      defaultValue - The default value
      Returns:
      The configured value

    • getURI

      public static URI getURI(String key)
      Return a URI configuration value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • getURI

      public static URI getURI(String key, String defaultValue)
      Return a URI configuration value with a default value.
      Parameters:
      key - The configuration key
      defaultValue - The default value
      Returns:
      The configured value

    • getDuration

      public static Duration getDuration(String key)
      Return a Duration configuration value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • getDuration

      public static Duration getDuration(String key, String defaultValue)
      Return a Duration configuration value with a default value.
      Parameters:
      key - The configuration key
      defaultValue - The default value
      Returns:
      The configured value

    • getEnum

      public static <T extends Enum<T>> T getEnum(Class<T> type, String key)
      Return the enum configuration value.

      IllegalStateException is thrown if the value is not defined in configuration.

      Parameters:
      type - The enum type
      key - The configuration key
      Returns:
      The configured value

    • getEnum

      public static <T extends Enum<T>> T getEnum(Class<T> type, String key, T defaultValue)
      Return the enum configuration value with a default value.
      Parameters:
      type - The enum type
      key - The configuration key
      defaultValue - The default value
      Returns:
      The configured value

    • getAs

      public static <T> T getAs(String key, Function<String,T> mappingFunction)
      Apply a mapping function to the value returned.
      Parameters:
      key - The configuration key
      mappingFunction - the mapping function to execute
      Returns:
      The mapped value

    • getAsOptional

      public static <T> Optional<T> getAsOptional(String key, Function<String,T> mappingFunction)
      Apply a mapping function to the value returned as an optional.
      Parameters:
      key - The configuration key
      mappingFunction - the mapping function to execute
      Returns:
      The mapped value

    • list

      public static Configuration.ListValue list()
      Return a List of values configured. 
      

  List<Integer> codes = Config.list().ofInt("my.codes", 97, 45);

    • set

      public static Configuration.SetValue set()
      Return a Set of values configured. 
      

  Set<String> operations = Config.set().of("my.operations", "put","delete");

    • eventBuilder

      public static ModificationEvent.Builder eventBuilder(String name)
      Create an event builder to make changes to the configuration. 
      

   configuration.eventBuilder("MyChanges")
     .put("someKey", "val0")
     .put("someOther.key", "42")
     .remove("foo")
     .publish();
      Parameters:
      name - The name of the event which defines the source of the configuration value.
      See Also:

    • setProperty

      public static void setProperty(String key, String value)
      Set a single configuration value. Note that eventBuilder(String) should be used to fluently set multiple configuration values.

      This will fire configuration callback listeners that are registered.

    • putAll

      public static void putAll(Map<String,?> map)
      Add configuration values via a map.

      This will fire configuration callback listeners that are registered.

    • clearProperty

      public static void clearProperty(String key)
      Clear the value for the given key. Note that eventBuilder(String) should be used when setting multiple configuration values.

      This will fire configuration callback listeners that are registered.

      Parameters:
      key - The configuration key we want to clear

    • onChange

      public static void onChange(Consumer<ModificationEvent> bulkChangeEventListener, String... keys)
      Register an event listener that will be notified of configuration changes.

      If we are only interested in changes to a single property it is easier to use onChange(String, Consumer) or the variants for int, long, boolean onChangeInt(), onChangeLong(), onChangeBool().

      Typically, we use this when we are interested in changes to multiple properties and want to get and act on the values of multiple properties. 

      
  configuration.onChange((modificationEvent) -> {

    String newValue = modificationEvent.configuration().get("myFirstKey");
    int newInt = modificationEvent.configuration().getInt("myOtherKey");
    // do something ...

  });

      When we are only interested if some specific properties have changed then we can define those. The event listener will be invoked if there is a change to any of those keys. 

      
  configuration.onChange((event) -> {

    String newValue = event.configuration().get("myFirstInterestingKey");
    int newInt = event.configuration().getInt("myOtherInterestingKey");
    // do something ...

  }, "myFirstInterestingKey", "myOtherInterestingKey");
      Parameters:
      bulkChangeEventListener - The listener that is called when changes have occurred
      keys - Optionally specify keys when the listener is only interested if changes are made for these specific properties

    • onChange

      public static void onChange(String key, Consumer<String> singlePropertyChangeListener)
      Register a callback for a change to the given configuration key.

      Use this when we are only interested in changes to a single configuration property. If we are interested in multiple properties we should use onChange(Consumer, String...) 

      

   configuration.onChange("myKey", (newValue) -> {

     // do something with the newValue ...

   )};
      Parameters:
      key - The configuration key we want to detect changes to
      singlePropertyChangeListener - The callback handling to fire when the configuration changes.

    • onChangeInt

      public static void onChangeInt(String key, IntConsumer singlePropertyChangeListener)
      Register a callback for a change to the given configuration key as an Int value.

      Use this when we are only interested in changes to a single configuration property. If we are interested in multiple properties we should use onChange(Consumer, String...)

      Parameters:
      key - The configuration key we want to detect changes to
      singlePropertyChangeListener - The callback handling to fire when the configuration changes.

    • onChangeLong

      public static void onChangeLong(String key, LongConsumer singlePropertyChangeListener)
      Register a callback for a change to the given configuration key as a Long value.

      Use this when we are only interested in changes to a single configuration property. If we are interested in multiple properties we should use onChange(Consumer, String...)

      Parameters:
      key - The configuration key we want to detect changes to
      singlePropertyChangeListener - The callback handling to fire when the configuration changes.

    • onChangeBool

      public static void onChangeBool(String key, Consumer<Boolean> singlePropertyChangeListener)
      Register a callback for a change to the given configuration key as a Boolean value.

      Use this when we are only interested in changes to a single configuration property. If we are interested in multiple properties we should use onChange(Consumer, String...)

      Parameters:
      key - The configuration key we want to detect changes to
      singlePropertyChangeListener - The callback handling to fire when the configuration changes.