Repository: incubator-tamaya-site Updated Branches: refs/heads/master 8f1fa3a86 -> d7b279051
TAMAYA-238: Unified CDI injection modules. 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/d7b27905 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/d7b27905 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/d7b27905 Branch: refs/heads/master Commit: d7b2790519add746120ba63dc18e9cd51d68aaaf Parents: 8f1fa3a Author: anatole <anat...@apache.org> Authored: Sun Mar 19 23:16:46 2017 +0100 Committer: anatole <anat...@apache.org> Committed: Sun Mar 19 23:16:46 2017 +0100 ---------------------------------------------------------------------- content/documentation/extensions.adoc | 32 ++++++------- content/documentation/extensions/mod_cdi.adoc | 52 ++++++++++++---------- 2 files changed, 45 insertions(+), 39 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/d7b27905/content/documentation/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc index b8e082a..bc1fd83 100644 --- a/content/documentation/extensions.adoc +++ b/content/documentation/extensions.adoc @@ -22,7 +22,6 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati |+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation] -|+org.apache.tamaya.ext:tamaya-injection-cdi-se+ | Java EE/standalone compliant CDI integration using Tamaya SE injection mechanism. | link:extensions/mod_cdi.html[Documentation] |+org.apache.tamaya.ext:tamaya-jndi+ |Provides a JNDI based PropertySource. |link:extensions/mod_jndi.html[Documentation] |+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation] |+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation] @@ -48,21 +47,22 @@ NOTE: All extensions currently run on Java 7 as well as on Java 8. [width="100%",frame="1",options="header",grid="all"] |======= |_Artifact_ |_Description_ |_Links_ -|+org.apache.tamaya.ext:tamaya-camel+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation] +|+org.apache.tamaya.ext:tamaya-camel_beta+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation] |+org.apache.tamaya.ext:tamaya-classloader-support+ |Configuration services considering classloaderas. |link:extensions/mod_classloader_support.html[Documentation] -|+org.apache.tamaya.ext:tamaya-commons+ |Integration Support for Apache Commons. | - -|+org.apache.tamaya.ext:tamaya-configured-sysprops+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] -|+org.apache.tamaya.ext:tamaya-consul+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation] -|+org.apache.tamaya.ext:tamaya-etcd+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation] -|+org.apache.tamaya.ext:tamaya-hazelcast+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation] -|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation] -|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] -|+org.apache.tamaya.ext:tamaya-metamodel+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation] -|+org.apache.tamaya.ext:tamaya-osgi+ |Integration with OSGI containers. | link:extensions/mod_osgi.html[Documentation] -|+org.apache.tamaya.ext:tamaya-remote+ |Remote configuration support using the server API. |link:extensions/mod_remote.html[Documentation] -|+org.apache.tamaya.ext:tamaya-server+ |Publishes configuration as a REST service. |link:extensions/mod_server.html[Documentation] -|+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-commons_beta+ |Integration Support for Apache Commons. | - +|+org.apache.tamaya.ext:tamaya-configured-sysprops_beta+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] +|+org.apache.tamaya.ext:tamaya-consul_beta+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation] +|+org.apache.tamaya.ext:tamaya-etcd_beta+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation] +|+org.apache.tamaya.ext:tamaya-hazelcast_beta+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation] +|+org.apache.tamaya.ext:tamaya-jodatime_beta+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation] +|+org.apache.tamaya.ext:tamaya-management_alpha+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] +|+org.apache.tamaya.ext:tamaya-metamodel_alpha+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation] +|+org.apache.tamaya.ext:tamaya-osgi_alpha+ |Integration with OSGI containers. | link:extensions/mod_osgi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-remote_alpha+ |Remote configuration support using the server API. |link:extensions/mod_remote.html[Documentation] +|+org.apache.tamaya.ext:tamaya-server_alpha+ |Publishes configuration as a REST service. |link:extensions/mod_server.html[Documentation] +|+org.apache.tamaya.ext:tamaya-ui_alpha+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation] +|+org.apache.tamaya.ext:tamaya-uom_beta+ |Provides additional converters based on the Units of Measurement JSR. |link:extensions/mod_uom.html[Documentation] +|+org.apache.tamaya.ext:tamaya-usagetracker_beta+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation] +|+org.apache.tamaya.ext:tamaya-validation-alpha+ |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/d7b27905/content/documentation/extensions/mod_cdi.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_cdi.adoc b/content/documentation/extensions/mod_cdi.adoc index b980642..24a85a6 100644 --- a/content/documentation/extensions/mod_cdi.adoc +++ b/content/documentation/extensions/mod_cdi.adoc @@ -14,23 +14,23 @@ Tamaya _CDI_ is an extension module. Refer to the link:../extensions.html[extens === What functionality this module provides ? -Apache Tamaya currently provides two implementations for integration with CDI extensions implementing similar -functionality as described in this document: +Apache _CDI_ provides integration with CDI: * Loading of CDI managed SPI components as configuration extensions such as +PropertySources, PropertySourceProviders, PropertyFilters, etc+. This also includes SPI defined by any Tamaya submodules. This is useful when Tamaya is used as an application module managed by the CDI implementation. -* Implement and enable Tamaya's configuration injection services with CDI. +* Implement and enable Tamaya's configuration injection services (either using CDI injection or + Tamaya's standalone injection module. Hereby there are two implementations provided: -* +tamaya-cdi-ee+ implements injection by using CDI's injection mechanism to inject configuration values into the +* +tamaya-injection-cdi+ implements injection by using CDI's injection mechanism to inject configuration values into the beans managed by the CDI systems. -* +tamaya-cdi-se+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used +* +tamaya-injection-standalone+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas beans and injection control overall are still managed by CDI. -* One difference, of course, is that +tamaya-se+ also provides an SE compatible API (+ConfigurationInjection, - ConfigurationInjector+), which is not available, when using the purely Java EE based variant. +* One difference, of course, is that +tamaya-injection-standalone+ also provides an SE compatible API (+ConfigurationInjection, + ConfigurationInjector+), which is not available, when using the purely CDI based variant. The annotations used for all injection functionality in Tamaya is defined as a separate module. This allows you to code against the injection API without dependency on the concrete injection implementation. As a consequence your @@ -60,17 +60,20 @@ you never have installed both CDI extensions at the same time because this may b ----------------------------------------------- <dependency> <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-cdi-ee</artifactId> + <artifactId>tamaya-cdi</artifactId> <version>{tamaya_version}</version> </dependency> ----------------------------------------------- -.CDI injection based on Tamaya SE Application Configuration +.To use Tamaya's _standalone injection support_, you additionally should add the +following dependency. If this dependency is missing injection is purely based on +CDI injection features. + [source, xml] ----------------------------------------------- <dependency> <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-cdi-se</artifactId> + <artifactId>tamaya-injection-standalone</artifactId> <version>{tamaya_version}</version> </dependency> ----------------------------------------------- @@ -78,11 +81,7 @@ you never have installed both CDI extensions at the same time because this may b Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they register CDI extensions that implement Configuration injection as described before. -IMPORTANT: Never install Tamaya's +tamaya-cdi-se+ and +tamaya-cdi-ee+ on the same system, since unpredictable side - effects could occur. - - -For working with a pure non Java EE environment have a look at the link:mod_injection.html[tamaya-injection module]. +For working with a pure non Java EE environment have a look at the link:mod_injection-standalone.html[tamaya-injection-standalone module]. Additionally you have to register Tamaya's CDI extension modules into your `beans-xml`: @@ -90,9 +89,18 @@ Contents of `META-INF/services/javax.enterprise.inject.spi.Extension`: [source, properties] ----------------------------------------------- # Register Tamaya to perform injection -org.apache.tamaya.integration.cdi.ConfigurationExtension +# org.apache.tamaya.cdi.TamayaCDIInjectionExtension +# org.apache.tamaya.cdi.TamayaSEInjectionExtension +org.apache.tamaya.cdi.TamayaCDIAccessor ----------------------------------------------- +If you want to use CDI standard injection (using +@Inject @Config+), activate ++org.apache.tamaya.cdi.TamayaCDIInjectionExtension+ as a CDI extension. + +If you want to use +SE based injection+ (using +@Config+ *without* +@Inject+), +activate +org.apache.tamaya.cdi.TamayaSEInjectionExtension+ instead of. + +Though not recommended, it is possible to activate both extension at the same time. === Annotating your Classes @@ -110,8 +118,8 @@ public class ConfiguredClass{ @Config private String testProperty; - @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"}) - @ConfigDefault("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") + @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"}, + defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") String value1; @Config({"foo","a.b.c.key2"}) @@ -121,12 +129,10 @@ public class ConfiguredClass{ @ConfigDefault("N/A") private String runtimeVersion; - @Config - @ConfigDefault("${sys:java.version}") + @Config(defdaultValue="${sys:java.version}") private String javaVersion2; - @Config - @ConfigDefault("5") + @Config(defaultValue="5") private Integer int1; ... @@ -190,7 +196,7 @@ Contents of `META-INF/services/org.apache.tamaya.spi.ServiceContext`: [source, properties] ----------------------------------------------- # Registering a CDI aware service context -org.apache.tamaya.integration.cdi.CDIAwareServiceContext +CDIAwareServiceContext -----------------------------------------------