Why Using Strings Only

There are good reason to keep of non String-values as core storage representation of configuration. Mostly there are several huge advantages:

• Strings are simple to understand

• Strings are human readable and therefore easy to prove for correctness

• Strings can easily be used within different language, different VMs, files or network communications.

• Strings can easily be compared and manipulated

• Strings can easily be searched, indexed and cached

• It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in production as well in testing.

• and more…​

On the other side there are also disadvantages:

• Strings are inherently not type safe, they do not provide validation out of the box for special types, such as numbers, dates etc.

• In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly throughout your code.

• Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some extra efforts.

Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above:

• Adding type safe adapters on top of String allow to add any type easily, that can be directly mapped out of Strings. This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.

• Also multi-valued, complex and collection types can be defined as a corresponding PropertyAdapter knows how to parse and create the target instance required.

• String s also can be used as references pointing to other locations and formats, where configuration is accessible.

[[API Configuration]] === Configuration

Configuration is the main API provided by Tamaya. It allows reading of single property values or the whole property map, but also supports type safe access:

public interface Configuration{
    String get(String key);
    String getOrDefault(String key, String value);
    <T> T get(String key, Class<T> type);
    <T> T getOrDefault(String key, Class<T> type, T defaultValue);
    <T> T get(String key, TypeLiteral<T> type);
    <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue);
    Map<String,String> getProperties();

    // extension points
    Configuration with(ConfigOperator operator);
    <T> T query(ConfigQuery<T> query);

    ConfigurationContext getContext();
}

Hereby

• <T> T get(String, Class<T>) provides type safe accessors for all basic wrapper types of the JDK.

• with, query provide the extension points for adding additional functionality.

• getProperties() provides access to all key/values, whereas entries from non scannable property sources may not be included.

• getOrDefault allows to pass default values as needed, returned if the requested value evaluated to null.

The class TypeLiteral is basically similar to the same class provided with CDI:

public class TypeLiteral<T> implements Serializable {

    [...]

    protected TypeLiteral(Type type) {
        this.type = type;
    }

    protected TypeLiteral() { }

    public static <L> TypeLiteral<L> of(Type type){...}
    public static <L> TypeLiteral<L> of(Class<L> type){...}

    public final Type getType() {...}
    public final Class<T> getRawType() {...}

    public static Type getGenericInterfaceTypeParameter(Class<?> clazz, Class<?> interfaceType){...}
    public static Type getTypeParameter(Class<?> clazz, Class<?> interfaceType){...}

    [...]
}

Instances of Configuration can be accessed from the ConfigurationProvider singleton:

Configuration config = ConfigurationProvider.getConfiguration();

Hereby the singleton is backed up by an instance of ConfigurationProviderSpi.

Property Converters

As illustrated in the previous section, Configuration also to access non String types. Nevertheless internally all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the configured String values into the required target type. This is achieved with the help of PropertyConverters:

public interface PropertyConverter<T>{
    T convert(String value, ConversionContext context);
    //X TODO Collection<String> getSupportedFormats();
}

The ConversionContext contains additional meta-information for the accessed key, inclusing the key’a name and additional metadata.

PropertyConverter instances can be implemented and registered by default using the ServiceLoader. Hereby a configuration String value is passed to all registered converters for a type in order of their annotated @Priority value. The first non-null result of a converter is then returned as the current configuration value.

Access to converters is provided by the current ConfigurationContext, which is accessible from the ConfigurationProvider singleton.

Interface PropertySourceProvider

Instances of this type can be used to register multiple instances of PropertySource.

// @FunctionalInterface in Java 8
public interface PropertySourceProvider{
    Collection<PropertySource> getPropertySources();
}

This allows to evaluate the property sources to be read/that are available dynamically. All property sources are read out and added to the current chain of PropertySource instances within the current ConfigurationContext, refer also to .

PropertySourceProviders are by default registered using the Java ServiceLoader or the mechanism provided by the current active ServiceContext.

Interface PropertyFilter

Also PropertyFilters can be added to a Configuration. They are evaluated before a Configuration instance is passed to the user. Filters can hereby used for multiple purposes, such as

• resolving placeholders

• masking sensitive entries, such as passwords

• constraining visibility based on the current active user

• …​

PropertyFilters are by default registered using the Java ServiceLoader or the mechanism provided by the current active ServiceContext. Similar to property sources they are managed in an ordered filter chain, based on the applied @Priority annotations.

A PropertyFilter is defined as follows:

// Functional Interface
public interface PropertyFilter{
    String filterProperty(String value, FilterContext context);
}

Hereby:

• returning null will remove the key from the final result

• non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies filter evaluation has to be continued as long as filters are still changing some of the values to be returned. To prevent possible endless loops after a defined number of loops evaluation is stopped.

• FilterContext provides additional metdata, inclusing the key accessed, which is useful in many use cases.

This method is called each time a single entry is accessed, and for each property in a full properties result.

Interface PropertyValueCombinationPolicy

This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to build up the final Configuration to be passed over to the PropertyFilters. The default implementation is just overriding all values read before with the new value read. Nevertheless for collections and other use cases it is often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the new value. Finally looking at the method’s signature it may be surprising to find a Map for the value. The basic value hereby is defined by currentValue.get(key). Nevertheless the Map may also contain additional meta entries, which may be considered by the policy implementation.

// FunctionalInterface
public interface PropertyValueCombinationPolicy{

   PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
     new PropertyValueCombinationPolicy(){
       @Override
       public Map<String,String> collect(Map<String,String> currentValue, String key,
                                         PropertySource propertySource) {
           PropertyValue value = propertySource.get(key);
           return value!=null?value.getConfigEntries():currentValue;
       }
   };

   String collect(Map<String,String> currentValue currentValue, String key,
                  PropertySource propertySource);

}

The Configuration Context

A Configuration is basically based on a so called ConfigurationContext, which is accessible from Configuration.getContext():

ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext();

The ConfigurationContext provides access to the internal building blocks that determine the final Configuration:

• PropertySources registered (including the PropertySources provided from PropertySourceProvider instances).

• PropertyFilters registered, which filter values before they are returned to the client

• PropertyConverter instances that provide conversion functionality for converting String values to any other types.

• the current PropertyValueCombinationPolicy that determines how property values from different PropertySources are combined to the final property value returned to the client.

Changing the current Configuration Context

By default the ConfigurationContext is not mutable once it is created. In many cases mutability is also not needed or even not wanted. Nevertheless there are use cases where the current ConfigurationContext (and consequently Configuration) must be adapted:

• New configuration files where detected in a folder observed by Tamaya.

• Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must be adapted to these changes.

• The overall configuration context is manually setup by the application logic.

• Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the tests executed.

In such cases the ConfigurationContext must be mutable, meaning it must be possible:

• to add or remove PropertySource instances

• to add or remove PropertyFilter instances

• to add or remove PropertyConverter instances

• to redefine the current PropertyValueCombinationPolicy instances.

This can be achieved by obtaining an instance of ConfigurationContextBuilder. Instances of this builder can be accessed either

• from the current ConfigurationContext, hereby returning a builder instance preinitialized with the values from the current ConfigurationContext

• from the current ConfigurationProvider singleton.

ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder();
ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();

With such a builder a new ConfigurationContext can be created and then applied:

ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext()
                                                           .toBuilder();
ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource())
                                                           .addPropertyFilter(new MyFilter()).build();
ConfigurationProvider.setConfigurationContext(context);

Hereby ConfigurationProvider.setConfigurationContext(context) can throw an UnsupportedOperationException. This can be checked by calling the method boolean ConfigurationProvider.isConfigurationContextSettable().

Implementing and Managing Configuration

One of the most important SPI in Tamaya if the ConfigurationProviderSpi interface, which is backing up the ConfigurationProvider singleton. Implementing this class allows

• to fully determine the implementation class for Configuration

• to manage the current ConfigurationContext in the scope and granularity required.

• to provide access to the right Configuration/ConfigurationContext based on the current runtime context.

• Performing changes as set with the current ConfigurationContextBuilder.

The ServiceContext

The ServiceContext is also a very important SPI, which allows to define how components are loaded in Tamaya. The ServiceContext hereby defines access methods to obtain components, whereas itself it is available from the ServiceContextManager singleton:

ServiceContext serviceContext = ServiceContextManager.getServiceContext();

public interface ServiceContext{
    int ordinal();
    <T> T getService(Class<T> serviceType);
    <T> List<T> getServices(Class<T> serviceType);
}

With the ServiceContext a component can be accessed in two different ways:

1. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally the most significant instance is returned only.

2. access all items given its type. This will return (by default) all instances loadedable from the current runtime context, ordered by priority, hereby the most significant components added first.