Repository: incubator-tamaya-site Updated Branches: refs/heads/master 5a66c777e -> 8f1fa3a86
TAMAYA-256: Fixed Java version, tests and added documentation for Vertx support. Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/8f1fa3a8 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/8f1fa3a8 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/8f1fa3a8 Branch: refs/heads/master Commit: 8f1fa3a86e2979ccc3424905b3714f8d4763cece Parents: 5a66c77 Author: anatole <anat...@apache.org> Authored: Sat Mar 11 00:04:29 2017 +0100 Committer: anatole <anat...@apache.org> Committed: Sat Mar 11 23:37:22 2017 +0100 ---------------------------------------------------------------------- content/documentation/extensions.adoc | 1 + content/documentation/extensions/mod_vertx.adoc | 189 +++++++++++++++++++ 2 files changed, 190 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8f1fa3a8/content/documentation/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc index 0c643f1..b8e082a 100644 --- a/content/documentation/extensions.adoc +++ b/content/documentation/extensions.adoc @@ -64,4 +64,5 @@ NOTE: All extensions currently run on Java 7 as well as on Java 8. |+org.apache.tamaya.ext:tamaya-ui+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation] |+org.apache.tamaya.ext:tamaya-usagetracker+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation] |+org.apache.tamaya.ext:tamaya-validation+ |Provides an XML API for validating configuration. |link:extensions/mod_validation.html[Documentation] +|+org.apache.tamaya.ext:tamaya-vertx-alpha+ |Provides Vertx integration. |link:extensions/mod_vertx.html[Documentation] |======= http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8f1fa3a8/content/documentation/extensions/mod_vertx.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_vertx.adoc b/content/documentation/extensions/mod_vertx.adoc new file mode 100644 index 0000000..4bb93d5 --- /dev/null +++ b/content/documentation/extensions/mod_vertx.adoc @@ -0,0 +1,189 @@ +: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, so it will not run on Java 7. + + +=== Installation + +To use Tamaya's _Vertx_ support you only must add the corresponding dependency to +your module: + +[source, xml] +----------------------------------------------- +<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 = ConfigurationProvider.getConfiguration(); + } + return this.configuration; + } + + public void setConfiguration(Configuration configuration){ + this.configuration = configuration; + configure(); + } + + protected void configure(){ + ConfigurationInjection.getConfigurationInjector().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; +----------------------------------------------- +