Parts & Modules

Overview
API
Core
Modules
Other Functionality or Extensions

Overview¶

Tamaya has a modular design comprising the following parts:

Tamaya contains a API with artifacts such as Configuration, ConfigurationProvider, ConfigOperator, ConfigQuery, PropertyConverter, TypeLiteral, ConfigException
Besides the API Tamaya defines an SPI, which provides powerful extension mechanisms with artifacts such as ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi, PropertyFilter, PropertySource, PropertySourceProvider, PropertyValueCombinationPolicy, ServiceContext, ServiceContextManager.
The Core contains a small and minimal implementation of the API that contains everything needed for SE based use cases.
The Modules are extensions (based on the API) providing different functionality such as a configuration injection mechanism, including an injection SPI (tamaya-injection). support for dynamic placeholders and resolvers, including a resolver API (tamaya-resolver). a mechanism to declaratively lookup resources on the filesystem and the classpath (tamaya-resources) an event mechanism for modelling and propagating configuration changes (tamaya-events) a common model for decoupling formatting from building up concrete property sources (tamaya-formats) an extendible environment model (tamaya-environment) preconfigured more complex configuration schemes, e.g. for OSGI, Java EE and other runtime container technologies. integrate of Tamaya with other frameworks such as Apache Commons Configuration, Spring and Java EE, CDI. ** and more...

NOTE: This modules are published based on the individual maturity. Check the release notes, which modules are part of a Tamaya release and which not.

Finally the dhe Documentation module contains overall documentations in asciidoc .

API¶

The API models a complete Java SE API for configuration. It is possible to implement an application completely against this API only. The API takes about 20k of disk space (Java 8) and is available from Maven central as

   <dependency>
     <artifactId>org.apache.tamaya</id>
     <artifactId>tamaya-api</artifactId>
     <version><CURRENT_VERSION></version>
   </dependency>

Nevertheless the API is also minimalistic and many users will wish more functionality available. This is where so called Tamaya extensions come into the place (see later).

Core¶

The Core module implements the API based on Java SE and provides additional features as useful. The Core part hereby does not have any external dependencies, beside the API and also only takes about 70k of space. So with the API less than 100k of space is needed for configuring your application. Put the following information in your pom.xml file

<dependency>
  <artifactId>org.apache.tamaya</id>
  <artifactId>tamaya-core</artifactId>
  <version><CURRENT_VERSION></version>
</dependency>

The core modules out of the box supports .properties files as valid input formats. It is capable of reading configuration resources from

the classpath
the file system
any resource addressable by an URL

The core part by default is not considered to define how you should organize your configuration. Different needs and usage scenarios still require Tamaya to be very flexible, consider the following aspects that theoretically may be completely different for different usage scenarios/ companies:

Configuration Formats
Configuration Locations
Configuration Technology (files, remote resources, classpath, database, ReST, ...)
Configuration Levels
Configuration Overriding Policies (aka duplicate handling and conflict resolution)
Configuration Isolation (ear, war, rar, shared classloaders, paas, saas, multi tenancy, etc).
Configuration Access Policies (security constraints, encryption, ...)
Configuration Granularity (overall, solution, products, plugins, package, class, ...)
Configuration Context (in relation to the current Environment)
... (and more)

Nevertheless, by default, Tamaya registers and loads a simple configuration meta-model by default, which is as follows (first sources have lower priority):

Default entries: META-INF/cfg/default-config.properties
Explicit entries: META-INF/cfg/config.properties
System Properties
Environment Properties, mapped to env.* The_.properties_ format hereby is as defined by java.util.Properties.

Modules¶

Tamaya ships with several extension modules that provide additional APIs, SPIs or integration functionality. The most important ones are shortly listed in this section.

Configuration Injection¶

Now with JSR 299/330 we all are aware of inversion of control and dependency injection as a very elegant way to resolve our dependencies. The same is also true for configuration. Instead of adding boilerplate configuration code just let _Tamaya: do the work for you. To use this feature simply add the following dependency to your project:

<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-innject</artifactId>
  <version><CURRENT_VERSION></version>
</dependency>

Now what can you do with it? Look at the following example:

public final class MyConfiguredPlugin {

  @ConfiguredProperty
  private String productName;

  @ConfiguredProperty(keys={"product.version","PRODUCT.version"})
  private Version version;

  ...
}

Hereby the example only shows a subset of the possibilities, given an instance of this class you can then call Tamaya to configure your fields:

MyConfiguredPlugin plugin = ...;
ConfigurationInjector.configure(plugin);

But this is not yet all. You can also define your type-safe configuration templates and add annotations on your template and let Tamaya implement your interface:

public interface MyConfiguredPluginTemplate{

  @ConfiguredProperty
  public String productName();

  @ConfiguredProperty(keys={"product.version", "PRODUCT.version"})
  public Version getVersion();

}

Finally the template can be accessed from ConfigurationInjector similarly:

MyConfiguredPluginTemplate template = ConfigurationInjector.getConfiguration(MyConfiguredPluginTemplate.class);

Integrations¶

Integrations adapt Tamaya for being interoperable with other solutions, or on the other way round existing configuration solutions can transparently hooked into Tamaya.

CDI Integration¶

Planned for the future.

Spring Integration¶

Planned for the future.

Apache Commons Configuration Integration¶

Planned for the future.

Meta-Models¶

Simple (Meta-Model)¶

NOTE: This section must be updated...

This meta-model module provides a simple, but already powerful configuration meta-model suitable for most SE applications. To use it, you just must simply add the following dependency:

<dependency>
  <artifactId>org.apache.tamaya.metamodels</id>
  <artifactId>tamaya-simple</artifactId>
  <version><CURRENT_VERSION></version>
</dependency>

This will allow you to organize your configuration as follows:

// defaults:
classpath:META-INF/cfg/default/**/*.xml,classpath:META-INF/cfg/default/**/*.properties,classpath:META-INF/cfg/default/**/*.ini

// may be overriden by file defaults (see below), and...

classpath:META-INF/cfg/config/**/*.xml,classpath:META-INF/cfg/config/**/*.properties,classpath:META-INF/cfg/config/**/*.ini

// may be overriden by file config (see below)

As mentioned you can set additional system properties to define external file locations to be considered as defaults or non-defaults. These will overridethe corresponding classpath counterpart:

-Dconfig.default.dir=... -Dconfig.dir=...

Classloader Aware Meta-Model¶

Planned for the future.

Java EE Base Meta-Model¶

Planned for the future.

Configuration Documentation and Validation¶

Available currently as experimental module.

Java Management Extension (JMX) Support¶

Available currently as experimental module.

Environment Module¶

Available currently as experimental module.

Other Functionality or Extensions¶

Don't be able to find what you need? If you like the project und want to see additional feastures, think about joining us as a contributor. Basically it is enough to just drop as a mail on our [developer mailing list][1]. We will help to jump on the Tamaya train!