Interface ConfigSource


  • public interface ConfigSource
    A configuration source which provides configuration values from a specific place. Some examples of configuration sources may include:
    • a JNDI-backed naming service
    • a properties file
    • a database table
    Implementations of this interface have the responsibility to get the value corresponding to a property name, and to enumerate available property names.

    A configuration source is always read-only; any potential updates of the backing configuration values must be handled directly inside each configuration source instance.

    Default configuration sources

    Some configuration sources are known as default configuration sources. These configuration sources are normally available in all automatically-created configurations, and can be manually added to manually-created configurations as well. The default configuration sources are:
    1. System properties, with an ordinal value of 400
    2. Environment properties, with an ordinal value of 300
    3. The /META-INF/microprofile-config.properties resource, with an ordinal value of 100

    Environment variable name mapping rules

    Some operating systems allow only alphabetic characters or an underscore (_) in environment variable names. Other characters such as ., /, etc. may be disallowed. In order to set a value for a config property that has a name containing such disallowed characters from an environment variable, the following rules are used. Three environment variables are searched for a given property name (e.g. "com.ACME.size"):

    1. The exact name (i.e. "com.ACME.size")
    2. The name, with each character that is neither alphanumeric nor _ replaced with _ (i.e. "com_ACME_size")
    3. The name, with each character that is neither alphanumeric nor _ replaced with _ and then converted to upper case (i.e. "COM_ACME_SIZE")

    The first of these environment variables that is found for a given name is returned.

    Configuration source discovery

    Discovered configuration sources are loaded via the ServiceLoader mechanism and and can be registered by providing a resource named META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource, which contains the fully qualified ConfigSource implementation class name as its content.

    Configuration sources may also be added by defining ConfigSourceProvider classes which are discoverable in this manner.

    Closing configuration sources

    If a configuration source implements the AutoCloseable interface, then its close method will be called when the underlying configuration is released.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CONFIG_ORDINAL
      The name of the configuration ordinal property, "config_ordinal".
      static int DEFAULT_ORDINAL
      The default configuration ordinal value, 100.
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.lang.String getName()
      The name of the configuration source.
      default int getOrdinal()
      Return the ordinal priority value of this configuration source.
      java.util.Map<java.lang.String,​java.lang.String> getProperties()
      Return the properties in this configuration source as a map.
      default java.util.Set<java.lang.String> getPropertyNames()
      Gets all property names known to this configuration source, without evaluating the values.
      java.lang.String getValue​(java.lang.String propertyName)
      Return the value for the specified property in this configuration source.
    • Field Detail

      • CONFIG_ORDINAL

        static final java.lang.String CONFIG_ORDINAL
        The name of the configuration ordinal property, "config_ordinal".
        See Also:
        Constant Field Values
      • DEFAULT_ORDINAL

        static final int DEFAULT_ORDINAL
        The default configuration ordinal value, 100.
        See Also:
        Constant Field Values
    • Method Detail

      • getProperties

        java.util.Map<java.lang.String,​java.lang.String> getProperties()
        Return the properties in this configuration source as a map.
        Returns:
        a map containing properties of this configuration source
      • getPropertyNames

        default java.util.Set<java.lang.String> getPropertyNames()
        Gets all property names known to this configuration source, without evaluating the values.

        For backwards compatibility, there is a default implementation that just returns the keys of getProperties(). Implementations should consider replacing this with a more performant implementation.

        The returned property names may be a subset of the names of the total set of retrievable properties in this config source.

        Returns:
        a set of property names that are known to this configuration source
      • getOrdinal

        default int getOrdinal()
        Return the ordinal priority value of this configuration source. If a property is specified in multiple config sources, the value in the config source with the highest ordinal takes precedence. For configuration sources with the same ordinal value, the configuration source name will be used for sorting according to string sorting criteria.

        Note that this method is only evaluated during the construction of the configuration, and does not affect the ordering of configuration sources within a configuration after that time.

        The ordinal values for the default configuration sources can be found above.

        Any configuration source which is a part of an application will typically use an ordinal between 0 and 200. Configuration sources provided by the container or 'environment' typically use an ordinal higher than 200. A framework which intends have values overridden by the application will use ordinals between 0 and 100.

        The default implementation of this method looks for a configuration property named "config_ordinal" to determine the ordinal value for this configuration source. If the property is not found, then the default ordinal value is used.

        This method may be overridden by configuration source implementations to provide a different behavior.

        Returns:
        the ordinal value
      • getValue

        java.lang.String getValue​(java.lang.String propertyName)
        Return the value for the specified property in this configuration source.
        Parameters:
        propertyName - the property name
        Returns:
        the property value, or null if the property is not present
      • getName

        java.lang.String getName()
        The name of the configuration source. The name might be used for logging or for analysis of configured values, and also may be used in ordering decisions.

        An example of a configuration source name is "property-file mylocation/myprops.properties".

        Returns:
        the name of the configuration source