content/documentation/quickstart.adoc

:jbake-type: page
:jbake-status: published

== Apache Tamaya: Quickstart


The fastest way to start with Tamaya is just using the _Core_ module, which
provides a simple configuration API. To start add the following
dependency to your project:

[source, xml, subs=attributes+]
----
<dependency>
    <groupId>{tamaya_mvn_group_id}</groupId>
    <artifactId>tamaya-core</artifactId>
    <version>{tamaya_version}</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:

[source,java]
----
Configuration config = Configuration.current();

String aTextValue = config.getOrDefault("my.value.key", "N/A");
int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15);
BigDecimal bdValue = config.getOrDefault("my.BD.value", BigDecimal.class, BigDecimal.valueOf(120));
List<URL> urls = config.get("servers.url", new TypeLiteral<List<URL>>());
----

Of course, you can also use +Optional+ values:

[source,java]
----
String aTextValue = config.getOptional("my.value.key", String.class).orElse("N/A");
----

=== Add/define your configuration data

As seen you can start working with your configuration backend, without adding any kind of
default configuration. Nevertheless Tamaya also comes with a _default_ mechanism:
simply store your configuration into +META-INF/javaconfiguration.properties+ in your classpath!


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):

. System Properties
. Environment Properties
. `META-INF/javaconfiguration.properties`


== Advanced Topics

=== Multiple configuration files

By default you can provide multiple `javaconfiguration.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:

. the systems checks for a `tamaya.ordinal` configuration value and tries to convert to
  an `int` ordinal value.
. the systems checks if the property source has a method +int getOrdinal()+. If present
  the result is used as ordinal.
. the systems checks if the property source has a `@Priority` annotation and uses the
  annotation's value as ordinal.
. 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's Core PropertySources uses the following default ordinals:

[width=70]
[cols="3,1", option="headers"]
|===
| 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:

[source]
----
# 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 link:extensions/extensions.html[this list] for a complete
overview.

==== Dynamic Resolution and Value Placeholders

[source, xml, subs=attributes+]
----
<dependency>
  <artifactId>org.apache.tamaya.ext</id>
  <artifactId>tamaya-resolver</artifactId>
  <version>{tamaya_version}</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:

[source,java]
----
String myExpression = ...;
String resolved = Resolver.getInstance().evaluateExpression(myExpression);
----


==== Ant-styled Path Resolution of Resources

[source, xml, subs=attributes+]
----
<dependency>
  <artifactId>org.apache.tamaya.ext</id>
  <artifactId>tamaya-resolution</artifactId>
  <version>{tamaya_version}</version>
</dependency>
----

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


[source, xml]
----
Collection<URL> urls = Resolver.getInstance().getResources("META-INF/cfg/**/*.properties");
----

For further details refer to the module documentation.


==== Configuration Injection

[source, xml, subs=attributes+]
----
<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:

[source, xml]
----
public class MyType {
   @Config("my.key")
   private String typeName;

   public String getName() {
      return name;
   }
}

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

Or the same as template:

[source, xml]
----
public interface MyTypeTemplate {
   @Config("my.key")
   public String getName();
}

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

Currently the following resolvers are available:

[width="60"]
[cols="1,4"]
|===
| 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.

|===