content/documentation/extensions/mod_vertx.adoc

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

= Apache Tamaya - Extension: Integration for Vertx

toc::[]


[[JNDI]]
== Integration with Vertx (Extension Module)
Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.

=== What functionality this module provides ?

Tamaya _Vertx_ provides configuration services that can be used in a Vertx environment:

* +AbstractConfiguredVerticle+ defines a subclass extending +AbstractVerticle+, which allows you to
  use Tamaya Injection API.
* Additionally you deply a +ConfigVerticle+, which registers services to access configuration
  using asynchronous event bus.


=== Compatibility

The module requires Java 8.


=== Installation

To use Tamaya's _Vertx_ support you only must add the corresponding dependency to
your module:

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


=== The Functionality Provided

NOTE: This module is in alpha state. Please give feedback via our JIRA, so we can improve it.


==== Extending AbstractConfiguredVerticle

Main artifact is the +AbstractConfiguredVerticle+ class, which implements a
base verticle class for Vertx:

[source, java]
-----------------------------------------------
public abstract class AbstractConfiguredVerticle extends AbstractVerticle{

    private Configuration configuration;

    public AbstractConfiguredVerticle() {
        configure();
    }

    public Configuration getConfiguration(){
        if(this.configuration==null){
          this.configuration = Configuration.current();
        }
        return this.configuration;
    }

    public void setConfiguration(Configuration configuration){
        this.configuration = configuration;
        configure();
    }

    protected void configure(){
        ConfigurationInjector.getInstance().configure(this, getConfiguration());
    }

    protected final String getConfigProperty(String key);
    protected final String getConfigPropertyOrDefault(String key, String defaultValue);
    protected final <T> T getConfigProperty(String key, Class<T> type);
    protected final <T> T getConfigPropertyOrDefault(String key, Class<T> type, T defaultValue);
}
-----------------------------------------------

Using this verticle as a superclass, provides you

* embedded convenience methods for programmatic configuration access (+getConfigProperty*+ methods).
* support for configuration injection based on link:../mod_injection.html[Tamaya's injection API].


The following code snippet gives you an example, what you can do with this functionality:

[source, java]
-----------------------------------------------
public cllass MyVerticle extends AbstractConfiguredVerticle{

   @Override
   public void start(){
     String configuredValue = getConfigPropertyOrDefault("myKey");
     [...]
     BigDecimal bd = getConfigureddPropertyOrDefault("MyNum", BigDecimal.ZERO);
     [...]
   }
}
-----------------------------------------------


As menioned you can also use the injection API:

[source, java]
-----------------------------------------------
public cllass MyVerticle extends AbstractConfiguredVerticle{

   @Config("myKey")
   private String configuredValue;

   @Config(value="MyNum", defaultValue="0.0")
   private BigDecimal bd;


   @Override
   public void start(){
     [...]
   }
}
-----------------------------------------------


==== Accessing Configuration using the Vertx event bus

Additionally the extension allows to access configuration values from the event bus:

[source, java]
-----------------------------------------------
@Override
public void start(){
  // the selector allows to apply a regex on the configuration key to select a
  // a configuration sub set.
  String selector = "user.";
  vertx().eventBus().send(
                "CONFIG-MAP", // event bus address
                selector,
                new Handler<AsyncResult<Message<String>>>() {
                    @Override
                    public void handle(AsyncResult<Message<String>> reply) {
                        testContext.assertNotNull(reply.result());
                        testContext.assertNotNull(reply.result().body());
                        Map<String,String> config = Json.decodeValue(reply.result().body(),
                                Map.class);
                        // do something with the config
                        // ...
                    }
                 });
-----------------------------------------------


Similar only single values can be accessed:

[source, java]
-----------------------------------------------
@Override
public void start(){
  vertx().eventBus().send(
             "CONFIG-VAL", // event bus address
             "user.home",  // property key
             new Handler<AsyncResult<Message<String>>>() {
                       @Override
                       public void handle(AsyncResult<Message<String>> reply) {
                           String value = reply.result().body();
                           // do something with the config value
                           // ...
                       }
                   });
-----------------------------------------------


Finally the event bus targets to be used can be configured using Tamaya configuration,
see the code snippet from the implementation:

[source, java]
-----------------------------------------------
@Config(value = "tamaya.vertx.config.map", defaultValue = "CONFIG-MAP")
private String mapBusTarget;

@Config(value = "tamaya.vertx.config.value", defaultValue = "CONFIG-VAL")
private String valBusTarget;
-----------------------------------------------