content/documentation/extensions/mod_optional.adoc

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

= Apache Tamaya - Extension: Optional Tamaya Configuration

toc::[]


[[Optional]]
== Tamaya Optional (Extension Module)

Tamaya _Optional_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.

=== What functionality this module provides ?

Tamaya _Optional_  is for projects that want to benefit from Tamaya configuration optionally only.
E.g. doing an OSS project you can declare to support configuration with Tamaya as
an optional extension. This module can be added as a hard dependency to your code, hereby adding only
three artifacts. The _optional_ module automatically checks the availability of Tamaya on the
classpath and only if available it tries to access it for configuration evaluation.
Additionally an +EvaluationPolicy+ lets you define the precedence of configured values
(yours, or Tamaya ones, if present).


=== Compatibility

The module is based on Java 8.


=== Installation

To use Tamaya _optional_ you only must add the corresponding dependency to your module:

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


=== Reading configuration using the Tamaya Optional Module

Tamaya _Optional_ allows reading configuration with a small subset of functionality only. For more
 advanced use cases consider using the Apache Tamaya as your main configuration API. When
 creating your +OptionalConfiguration+ instance you also pass the logic to access a value
 with your own configuration logic. Tamaya Optional will delegate to your logic as needed
 (depending on the `EvaluationPolicy`).

[source, java]
-----------------------------------------------
BigDecimal interestRate =
                 OptionalConfiguration.of(
                    EvaluationPolicy.TAMAYA_OVERRIDES_OTHER,
                    (k) -> MyConfigMechanism.get(k) // String get(String key);
                 )
                .get("com.mycomp.ratecalculator.rate", BigDecimal.class))
                .orElse(BigDecimal.of(0.05d));
-----------------------------------------------