Interface Configuration

All Known Implementing Classes:
Configuration.Default

public interface Configuration
General purpose, immutable (builder-created), hierarchical configuration container. Its content consists of key value pairs, which are either value entries <String, String> or child-configuration entries <String, Configuration>.

The keys are just plain Strings with any content except the KEY_SEPARATOR ('.'), because it connects simple keys to full-qualified ones.

Example configuration:

 microstream
   |
   +-- storage
   |   |
   |   +-- storageDirectory = /home/my-storage
   |   |
   |   +-- backupDirectory = /home/backup-storage
   |
   +-- cache
   |   |
   |   +-- keyType = java.lang.String
   |   |
   |   +-- valueTytpe = java.lang.Double
   |
   +-- version = 1.2.3
   |
   +-- production = true
 
To access the storageDirectory entry there are following ways. Either get the child configurations and then the value entry
 String directory = configuration.child("microstream").child("storage").get("storageDirectory");
 
or just use the full-qualified key, as a shortcut
 String directory = configuration.get("microstream.storage.storageDirectory");
 
In order to translate the value entries into different types, ConfigurationValueMappers are used. Predefined value mappers are there for the most commonly used types in configurations: ConfigurationValueMapperProvider.Default().

Custom value mappers can be used as well, of course.

 ConfigurationValueMapperProvider valueMapperProvider = ConfigurationValueMapperProvider.Default()
        .add(new MyValueMapper())
        .build();
 Configuration configuration = Configuration.Builder()
        .valueMapperProvider(valueMapperProvider)
        .build();
 
 boolean production = configuration.getBoolean("microstream.production");
 MyType  myType     = configuration.get("key", MyType.class);
 

Configurations can be created with a Configuration.Builder. Builders are populated programmatically, by a ConfigurationMapper or a ConfigurationParser.

 // create configuration from external file
 Configuration configuration = Configuration.Load(
        ConfigurationLoader.New("config-production.xml"),
        ConfigurationParserXml.New()
 );
 
 // create configuration from Map
 Map<String, Object> otherFrameworkConfig = ...;
 Configuration configuration = ConfigurationMapperMap.New()
        .mapConfiguration(otherFrameworkConfig)
        .buildConfiguration();
 
 // create configuration from different sources
 Configuration.Builder()
        .load(
                ConfigurationLoader.New("config-base.xml"),
                ConfigurationParserXml.New()
        )
        .load(
                ConfigurationLoader.New("config-production.xml"),
                ConfigurationParserXml.New()
        )
        .buildConfiguration();
 
Configurations can be exported as well:
 configuration.store(
        ConfigurationStorer.New(Paths.get("home", "config-export.xml")),
        ConfigurationAssemblerXml.New()
 );
 
  • Field Details

  • Method Details

    • Builder

      static Configuration.Builder Builder()
      Pseudo-constructor method to create a new Configuration.Builder.
      Returns:
      a new builder
    • Load

      static Configuration Load​(ConfigurationLoader loader, ConfigurationParser parser)
      Convenience method to load a configuration from an external source.

      This is shortcut for

      Configuration.Builder().load(loader, parser).buildConfiguration()
      Parameters:
      loader - the loader to retrieve the input
      parser - the parser to parse the input
      Returns:
      the created configuration
    • get

      String get​(String key)
      Gets the assigned value of the specified key, or null if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getBoolean

      default Boolean getBoolean​(String key)
      Gets the assigned value of the specified key as Boolean, or null if the configuration doesn't contain the key.

      The String value is parsed according to Boolean.parseBoolean(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getByte

      default Byte getByte​(String key)
      Gets the assigned value of the specified key as Byte, or null if the configuration doesn't contain the key.

      The String value is parsed according to Byte.parseByte(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getShort

      default Short getShort​(String key)
      Gets the assigned value of the specified key as Short, or null if the configuration doesn't contain the key.

      The String value is parsed according to Short.parseShort(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getInteger

      default Integer getInteger​(String key)
      Gets the assigned value of the specified key as Integer, or null if the configuration doesn't contain the key.

      The String value is parsed according to Integer.parseInt(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getLong

      default Long getLong​(String key)
      Gets the assigned value of the specified key as Long, or null if the configuration doesn't contain the key.

      The String value is parsed according to Long.parseLong(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getFloat

      default Float getFloat​(String key)
      Gets the assigned value of the specified key as Float, or null if the configuration doesn't contain the key.

      The String value is parsed according to Float.parseFloat(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • getDouble

      default Double getDouble​(String key)
      Gets the assigned value of the specified key as Double, or null if the configuration doesn't contain the key.

      The String value is parsed according to Double.parseDouble(String).

      Parameters:
      key - the key to look up
      Returns:
      the assigned value, or null
    • get

      <T> T get​(String key, Class<T> type)
      Gets the assigned value of the specified key. or null if the configuration doesn't contain the key.

      The String value is parsed by the registered ConfigurationValueMapper for the specified type.

      Type Parameters:
      T - the value type
      Parameters:
      key - the key to look up
      type - the type to map to
      Returns:
      the assigned value, or null
      Throws:
      ConfigurationExceptionNoValueMapperFound - if no ConfigurationValueMapper is found for the type
      ConfigurationExceptionValueMappingFailed - if the mapping to the target type fails
    • opt

      default Optional<String> opt​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
    • optBoolean

      default Optional<Boolean> optBoolean​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getBoolean(String)
    • optByte

      default Optional<Byte> optByte​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getByte(String)
    • optShort

      default Optional<Short> optShort​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getShort(String)
    • optInteger

      default Optional<Integer> optInteger​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getInteger(String)
    • optLong

      default Optional<Long> optLong​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getLong(String)
    • optFloat

      default Optional<Float> optFloat​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getFloat(String)
    • optDouble

      default Optional<Double> optDouble​(String key)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      a filled or empty Optional
      See Also:
      getDouble(String)
    • opt

      default <T> Optional<T> opt​(String key, Class<T> type)
      Gets the assigned value of the specified key as Optional, which is empty if the configuration doesn't contain the key.
      Type Parameters:
      T - the value type
      Parameters:
      key - the key to look up
      type - the type to map to
      Returns:
      a filled or empty Optional
      Throws:
      ConfigurationExceptionNoValueMapperFound - if no ConfigurationValueMapper is found for the type
      ConfigurationExceptionValueMappingFailed - if the mapping to the target type fails
      See Also:
      get(String, Class)
    • contains

      boolean contains​(String key)
      Checks if this configuration contains the specified key.
      Parameters:
      key - the key to look up
      Returns:
      true if this configuration contains the key, false otherwise
    • key

      String key()
      Gets the key of this child-configuration or null if this is the root configuration.
      Returns:
      this child-configuration's key
    • keys

      Iterable<String> keys()
      Gets all keys of this configuration, but not of the child-configurations.
      Returns:
      an iterable with all keys
    • child

      Configuration child​(String key)
      Gets the assigned child-configuration of the specified key, or null if the configuration doesn't contain the key.
      Parameters:
      key - the key to look up
      Returns:
      the assigned child-configuration, or null
    • children

      Iterable<? extends Configuration> children()
      Gets all direct child-configurations.
      Returns:
      all child-configurations
    • parent

      Configuration parent()
      Gets this configuration's parent, or null if this is the root configuration.
      Returns:
      the parent or null
    • isRoot

      default boolean isRoot()
      Checks if this configuration is the root, meaning it has no parent.
      Returns:
      true if this configuration is the root, false otherwise
    • root

      default Configuration root()
      Gets the root configuration, which may be this.
      Returns:
      the configuration's root
    • traverse

      void traverse​(Consumer<Configuration> consumer)
      Traverses this and all child-configurations recursively.
      Parameters:
      consumer - the consumer to accept all configurations
    • table

      Converts all entries of this configuration to a XGettingTable.
      Returns:
      a XGettingTable containing all entries of this configurations
      See Also:
      coalescedTable()
    • coalescedTable

      XGettingTable<String,​String> coalescedTable()
      Converts all entries of this configuration and all child-configurations recursively to a XGettingTable.
      Returns:
      a XGettingTable containing all entries of this and all child-configurations
    • map

      Map<String,​String> map()
      Converts all entries of this configuration to a Map.

      Because configurations are immutable, changes made in the resulting map will not reflect back.

      Returns:
      a Map containing all entries of this configurations
      See Also:
      coalescedMap()
    • coalescedMap

      Map<String,​String> coalescedMap()
      Converts all entries of this configuration and all child-configurations recursively to a Map.

      Because configurations are immutable, changes made in the resulting map will not reflect back.

      Returns:
      a Map containing all entries of this and all child-configurations
    • valueMapperProvider

      ConfigurationValueMapperProvider valueMapperProvider()
      Gets the value mapper provider which is assigned to this configuration.
      Returns:
      the assigned value mapper
      See Also:
      get(String, Class)
    • detach

      Configuration detach()
      Creates a new Configuration instance with all entries and child-configurations of this configuration, but with no parent, which makes it a root configuration.

      The original configuration (this) remains untouched.

      Returns:
      a new, detached configuration
    • store

      default void store​(ConfigurationStorer storer, ConfigurationAssembler assembler)
      Stores this configuration to an external target.
      Parameters:
      storer - the storer to write to
      assembler - the assembler for the desired format