| :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="verbatim,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="verbatim,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="verbatim,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,subs="verbatim,attributes"] |
| ---- |
| Collection<URL> urls = Resolver.getInstance().getResources("META-INF/cfg/**/*.properties"); |
| ---- |
| |
| For further details refer to the module documentation. |
| |
| |
| ==== Configuration Injection |
| |
| [source,xml,subs="verbatim,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,subs="verbatim,attributes"] |
| ---- |
| 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,subs="verbatim,attributes"] |
| ---- |
| 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. |
| |
| |=== |