Apache Tamaya — Extension: Injection

<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-injection-api</artifactId>
  <version>{tamayaVersion}</version>
</dependency>

<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-injection</artifactId>
  <version>{tamayaVersion}</version>
</dependency>

package foo.bar;

public class ConfiguredClass{

    // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
    private String testProperty;

    // Trying to resolve mutiple keys, with a default value, if none could be resolved
    @Config({"a.b.c.key1","a.b.legacyKey",area1.key2"}, defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
    String value1;

    // Typical case
    @Config("a.b.c.key2")
    private int value2;

    // resolved by default as foo.bar.ConfiguredClass.accessUrl
    // Using a (default) String -> URL converter
    @Config(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
    private URL accessUrl;

    // Config injection disabled for this property
    @NoConfig
    private Integer int1;

    // Overriding the String -> BigDecimal converter with a custom implementation.
    @Config("BD")
    @WithPropertyConverter(MyBigDecimalRoundingAdapter.class)
    private BigDecimal bigNumber;

    ...
}

. An autoinjected bean class
--------------------------------------------
package a.b;

  public int getId(){
    return id;
  }
  public String getName(){
    return name;
  }
  public String getDescription(){
    return description;
  }
}

These examples do not show all possibilities provided. Configuring instance of these
class using Tamaya is very simple: Just pass the instance to Tamaya to let
Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible):

[source,java]
.Configuring the +ConfiguredClass+ Instance

NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
documentation.


=== The Annotations in detail
==== The ConfigurationInjector

The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured
by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed
hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
tries to determine configuration for each property of an instance passed, using the following resolution policy:

Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
[source, listing]

So given the following properties:

[source, properties]

==== Accessing ConfiguredItemSupplier instances

In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
by the current context. This can be done using +Suppliers+:

[source, java]

With Java 8 it's even more simpler:

[source, java]

Hereby this annotation can be used in multiple ways and combined with other annotations such as +@DefaultValue+,
+@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+.

==== Minimal Example

To illustrate the mechanism below the most simple variant of a configured class is given:

[source,java]
.Most simple configured class

When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
the following is happening:

* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
  keys are possible).
* if not successful, an error is thrown (+ConfigException+)
* On success, since no type conversion is involved, the value is injected.

==== Using @DefaultValue

In the next example we explicitly define the property value:
[source,java]

  @Config({"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
  private String aValue;
}

==== Inject a DynamicValue Property

Within this example we evaluate a dynamic value. This mechanism allows you to listen for configuration changes and to
commit new values exactly, when convenient for you.

[source,java]

  @Config({"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
  private DynamicValue aValue;
}

The +DynamicValue+ provides you the following functionality:

[source,java]

enum UpdatePolicy{
    IMMEDIATE,
    EXPLCIT,
    NEVER,
    LOG_AND_DISCARD
}

T get();
T getNewValue();
T evaluateValue();
T commitAndGet();
void commit();
void discard();
boolean updateValue();

void setUpdatePolicy(UpdatePolicy updatePolicy);
UpdatePolicy getUpdatePolicy();
void addListener(PropertyChangeListener l);
void removeListener(PropertyChangeListener l);

boolean isPresent();
T orElse(T other);
T orElseGet(ConfiguredItemSupplier<? extends T> other);
<X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;

Summarizing this class looks somehow similar to the new +Optional+ class added with Java 8. It provides
a wrapper class around a configured instance. Additionally this class provides functionality that gives
active control, to manage a configured value based on a ++LoadingPolicy+:

* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
  is automatically applied without any further notice.
* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
  returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
  hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
  +discard()+.
* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.

Summarizing a +DynamicValue+ allows you

* to reload actively updates of configured values.
* update implicitly or explicitly all changes on the value.
* add listeners that observe changes of a certain value.

Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+. Hereby the value of the
instance is not changed.


==== Ommitting Injection using @NoConfig

Adding the @NoConfig annotation prevents a field or method to be auto-injected from
configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with auto-confiuration
turned on as follows:

[source,java]

@NoConfig
private transient int sum;

  private String a;
  private String b;
  Private String c;
}

In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
configuration.

==== Adding custom operators using @WithConfigOperator

The @WithConfigOperator annotation allows you define a class of type +ConfigOperator+, to being applied
to the final +Configuration+, BEFORE the value is injected. This can be used for various use cases, e.g.
filtering or validating the visible properties for a certain use case.

[source,java]

@Config
private String a;

==== Adding custom property converters using @WithPropertyConverter

The @WithPropertyConverter annotation allows you to define a class of type +PropertyConverter+, to be applied
on a property configured to convert the String value to the expected injected type. This can be used for
various use cases, e.g. adding custom formats, config models, decryption.

[source,java]

@WithPropertyConverter(MyPropertyConverter.class)
@Config
private String a;

==== Defining the loading policy to be applied to configured values using @WithLoadPolicy

The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The +LoadPolicy+
enum hereby defines the various loading modes.

[source,java]

@WithPropertyConverter(MyPropertyConverter.class)
@Config
private String a;

=== Configuration Events

Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
event backend in use, if and how events are published:

* when you have the CDI extension active events are published using the default CDI event mechanism.
* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
* if no event delegation is available no events are published.

The event published is very simple:

[source,java]