Title: Parts & Modules
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

[TOC]

***

# 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 **override**the 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!