Moved collections, consul, etcd and hazelcast modules into extensions. Updated docs to match code.
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/8dd2accd Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/8dd2accd Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/8dd2accd Branch: refs/heads/master Commit: 8dd2accdecaff328afa462e36ff90350d7027ec1 Parents: 7fc31c0 Author: Anatole Tresch <[email protected]> Authored: Thu Nov 8 00:26:28 2018 +0100 Committer: Anatole Tresch <[email protected]> Committed: Thu Nov 8 00:26:28 2018 +0100 ---------------------------------------------------------------------- content/documentation/extensions.adoc | 13 +- .../extensions/mod_classloader_support.adoc | 2 +- .../documentation/extensions/mod_consul.adoc | 42 +++-- content/documentation/extensions/mod_etcd.adoc | 165 +++---------------- .../documentation/extensions/mod_hazelcast.adoc | 57 ++----- 5 files changed, 68 insertions(+), 211 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc index 098652c..3186910 100644 --- a/content/documentation/extensions.adoc +++ b/content/documentation/extensions.adoc @@ -13,23 +13,26 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati |======= |_Artifact_ |_Description_ |_Links_ |+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.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-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation] |+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. |link:extensions/mod_filter.html[Documentation] |+org.apache.tamaya.ext:tamaya-features+ |Provides a simple feature check for loaded extensions. |link:extensions/mod_features.html[Documentation] |+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation] |+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation] +|+org.apache.tamaya.ext:tamaya-hazelcast+ |Integration with Hazelcast datagrids. |link:extensions/mod_hazelcast.html[Documentation] |+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 configuration 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-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-microprofile+ |Implemenation and Integration with the Microprofile API. | link:extensions/mod_microprofile.html[Documentation] +|+org.apache.tamaya.ext:tamaya-microprofile+ |Implemenation and Integration with the Microprofile API. |link:extensions/mod_microprofile.html[Documentation] |+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation] |+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation] |+org.apache.tamaya.ext:tamaya-osgi+ |Integration with OSGI containers. |link:extensions/mod_osgi.html[Documentation] |+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] -|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation] -|+org.apache.tamaya.ext:tamaya-spring+ |Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation] +|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation] +|+org.apache.tamaya.ext:tamaya-spring+ |Integration for Spring / Spring Boot. |link:extensions/mod_spring.html[Documentation] |+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] |======= @@ -45,12 +48,8 @@ us getting them stable and well tested! |======= |_Artifact_ |_Description_ |_Links_ |+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_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] http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_classloader_support.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_classloader_support.adoc b/content/documentation/extensions/mod_classloader_support.adoc index 6037153..d816f50 100644 --- a/content/documentation/extensions/mod_classloader_support.adoc +++ b/content/documentation/extensions/mod_classloader_support.adoc @@ -11,7 +11,7 @@ toc::[] Tamaya _Classloader_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. CAUTION: Classloader support has been added into the main API and implementation module. This module probably is not - useful anymore and will probably be removed in the future. + useful anymore and will be removed in the future. === What functionality this module provides ? http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_consul.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_consul.adoc b/content/documentation/extensions/mod_consul.adoc index 8a988a5..094e8be 100644 --- a/content/documentation/extensions/mod_consul.adoc +++ b/content/documentation/extensions/mod_consul.adoc @@ -1,7 +1,7 @@ :jbake-type: page :jbake-status: published -= Apache Tamaya - Extension: Integration with consul (Hashicorp) += Apache Tamaya - Extension: Integration with Consul (Hashicorp) toc::[] @@ -22,7 +22,7 @@ defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension mod === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation @@ -39,28 +39,38 @@ To use _tamaya-consul_ you only must add the corresponding dependency to your mo ----------------------------------------------- -=== The Extensions Provided +=== The Functionality Provided -Consul integration comes basically with 2 artifacts: +Tamaya Consul provides two artifacts: -* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default - ordinal of 100 and the name 'consul', which is automatically registered. -* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster, - by accessing a +MutableConfiguration+ using the URI +config:consul+. +* The +org.apache.tamaya.consul.ConsulPropertySource+ is a +PropertySource+ with a default + ordinal of 100 and the name 'consul'. +* +org.apache.tamaya.consul.ConsulPropertySource+ is based on +org.apache.tamaya.consul.AbstractConsulPropertySource+, + which provides all required basic functionality to implement your own consul based property + sources. Access of consul key/value pairs is through the normal Tamaya API. === The ConsulPropertySource -The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This -enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running -in microservice containers to connect with the according consul cluster: +The +ConsulPropertySource+ allows the consul servers to be used as configuration backends. It provides: -* The property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible consul servers - (comma separated), which can be connected to. On failure the API just performs a Round-Robin through the list of +* a Consul based property source implementation. +* configurable caching of key/values accessed (Consul does not provide reading all values out). +* configuring a optional key prefix for defining a namespace for Tamaya configuration within the consul key/value + store. +* +ConsulPropertySource+ reads the +tamaya.consul.urls+ system and environment property to evaluate the consul servers + to be used (comma separated). The API just performs a Round-Robin through the list of configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul server can be established a warning will be logged, but deployment will not fail. -* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed - context. This can be activated by setting the `-Dtamaya.consul.prefix=<PREFIX>` system property. E.g. when the prefix is - set to `cluster-config.` a consul key of `host:known/all` is mapped to `cluster-config.host:known/all`. +* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped with a prefix. + This allows to let all values stored in consul have their own namespace. E.g. the Tamaya key `a.b` is mapped + to `foo.a.b`, when the prefix is set to `foo.`. The prefix can be activated by setting the + `tamaya.consul.prefix` system or environment property. + + +=== The AbstractConsulPropertySource + +The +AbstractConsulPropertySource+ provides all features from +ConsulPropertySource+ but does not define how the +property source is exactly configured, so you have full control. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_etcd.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_etcd.adoc b/content/documentation/extensions/mod_etcd.adoc index 3003a09..536ff41 100644 --- a/content/documentation/extensions/mod_etcd.adoc +++ b/content/documentation/extensions/mod_etcd.adoc @@ -12,7 +12,7 @@ Tamaya _Etcd_ is an extension module. Refer to the link:../extensions.html[exten === What functionality this module provides ? -Tamaya _Etcd_ provides different artifacts which allows using link:https://github.com/coreos/etcd[etcd] as a +Tamaya _Etcd_ provides artifacts, which allow using link:https://github.com/coreos/etcd[etcd] as a configuration backend. Basically the module adds a read-only property source (+EtcdPropertySource+). If the _tamaya-mutable-config_ extension is loaded it is alos possible to write configuration changes to _etcd_ using +MutableConfiguration+. @@ -20,7 +20,7 @@ changes to _etcd_ using +MutableConfiguration+. === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation @@ -38,155 +38,32 @@ your module: ----------------------------------------------- -=== The Extensions Provided +=== The Functionality Provided Tamaya's _etcd_ integration provides basically the following artifacts: -* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint - root. The accessor basically provides a simple Java API for communicating with the _etcd_ server. The - accessor hereby allows reading of single properties, or whole subtrees. Also the basic non - atomic write methods are implemented. -* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name - 'etcd', which is automatically registered. -* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster, - by accessing a +MutableConfiguration+ using the URI +config:etcd+. - -=== The EtcdAccessor - -The accessor implements the basic read and write API for communicating with an _etcd_ server. -Hereby the accessor also provides _etcd_ specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+ -returned. Hereby the concept of _etcd_ is used where keys starting with an '_' represent meta-configuration -that will be hidden from the overall properties map, being only directly/explicitly accessible: - -[source, java] ------------------------------------------------ -public class EtcdAccessor { - - /** - * Creates a new instance with the basic access url. - * @param server server url, e.g. {@code http://127.0.0.1:4001}. - * @throws MalformedURLException - */ - public EtcdAccessor(String server) throws MalformedURLException; - - /** - * Get the etcd server version. - * @return the etcd server version, never null. - */ - public String getVersion(); - - /** - * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd: - * <pre> - * key=value - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 // optional - * _key.ttl=300 // optional - * _key.expiration=... // optional - * </pre> - * @param key the requested key - * @return the mapped result, including meta-entries. - */ - public Map<String,String> get(String key); - - /** - * Creates/updates an entry in etcd without any ttl set. - * The response is as follows: - * <pre> - * key=value - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 // optional - * _key.prevNode.createdIndex=12 // optional - * _key.prevNode.modifiedIndex=34 // optional - * </pre> - * @param key the property key, not null - * @param value the value to be set - * @return the result map as described above. - */ - public Map<String,String> set(String key, String value); - - /** - * Creates/updates an entry in etcd. The response is as follows: - * <pre> - * key=value - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 // optional - * _key.ttl=300 // optional - * _key.expiry=... // optional - * _key.prevNode.createdIndex=12 // optional - * _key.prevNode.modifiedIndex=34 // optional - * _key.prevNode.ttl=300 // optional - * _key.prevNode.expiration=... // optional - * </pre> - * @param key the property key, not null - * @param value the value to be set - * @param ttlSeconds the ttl in seconds (optional) - * @return the result map as described above. - */ - public Map<String,String> set(String key, String value, Integer ttlSeconds); - - - /** - * Deletes a given key. The response is as follows: - * <pre> - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 - * _key.ttl=300 // optional - * _key.expiry=... // optional - * _key.prevNode.createdIndex=12 // optional - * _key.prevNode.modifiedIndex=34 // optional - * _key.prevNode.ttl=300 // optional - * _key.prevNode.expiration=... // optional - * _key.prevNode.value=... // optional - * </pre> - * @param key the key to be deleted. - * @return the response mpas as described above. - */ - public Map<String,String> delete(String key); - - - /** - * Access regular Tamaya properties map as follows: - * <pre> - * key1=myvalue - * _key1.source=[etcd]http://127.0.0.1:4001 - * _key1.createdIndex=12 - * _key1.modifiedIndex=34 // optional - * _key1.ttl=300 // optional - * _key1.expiration=... // optional - * - * key2=myvaluexxx - * _key2.source=[etcd]http://127.0.0.1:4001 - * _key2.createdIndex=12 - * - * key3=val3 - * _key3.source=[etcd]http://127.0.0.1:4001 - * _key3.createdIndex=12 - * _key3.modifiedIndex=2 - * </pre> - */ - public Map<String,String> getProperties(String directory, boolean recursive); - -} ------------------------------------------------ +* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a ready-to-use +PropertySource+ with a default ordinal of 100 and + the name 'etcd'. +* The +org.apache.tamaya.etcd.AbstractEtcdPropertySource+ is a abstract base +PropertySource+ you can use to + implement your own etcd propertysource. === The EtcdPropertySource -The +EtcdPropertySource+ is automatically registered and allows to configure the _etcd_ servers to be used. This -enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running -in microservice containers to connect with the according etcd cluster: +The +EtcdPropertySource+ is a ready-to-use property source implementation for etcd. For use you must simply register it +with the Java `ServiceLoader` od include it in a +PropertySourceProvider+. It provides: -* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers - (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of +* a etcd based property source implementation. +* configurable caching of key/values. +* configuring a dedicated etcd directory ID to be used. +* The property source reads the +tamaya.etcd.server+ system or environment property to evaluate the etcd servers + (comma separated). The API hereby just performs a Round-Robin through the list of configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd server can be established a warning will be logged, but deployment will not fail. -* Additionally also the accessor allows to configure the socket/connection timeouts by setting - +tamaya.etcd.timeout+ in seconds either as system or environment property. -* The +EtcdPropertySource+ finally also allows the values read from the _etcd_ cluster to be mapped to prefixed - context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is - set to `cluster-config.` a etcd key of `host:known/all` is mapped to `cluster-config.host:known/all`. +* Additionally with +tamaya.etcd.timeout+ system or environment property you can configure the connection timeout + in seconds. + +=== The AbstractEtcdPropertySource + +The +AbstractEtcdPropertySource+ is the base class used by +EtcdPropertySource+. Use it to implement your own custom +etcd property source. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_hazelcast.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_hazelcast.adoc b/content/documentation/extensions/mod_hazelcast.adoc index 13487a9..c8cecca 100644 --- a/content/documentation/extensions/mod_hazelcast.adoc +++ b/content/documentation/extensions/mod_hazelcast.adoc @@ -23,7 +23,7 @@ defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension mod === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation @@ -56,50 +56,15 @@ Access of consul key/value pairs is through the normal Tamaya API. === The HazelcastPropertySource The +HazelcastPropertySource+ is not automatically registered and provides different options how to integrate -Tamaya with Hazelcast. +Tamaya with Hazelcast. It provides: -[source, java] ------------------------------------------------ -/** - * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and - * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}. - */ -public HazelcastPropertySource(); - -/** - * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and the - * given hazelcast instance. - * @param hazelcastInstance the hazelcast instance, not null. - */ -public HazelcastPropertySource(HazelcastInstance hazelcastInstance); - -/** - * Creates a new instance, hereby using the given property source name and - * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}. - * @param name the property source name, not null. - */ -public HazelcastPropertySource(String name); - -/** - * Creates a new instance, hereby using the given property source name and - * a creating a new hazelcast backend using the given Hazelcast {@link Config}. - * @param config the hazelcast config, not null. - * @param name the property source name, not null. - */ -public HazelcastPropertySource(String name, Config config); - -/** - * Creates a new instance, hereby using the given property source name and the - * hazelcast instance. - * @param name - * @param hazelcastInstance - */ -public HazelcastPropertySource(String name, HazelcastInstance hazelcastInstance); ------------------------------------------------ +* a Hazelcast based property source implementation. +* configurable caching of key/values. +* configuraing a dedicated Hazelcast map ID to be used. To use hazelcast as a configuration backend, you simply create the corresponding Hazelcast instance -and use it to initialize the Tamaya property source. Given that a hazelcast backedn configuration -can be easily created asillustrated below: +and use it to initialize the Tamaya property source. Given that a hazelcast backend configuration +can be easily created as illustrated below: [source, java] ----------------------------------------------- @@ -110,10 +75,16 @@ HazelcastPropertySource ps = new HazelcastPropertySource(hazelcastInstance); ps.setName("myHazelcast-config"); ps.setOrdinal(2000); // Build your own configuration context -ConfigurationContextBuilder b = ConfigurationProvider.createNewConfigurationContextBuilder(); +ConfigurationBuilder b = Configuration.createConfigurationBuilder(); b.addDefaultPropertyConverters().addDefaultPropertyFilter().addDefaultPropertySources(); // Add the hazelcast property source (as most significant) b.addPropertySource(ps); // build and use the configuration Configuration config = b.build(); ----------------------------------------------- + + +=== The AbstractHazelcastPropertySource + +The +AbstractHazelcastPropertySource+ is the baseclass used by +HazelcastPropertySource+. Use it to implement your own +Hazelcast based property source. \ No newline at end of file
