# Apache Tamaya — Documentation

Anatole Tresch
<anatole@apache.org>
version 0.1-SNAPSHOT, November 2014
Incubator

    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.

## 1. Introduction

### 1.1. What is Apache Tamaya?

Tamaya is a very powerful yet flexible configuration solution. It’s core is built based on a few simple concepts. Summarizing Tamaya provides you

- a simple key/value configuration model.

- a uniform API for accessing configuration, regardless if you are running in a Java SE, Java EE or OSGI environment. This API is capable of hiding all the complexities in configuration management, your developers only need to know, where and in which format configuration can be added to the system.

- A `ConfigurationBuilder` allowing you to create a configuration completely manually and managing the configuration lifecycle on your own.

- a minimalistic implementation, which in the future might also be targeting Java ME environments.

- a powerful SPI that allows you to extend/adapt Tamaya with all kind of additional mechanisms commonly used in many use cases.

- a bunch of modules that can be added to your classpath thus adding different functionality to your system as needed.

### 1.2. What is Apache Tamaya NOT?

Nevertheless there are a few things that are not part of Tamaya:

- Tamaya comes as a modular framework, where you have to decide, which features make sense for you. So you have to do a selection, which modules make sense.

- Though Tamaya comes with a very minimalistic configuration scheme out-of-the-box, it does by default typically not cover your enterprise requirements. Also here Tamaya offers hooks and examples showing how you can easily replace your current configuration logic with Tamaya. So you must know how you want to organize configuration in your enterprise context, such as supported file locations, formats, overriding and filter rules etc.

### 1.3. And what can I do with Apache Tamaya?

There are basically two main usage scenarios, which are synergetic:

- In an enterprise context you can easily implement a configuration architecture for your whole company and deploy the logic as an extension module. All application development teams in your company can then depend on this module (and the basic Tamaya core implementation). As a result all applications/modules in your company follow the same configuration policy, which makes it much more simpler to move people between your teams. Similarly additional tooling functionality can help you to manage configuration on application as well as on enterprise level, e.g. providing command line or REST support to access the supported configuration entries, types and values, configuration validation and more.

- If you are writing an application, application component or library you can support configuration using Tamaya by adding it as an optional dependency. If done so your users/customers can use Tamaya to connect their current enterprise configuration infrastructure transparently to your code. As an example you can use Tamaya to read your default configuration files, but since Tamaya is so easily extendable, customers can deploy an additional jar, which then allows them to add their own configuration mechanisms such as databases, datagrids or REST services.

### 1.4. Working Group

This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This specification is the result of the collaborative work of the members of the Tamaya Users Group and the community at large.

### 1.5. Goals

Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of well defined aspects of a software product without having to recompile/rebuild the code. Summarizing configuration can affect basically every part of a system, which renders configuration to a real cross-cutting concern, usable in many facets.

### 1.6. Targets

Tamaya targets to support all general configuration aspects in a system, e.g.

- application configuration

  - plugins

  - modules

  - components

- Container configuration, e.g. of Java EE enabling portability and dynamic provisioning

- Configuration of CDI (interceptors, decorators and alternatives)

- Configuration of Bean Validation, JSF, web applications etc.

- Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values, and by providing accessors to evaluate current configuration values. This can be used explicitly or transparently by client code.

Since configuration is implemented and applied in various ways Tamaya will allow you to use

- multiple configuration locations, including remote locations

- multiple configuration formats, including custom formats

- multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und URIs are supported by default.

- type conversion

- configuration filtering and property adapters

- configuration of collections

The Tamaya project consists of the following parts:

- The API is a complete SE based configuration API, that provides the minimum of functionality needed. It is modelled in a extensible way and only requires a few kb. The main features supported by the API.html are:

  - Reading configuration as String/String key/value pairs

  - Reading configuration as type safe values, including type conversion.

  - Converting/mapping configuration using operators and queries.

  - An SPI providing abstractions for handling property sources, property filters and component lifecycle management.

- The Core implements the API. Basically with the core part (and the API) you are ready to go, but you may want to add additional extensions that provide more features that are very useful.

- Extensions are additional libraries that you can add to your project setup. Most important features are:

  - Dynamic resolution of configured values.

  - Pattern based resource location

  - Configuration injection and configuration template support

  - Support for additional configuration formats

  - Collection Support

  - Prepared configuration metamodels

  - Integration with other frameworks as configuration consumer or producer.

- Finally the documentation module provides comprehensive documentation on all features provided.

### 1.7. Required Java version

The full API is based on Java SE 8.0 language features, whereas a compatible implementation of API and Core is similarly available for Java SE 7 as well.

## 2. Where should I continue

### 2.1. Further Documentation

- If you want to have a deeper look at the API/SPI, we recommend the API documentation.

- If you want to have an overview about the available modules, continue here.

- If you want to look to the numerous examples, continue here.

- If you are interested in the software design in place, continue here.

Finally * If you are interested in the collected requirements, continue here. * If you are interested in the collected use cases, continue here.

### 2.2. API Documentation

Javadoc of the current API

- General API Documentation and API Javadoc for Java7 / API Javadoc for Java8

Javadoc of the current Core Implementation

- General Core Documentation and Core Javadoc for Java7 / Core Javadoc for Java8

Javadoc of the current Extension Modules

### 2.3. Examples

A comprehensive set of examples can be found here.