Module io.avaje.config
Package io.avaje.config

Interface Configuration

@NonNullApi public interface Configuration
Configuration API for accessing property values and registering onChange listeners.

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);

  • Method Details

    • asProperties

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

    • forPath

      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");

    • get

      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

      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

      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

      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

      @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

      @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

      default 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 (configuration.enabled("feature.cleanup")) {
     ...
   }
      Parameters:
      key - The configuration key
      Returns:
      The configured value

    • enabled

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

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

      

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

    • getBool

      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

      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

      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

      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

      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

      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

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

    • getDecimal

      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

      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

      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

      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

      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

      <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

    • getAs

      <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

      <T> Optional<T> getAsOptional(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

    • getEnum

      <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

    • list

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

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

    • set

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

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

    • eventBuilder

      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

      void setProperty(String key, String value)
      Set a single configuration value. Note that eventBuilder(String) should be used when setting multiple configuration values.

      This will fire configuration callback listeners that are registered.

    • putAll

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

      This will fire configuration callback listeners that are registered.

    • clearProperty

      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.

    • onChange

      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

      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

      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

      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

      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.

    • loadIntoSystemProperties

      void loadIntoSystemProperties()
      Put the loaded properties into System properties.

    • size

      int size()
      Return the number of configuration properties.

    • schedule

      void schedule(long delay, long period, Runnable task)
      Schedule a task to run periodically with a given delay and period.
      Parameters:
      delay - delay in milliseconds before task is to be executed.
      period - time in milliseconds between successive task executions.
      task - task to be scheduled.

    • eval

      Properties eval(Properties properties)
      Return a copy of the properties with 'eval' run on all the values.

    • evalModify

      void evalModify(Properties properties)
      Run eval of the given properties modifying the values if changed.

    • builder

      static Configuration.Builder builder()
      Return a Builder for Configuration that is loaded manually (not via the normal resource loading).