Apache Tamaya — Extension: Mutable Configuration

Overview

Tamaya Configuration by default is read-only, which covers must of the use cases. But there are many legit scenarios where configuration should be written back to some backend systems or the local file system. This module adds this functionality.

Compatibility

The module is based on Java 7, so it can be used with Java 7 and beyond.

Installation

To benefit from configuration mutability support you only must add the corresponding dependency to your module:

<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-mutable-config</artifactId>
  <version>{tamayaVersion}</version>
</dependency>

Core Architecture

The core of the module is the MutableConfigurationProvider singleton, which provides access to MutableConfiguration instance, which extends Configuration. This interface adds additional methods to add/update or remove property values. Hereby changes applied are managed in a transaction like context, called ConfigChangeContext. Each context defines a UUID that identifes a change. Backends for writing changes applied are of type MutablePropertySource, similarly extending the PropertySource SPI with methods for writing changes back. Registrations and ordering policies are like with ordinary property sources, with one important difference. Mutable property source can be targeted by write operations.

Summarizing a MutableConfiguration can be obtained as follows:

MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
config.set("newKey", "newValue")
      .set("anotherKey", "updatedValue")
      .remove("valueNotValid")
      .commit();

In the above scenario we use the overall system’s configuration as the backend to be used. We can also pass any Configuration to render it into a mutable instance, e.g.

Configuration config = ...;
MutableConfiguration config =
    MutableConfigurationProvider.createMutableConfiguration(config);

Following is the complete listing of the MutableConfigurationProvider accessor:

public final class MutableConfigurationProvider {

    private MutableConfigurationProvider(){}

    public static MutableConfiguration getMutableConfiguration();
    public static MutableConfiguration getMutableConfiguration(Configuration configuration);

    [...]
}

Hereby MutableConfiguration is defined as follows:

public interface MutableConfiguration extends Configuration {

    UUID startTransaction();
    void commitTransaction();
    void rollbackTransaction();
    UUID getTransactionId();
    boolean getAutoCommit();
    void setAutoCommit(boolean autoCommit);

    void setChangePropagationPolicy(ChangePropagationPolicy changePropagationPolicy);
    ChangePropagationPolicy getChangePropagationPolicy();

    boolean isWritable(String keyExpression);
    boolean isRemovable(String keyExpression);
    boolean isExisting(String keyExpression);
    List<MutablePropertySource> getMutablePropertySources();
    List<MutablePropertySource> getPropertySourcesThatCanWrite(String keyExpression);
    List<MutablePropertySource> getPropertySourcesThatCanRemove(String keyExpression);
    List<MutablePropertySource> getPropertySourcesThatKnow(String keyExpression);

    MutableConfiguration put(String key, String value);
    MutableConfiguration putAll(Map<String, String> properties);
    MutableConfiguration remove(Collection<String> keys);
    MutableConfiguration remove(String... keys);

}

public interface ChangePropagationPolicy {
    void applyChanges(Collection<PropertySource> propertySources, UUID transactionID, Map<String,String> changes);
    void applyChange(Collection<PropertySource> propertySources, UUID transactionID, String key, String value);
    void applyRemove(Collection<PropertySource> propertySources, UUID transactionID, String... keys);

}

public final class MutableConfigurationProvider {

    private MutableConfigurationProvider(){}

    public static MutableConfiguration getMutableConfiguration();
    public static MutableConfiguration getMutableConfiguration(Configuration configuration);

    public static ChangePropagationPolicy getApplyAllChangePolicy();
    public static ChangePropagationPolicy getApplyMostSignificantOnlyChangePolicy();
    public static ChangePropagationPolicy getApplySelectiveChangePolicy(String... propertySourceNames);
    public static ChangePropagationPolicy getApplyNonePolicy();
}

MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();

if(config,isWritable("mycluster.shared.appKey")){
    config.set("newKey", "newValue");
}
if(config,isRemovable("mycluster.myapp.myKey")){
    config.remove("mycluster.myapp.myKey");
}
config.commit();

Configuration Changes

This module does not handle detection of changes to the overall system’s Configuration. This can be done in several ways, e.g. by:

• using the tamaya-events extension, which can be used to observe the system’s configuration and publishing events when things have been changed.

• The SPI implementing the MutableConfigurationBackendSpi may inform/update any affected PropertySource, PropertySourceProvider instances about the changes applied.

Supported Backends

Multiple backends are supported. E.g. the etcd integration module of Tamaya also registers corresponding SPI implementations/backends. By default this module comes with the following MutablePropertySource implementations:

• MutablePropertySource resources, targeting local .properties files, following the java.util.Properties format.

• MutableXmlPropertySource resources, targeting local .xml property files, following the java.util.Properties XML format.

SPIs

The module defines MutableConfigurationProviderSpi, that is used as a delegate by the MutableConfigurationProvider singleton accessor:

public interface MutableConfigurationProviderSpi {
   MutableConfiguration createMutableConfiguration(Configuration configuration);
}

Implementations are registered with the current ServiceContext, by default as a java.util.ServiceLoader service.

As convenience the following base classes are provided:

• org.apache.tamaya.mutableconfig.propertysource.AbstractMutablePropertySource simplifying implementation of MutablePropertySource.