→ add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg

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

This document describes the Tamaya Configuration System. It provides an overview of the different building blocks and links you to more detailed documentations.

1.1. 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.2. 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.2.1. 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

1.3. Required Java version

The full API is based on Java SE 8.0 language features, whereas a compatible PI is similarly available for Java SE 7.

2. Design Documentation

2.1. How is Tamaya organized

The Tamaya project consists of the following parts:

  • The API is a complete SE based configuration API, that provides the absolute minimum of functionality needed. It is modelled in a minimal, but expendable way. It should be easily implemented within a few kb, so it is also possible to use it witin Java ME. The main features supported by the minimal API are:

    • Reading configuration as String/String key/value pairs

    • Reading configuration as type safe values, including transparent conversion.

    • Extending configuration using operators and queries.

    • An SPI providing abstractions for component lifecycle, property sources, peroperty source providers, configuration context and property filters.

  • The "core* part implements the API. Basically with the core part and the API you are ready to go, but you may add additional extensions that provide additional features that are very useful.

  • Extensions are additional libraries that you can add to your project setup. Most important features implemented by modules are

    • Dynamic resolution of configured values.

    • Pattern based resource location

    • Configuration injection and configuration template support

    • Support for additional configuration formats

    • Prepared configuration metamodels

    • Integration with other frameworks as configuration consumer or producer.

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

4. Code Documentation

5. Examples

  • A comprehensive set of examples can be found here.