2017-09-12

Apache Tamaya: Quickstart

The fastest way to start with Tamaya is just using the Core implementation, implementing the API in a minimalistic way. For that add the following Maven dependency to your project:

Adding the Tamaya Dependency

<dependency>
    <groupId>org.apache.tamaya</groupId>
    <artifactId>tamaya-core</artifactId>
    <version>0.4-incubating-SNAPSHOT</version>
</dependency>

Start Coding

In your Java code you can directly access configuration from the API. In most cases it is recommended to provide the default values when accessing the configuration:

Configuration config = ConfigurationProvider.getConfiguration();

String aTextValue = config.getOrDefault("my.value.key", "N/A");
int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15 /* default */);
BigDecimal bdValue = config.getOrDefault("my.BD.value", BigDecimal.class, BigDecimal.valueOf(120));

With Java 8 you can, of course, also use Optional, e.g.

Configuration config = ConfigurationProvider.getConfiguration();

String aTextValue = Optional.ofNullable(config.getOrDefault("my.value.key").orElse("N/A");

Add/define your configuration data

As seen you can immedeatly start working with your configuration backend, without adding any kind of default configuration. Nevertheless the core implementation also comes with a default mechanism, where you can store your configuration as .properties in your classpath:

META-INF/javaconfiguration.properties

Additionally also system properties are taken into account, hereby overriding the default properties. Overall Tamaya by default defines the following configuration model per default (most significant first):

  1. System Properties

  2. META-INF/javaconfiguration.properties

Advanced Topics

Multiple configuration files

By default you can provide multiple javaconfig.properties files, e.g. as part of multiple jars loaded into your system. The system creates one PropertySource for each file found on the classpath. All PropertySource instances created are ordered by their precedence.

By default the precendence of a PropertySource is evaluated based on an ordinal value calculated as follows:

  1. the systems checks for a tamaya.ordinal configuration value and tries to convert to an int ordinal value.

  2. the systems checks if the property source has a method int getOrdinal(). If present the result is used as ordinal.

  3. the systems checks if the property source has a @Priority annotation and uses the annotation’s value as ordinal.

  4. if all of the above fails, 0 is assumed as ordinal.

Note
Since evaluation of the tamaya.ordinal is always done first, it is possible to change the ordinal value by adding a corresponding configuration entry to a property source.

Tamaya Core uses the following default ordinals:

Source

Ordinal

System Properties

400

Environment Properties

300

Properties from META-INF/javaconfiguration.properties

100

That means that the value of a configuration variable x overhanded via -Dx=yes has a higher precedence then the entry for configuration variable x specified in META-INF/javaconfig.properties as x=no.

These ordinal values can be either hardcoded, or be dynamically configurable as key within each configuration resource. The ladder can be done by defining a special Tamaya ordinal value as follows:

# override default Tamaya ordinal for property files
tamaya.ordinal=123

This assigns an ordinal of 123 to each entry in that property source providing this configuration properties.

Using additional features of Tamaya

There many modules that extend the capabilities of Tamaya. These modules doe not depend on core, so alternative implementations of the Tamaya API should work similarly. Following a small extract of most important modules available (or available soon). Refer to this list for a complete overview.

Dynamic Resolution and Value Placeholders

<dependency>
  <artifactId>org.apache.tamaya.ext</id>
  <artifactId>tamaya-resolver</artifactId>
  <version>0.4-incubating-SNAPSHOT</version>
</dependency>

With that it is possible to define values with Unix styled placeholders that are resolved on configuration access, e.g. mykey=my${dynamicValue}ยด. For further details refer to the module documentation. This module also provides a `Resolver singleton:

String myExpression = ...;
String resolved = Resolver.evaluateExpression(myExpression);

Ant-styled Path Resolution of Resources

<dependency>
  <artifactId>org.apache.tamaya.ext</id>
  <artifactId>tamaya-resolution</artifactId>
  <version>0.4-incubating-SNAPSHOT</version>
</dependency>

This module provides a Resolver singleton that allows to resolve configuration resources using a ant-styled resource description, e.g.

Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties");

For further details refer to the module documentation.

Configuration Injection

<dependency>
  <artifactId>org.apache.tamaya.ext</id>
  <artifactId>tamaya-inject</artifactId>
  <version>{tamaya_version_development}</version>
</dependency>

With this extension you can let Tamaya inject configuration into instances of annotated classes or let Tamaya implement a configuration template.

Corresponding configuration:

public class MyType {
   @Config("my.key")
   private String typeName;

   public String getName() {
      return name;
   }
}

MyType type = new MyType();
ConfigurationInjector.configure(type);

Or the same as template:

public interface MyTypeTemplate {
   @Config("my.key")
   public String getName();
}

MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class);

Currently the following resolvers are available:

Conf

Cross-reference to another configuration entry

URL

Referencing a resource addressable by an URL.

File

Reference to a file, replacing the expression with the file’s text value.

Resource

Reference to classpath resource, replacing the expression with the resource’s text value.