Updated docs for JSR based release. Signed-off-by: Anatole Tresch <[email protected]>
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/5675df62 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/5675df62 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/5675df62 Branch: refs/heads/master Commit: 5675df62c37d18b3511a61040f60b8aa4e8d4221 Parents: 8951b7b Author: Anatole Tresch <[email protected]> Authored: Sun Apr 22 18:21:28 2018 +0200 Committer: Anatole Tresch <[email protected]> Committed: Sun Apr 22 18:22:08 2018 +0200 ---------------------------------------------------------------------- .../documentation-new/extensions/mod_camel.adoc | 2 +- .../documentation-new/extensions/mod_cdi.adoc | 64 +++++------ .../extensions/mod_classloader_support.adoc | 2 +- .../extensions/mod_collections.adoc | 13 +-- .../extensions/mod_consul.adoc | 14 +-- .../documentation-new/extensions/mod_etcd.adoc | 12 +-- .../extensions/mod_events.adoc | 84 +++++++-------- .../extensions/mod_features.adoc | 2 +- .../extensions/mod_filter.adoc | 35 +++--- .../extensions/mod_formats.adoc | 50 ++++----- .../extensions/mod_functions.adoc | 68 ++++++++---- .../extensions/mod_hazelcast.adoc | 39 ++++--- .../extensions/mod_injection.adoc | 98 ++++++++--------- .../documentation-new/extensions/mod_jndi.adoc | 10 +- .../extensions/mod_jodatime.adoc | 2 +- .../documentation-new/extensions/mod_json.adoc | 4 +- .../extensions/mod_management.adoc | 2 +- .../extensions/mod_metamodel.adoc | 56 +++++----- .../extensions/mod_microprofile.adoc | 93 ---------------- .../extensions/mod_mutable_config.adoc | 106 +++++++++---------- .../extensions/mod_optional.adoc | 2 +- .../extensions/mod_remote.adoc | 4 +- .../extensions/mod_resolver.adoc | 8 +- .../extensions/mod_resources.adoc | 14 +-- .../extensions/mod_server.adoc | 2 +- .../extensions/mod_spring.adoc | 9 +- .../extensions/mod_usagetracker.adoc | 4 +- .../extensions/mod_validation.adoc | 2 +- .../documentation-new/extensions/mod_vertx.adoc | 9 +- .../documentation-new/extensions/mod_yaml.adoc | 4 +- content/documentation-new/usecases.adoc | 46 +++----- 31 files changed, 374 insertions(+), 486 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_camel.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_camel.adoc b/content/documentation-new/extensions/mod_camel.adoc index 828a8d2..b21df17 100644 --- a/content/documentation-new/extensions/mod_camel.adoc +++ b/content/documentation-new/extensions/mod_camel.adoc @@ -19,7 +19,7 @@ configuration with Apache Camel. === 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, so it will not run on Java 8 and beyond. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_cdi.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_cdi.adoc b/content/documentation-new/extensions/mod_cdi.adoc index 41e1fb4..deb8842 100644 --- a/content/documentation-new/extensions/mod_cdi.adoc +++ b/content/documentation-new/extensions/mod_cdi.adoc @@ -16,8 +16,8 @@ Tamaya _CDI_ is an extension module. Refer to the link:../extensions.html[extens 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. +* Loading of CDI managed SPI components as configuration extensions such as +ConfigSources, ConfigSourceProviders, + Converters, Filters, 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 (either using CDI injection or Tamaya's standalone injection module. @@ -32,12 +32,18 @@ Hereby there are two implementations provided: * 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 -components will be compatible regardless if deployed in a pure SE or as Java EE (CDI) or Spring environment: +Most annotations used are defined as part of the Config JSR API, whereas Tamaya adds additional features not available +in the JSR as separate modules. This allows you to code against the injection API without dependency on the concrete +injection implementation. As a consequence your components will be compatible regardless if deployed in a pure SE or as +Java EE (CDI) or Spring environment: ----------------------------------------------- <dependency> + <groupId>javax.config</groupId> + <artifactId>config-api</artifactId> + <version>{config_api_version}</version> +</dependency> +<dependency> <groupId>org.apache.tamaya.ext</groupId> <artifactId>tamaya-injection-api</artifactId> <version>{tamaya_version}</version> @@ -47,7 +53,7 @@ components will be compatible regardless if deployed in a pure SE or as Java EE === Compatibility -All modules are based on Java 7, so they will not run on Java 7 and beyond. +All modules are based on Java 8, so they will not run on Java 8 and beyond. === Installation @@ -105,9 +111,10 @@ Though not recommended, it is possible to activate both extension at the same ti === Annotating your Classes -Basically annotating your classes is stright forward. +@Config+ defines an additional CDI qualifier that is, depending -on the module deployed, handled by a CDI producer (+tamaya-cdi-ee+) or the Tamaya SE injection mechanism $ -(+tamaya-cdi-se+). All types injected by this module are injected using _dependent scope_. +Basically annotating your classes is stright forward. Depending +on the module deployed, your annotations are handled by a CDI producer (+tamaya-cdi-ee+) or the +Tamaya SE injection mechanism (+tamaya-cdi-se+). All types injected by this module are injected +using _dependent scope_. [source, java] @@ -118,15 +125,14 @@ public class ConfiguredClass{ @Config private String testProperty; - @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"}, + @Config(key="a.b.c.key1", defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") String value1; - @Config({"foo","a.b.c.key2"}) + @Config(key="foo") private String value2; - @Config - @ConfigDefault("N/A") + @Config(defaultValue="N/A") private String runtimeVersion; @Config(defdaultValue="${sys:java.version}") @@ -152,11 +158,11 @@ the required SPI interface: [source, java] -------------------------------------------------------- @Singleton -public class TestPropertySource implements PropertySource{ +public class TestConfigSource implements ConfigSource{ final Map<String,String> config = new HashMap<>(); - public TestPropertySource(){ + public TestConfigSource(){ config.put("a.b.c.key1", "keys current a.b.c.key1"); config.put("a.b.c.key2", "keys current a.b.c.key2"); config.put("{"+getName()+"}source", getClass().getName()); @@ -182,10 +188,6 @@ public class TestPropertySource implements PropertySource{ return config; } - @Override - public boolean isScannable() { - return true; - } } -------------------------------------------------------- @@ -196,7 +198,7 @@ Contents of `META-INF/services/org.apache.tamaya.spi.ServiceContext`: [source, properties] ----------------------------------------------- # Registering a CDI aware service context -CDIAwareServiceContext +org.apache.tamaya.cdi.CDIAwareServiceContext ----------------------------------------------- @@ -205,22 +207,13 @@ CDIAwareServiceContext Beside basic configuration Tamaya also covers additional requirements: * _Reading multiple keys, where the first successful one is determining the value of the configuration, is - simply possible, by adding multiple keys to the +@Configy+ annotation. + simply possible, by defining additional keys with +@ConfigFallbackKeys+ annotation. E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows: [source,java] -------------------------------------------------------------------------------------- -@Config({"a.b", "new.b"} -private String value; --------------------------------------------------------------------------------------- - -* When you must apply a +ConfigOperator+ to your config, before reading the configuration, you can - configure one as follows: - -[source,java] --------------------------------------------------------------------------------------- -@Config({"a.b", "new.b"} -@WithConfigOperator(MyOperator.class) +@Config(key="a.b") +@ConfigFallbackKeys({"new.b"}) private String value; -------------------------------------------------------------------------------------- @@ -229,8 +222,8 @@ private String value; [source,java] -------------------------------------------------------------------------------------- -@Config({"a.b", "new.b"} -@WithPropertyConverter(MyConverter.class) +@Config(key="a.b") +@WithConverter(MyConverter.class) private MySpecialFooType value; -------------------------------------------------------------------------------------- @@ -242,7 +235,8 @@ private MySpecialFooType value; @ConfigDefaultSections({"aaaa", "new"}); public class MyType{ -@Config({"b", "[legacy.bKey]"} // lookups: "aaaa.b", "new.b", legacy.bKey +@Config(key="b"} +@ConfigFallbackKeys({"[legacy.bKey]"}) // lookups: "aaaa.b", "new.b", legacy.bKey private String value; -------------------------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_classloader_support.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_classloader_support.adoc b/content/documentation-new/extensions/mod_classloader_support.adoc index 50a3e61..501bcc8 100644 --- a/content/documentation-new/extensions/mod_classloader_support.adoc +++ b/content/documentation-new/extensions/mod_classloader_support.adoc @@ -18,7 +18,7 @@ of classloaders, hereby preventing multiple loading of components within a class === 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, so it will not run on Java 8 and beyond. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_collections.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_collections.adoc b/content/documentation-new/extensions/mod_collections.adoc index 49cead4..93cc4be 100644 --- a/content/documentation-new/extensions/mod_collections.adoc +++ b/content/documentation-new/extensions/mod_collections.adoc @@ -20,7 +20,7 @@ Collections extension adds this functionality to the Tamaya eco-system. === 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, so it will not run on Java 8 and beyond. === Installation @@ -70,6 +70,7 @@ inner-workings, e.g. * specifying the implementation type of the collection item to be returned. * specifying the implementation type of the collection to be returned. + === Supported Types This module currently supports the following types: @@ -100,8 +101,8 @@ required target type. ==== Configuring the target implementation type Tamaya Collections allows you to configure the _default_ target collection type by adding the -following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+ -can be ommitted: +following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part ++java.util.+ can be ommitted: [ source, properties] ----------------------------------------------- @@ -109,9 +110,9 @@ mylist=a,b,c _mylist.collection-type=LinkedList ----------------------------------------------- -When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still -get an +ArrayList+ as a result. However when you call +config.get("mylist", List.class)+ you will -get a +LinkedList+ as implementation type. +When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, +so you will still get an +ArrayList+ as a result. However when you call +config.get("mylist", +List.class)+ you will get a +LinkedList+ as implementation type. This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation type returned when accessing +List+, +Map+ or +Collection+. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_consul.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_consul.adoc b/content/documentation-new/extensions/mod_consul.adoc index 8a988a5..96c0b98 100644 --- a/content/documentation-new/extensions/mod_consul.adoc +++ b/content/documentation-new/extensions/mod_consul.adoc @@ -15,14 +15,14 @@ Tamaya _Consul_ is an extension module. Refer to the link:../extensions.html[ext Tamaya _Consul_ provides different artifacts which allows use of link:http://www.consul.io[Consul from Hashicorp] as configuration backend. Basically the -module supports read-only integration (as a +ConsulPropertySource+ as well +module supports read-only integration (as a +ConsulonfigSource+ as well as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module. === 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, so it will not run on Java 8 and beyond. === Installation @@ -43,7 +43,7 @@ To use _tamaya-consul_ you only must add the corresponding dependency to your mo Consul integration comes basically with 2 artifacts: -* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default +* The +org.apache.tamaya.etcd.ConsulConfigSource+ is a +ConfigSource+ 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+. @@ -51,16 +51,16 @@ Consul integration comes basically with 2 artifacts: Access of consul key/value pairs is through the normal Tamaya API. -=== The ConsulPropertySource +=== The ConsulConfigSource -The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This +The +ConsulConfigSource+ 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 property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible consul servers +* The config 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 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 +* The +ConsulConfigSource+ 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`. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_etcd.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_etcd.adoc b/content/documentation-new/extensions/mod_etcd.adoc index 3003a09..dac6ab7 100644 --- a/content/documentation-new/extensions/mod_etcd.adoc +++ b/content/documentation-new/extensions/mod_etcd.adoc @@ -13,14 +13,14 @@ 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 -configuration backend. Basically the module adds a read-only property source (+EtcdPropertySource+). If +configuration backend. Basically the module adds a read-only property source (+EtcdConfigSource+). If the _tamaya-mutable-config_ extension is loaded it is alos possible to write configuration 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, so it will not run on Java 8 and beyond. === Installation @@ -46,7 +46,7 @@ Tamaya's _etcd_ integration provides basically the following artifacts: 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 +* The +org.apache.tamaya.etcd.EtcdConfigSource+ is a +ConfigSource+ 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+. @@ -175,9 +175,9 @@ public class EtcdAccessor { ----------------------------------------------- -=== The EtcdPropertySource +=== The EtcdConfigSource -The +EtcdPropertySource+ is automatically registered and allows to configure the _etcd_ servers to be used. This +The +EtcdConfigSource+ 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: @@ -187,6 +187,6 @@ in microservice containers to connect with the according etcd cluster: 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 +* The +EtcdConfigSource+ 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`. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_events.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_events.adoc b/content/documentation-new/extensions/mod_events.adoc index ccba9d1..9061d13 100644 --- a/content/documentation-new/extensions/mod_events.adoc +++ b/content/documentation-new/extensions/mod_events.adoc @@ -14,9 +14,9 @@ Tamaya _Events_ is an extension module. Refer to the link:../extensions.html[ext === What functionality this module provides ? Tamaya _Events_ provides a mechanism to publish and subscribe to +ConfigEvent<T>+ instances. -This module implements +ConfigChange+ or +PropertySourceChange+ as possible payloads, but +This module implements +ConfigChange+ or +ConfigSourceChange+ as possible payloads, but the module itself is not constraint to this payload types. -These payload types describe detected changes of key/values of a +Configuration+ or a +PropertySource+. +These payload types describe detected changes of key/values of a +Config+ or a +ConfigSource+. The extension also provides a _Singleton accessor_ which allows to register/unregister listeners for changes and the period, when configuration should be scanned for any changes. @@ -27,7 +27,7 @@ change events. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8, so it can be used with Java 8 and beyond. === Installation @@ -59,7 +59,7 @@ public interface ConfigEvent<T> { long getTimestamp(); } -// @FunctionalInterface +@FunctionalInterface public interface ConfigEventListener { void onConfigEvent(ConfigEvent<?> event); @@ -127,25 +127,25 @@ configuration change, which is anything of the following A collection of changes -* on a +Configuration+ is modelled by the +ConfigurationChange+ class -* on a +PropertySource+ is modelled by the +PropertySourceChange+ class +* on a +Config+ is modelled by the +ConfigChange+ class +* on a +ConfigSource+ is modelled by the +ConfigSourceChange+ class ==== Configuration Changes -A set of changes on a +Configuration+ is described by a +ConfigurationChange+ +A set of changes on a +Config+ is described by a +ConfigChange+ as follows: [source,java] ------------------------------------------------------- -public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{ +public final class ConfigChange implements ConfigEvent<Config>, Serializable{ - public static ConfigurationChange emptyChangeSet(Configuration configuration); + public static ConfigChange emptyChangeSet(Config configuration); @Override - public Configuration getResource(); + public Config getResource(); @Override - public Class<Configuration> getResourceType(); + public Class<Config> getResourceType(); @Override public String getVersion(); @Override @@ -168,45 +168,45 @@ public final class ConfigurationChange implements ConfigEvent<Configuration>, Se ------------------------------------------------------- -New instances of +ConfigurationChange+ hereby can be created using a -fluent +ConfigurationChangeBuilder+: +New instances of +ConfignChange+ hereby can be created using a +fluent +ConfigChangeBuilder+: [source,java] ------------------------------------------------------- -Configuration config = ...; -ConfigurationChange change = ConfigurationChangeBuilder.of(config) +Config config = ...; +ConfigChange change = ConfigChangeBuilder.of(config) .addChange("MyKey", "newValue") .removeKeys("myRemovedKey").build(); ------------------------------------------------------- -Also it is possible to directly compare 2 instances of +Configuration+, -which results in a +ConfigurationChange+ that +Also it is possible to directly compare 2 instances of +Config+, +which results in a +ConfigChange+ that reflects the differences between the two configurations passed: [source,java] Comparing 2 configurations ------------------------------------------------------- -Configuration config = ...; -Configuration changedConfig = ...; -ConfigurationChange change = ConfigurationChangeBuilder.of(config) +Config config = ...; +Config changedConfig = ...; +ConfigChange change = ConfigChangeBuilder.of(config) .addChanges(changedConfig).build(); ------------------------------------------------------- -So a +ConfigurationChange+ describes all the changes detected on a +Configuration+. +So a +ConfigChange+ describes all the changes detected on a +Config+. This allows you to publish instances of this class as events to all registered listeners (observer pattern). -For listening to +ConfigurationChange+ events you must implement the +For listening to +ConfigChange+ events you must implement the +ConfigEventListener+ functional interface: [source,java] .Implementing a ConfigChangeListener ------------------------------------------------------- -public final class MyConfigChangeListener implements ConfigEventListener<ConfigurationChange>{ +public final class MyConfigChangeListener implements ConfigEventListener<ConfigChange>{ - private Configuration config = ConfigurationProvider.getConfiguration(); + private Config config = ConfigProvider.getConfig(); public void onConfigEvent(ConfigEvent<?> event){ - if(event.getResourceType()==Configuration.class){ + if(event.getResourceType()==Config.class){ if(event.getConfiguration()==config){ // do something } @@ -229,51 +229,51 @@ NOTE: By default detection of configuration changes is not enabled. To enable it +ConfigEventManager.enableChangeMonitoring(true)+. -=== PropertySource Changes +=== ConfigSource Changes -Beside that a whole +Configuration+ changes, also a +PropertySource+ can change, +Beside that a whole +Config+ changes, also a +ConfigSource+ can change, e.g. by a configuration file edited on the fly. This is similarly to a -+ConfigurationChange+ reflected by the classes +PropertySourceChange, -PropertySourceChangeBuilder+. ++ConfigChange+ reflected by the classes +ConfigSourceChange, +ConfigSourceChangeBuilder+. ==== Monitoring of configuration changes The +ConfigEventManager+ supports *active monitoring of the current configuration* to trigger corresponding change events to listeners registered. *This feature is deactivated by default*, but can be enabled by calling -+ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling your local +Configuration+ for ++ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling your local +Config+ for any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding -+ConfigurationChange+ events automatically. ++ConfigChange+ events automatically. -=== Freezing Configurations and PropertySources +=== Freezing Configs and ConfigSources -+Configuration+ instances as well as +PropertySources+ are explicitly not required to be serializable. To enable easy -serialization of these types a +Configuration+'s *current state can be frozen* (e.g. for later comparison with a newly ++Config+ instances as well as +ConfigSources+ are explicitly not required to be serializable. To enable easy +serialization of these types a +Config+'s *current state can be frozen* (e.g. for later comparison with a newly loaded version). Freezing hereby means * all key/values are read-out by calling the +getProperties()+ method. * a meta data entry is added of the form +_frozenAt=223273777652325677+, whichdefines the UTC timestamp in milliseconds when this instance was frozen. -* if not already defined an +_id+ property will be added to the +Configuration+ containing the +* if not already defined an +_id+ property will be added to the +Config+ containing the identifier of the configuration. In code freezing is a no-brainer: [source,java] -.Freezing the current Configuration +.Freezing the current Config -------------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); -Configuration frozenConfig = FrozenConfiguration.of(config); +Config config = ConfigProvider.getConfig(); +Config frozenConfig = FrozenConfig.of(config); -------------------------------------------------- -... and similarly for a +PropertySource+: +... and similarly for a +ConfigSource+: [source,java] -.Freezing the current Configuration +.Freezing a ConfigSource -------------------------------------------------- -PropertySource propertySource = ...; -PropertySource frozenSource = FrozenPropertySource.of(propertySource); +ConfigSource configSource = ...; +ConfigSource frozenSource = FrozenConfigSource.of(configSource); -------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_features.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_features.adoc b/content/documentation-new/extensions/mod_features.adoc index c3299bd..454cf48 100644 --- a/content/documentation-new/extensions/mod_features.adoc +++ b/content/documentation-new/extensions/mod_features.adoc @@ -17,7 +17,7 @@ which Tamaya Extensions are currently on the classpath. === 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, so it will not run on Java 8 and beyond. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_filter.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_filter.adoc b/content/documentation-new/extensions/mod_filter.adoc index bce6947..8de64d8 100644 --- a/content/documentation-new/extensions/mod_filter.adoc +++ b/content/documentation-new/extensions/mod_filter.adoc @@ -14,7 +14,7 @@ Tamaya _Filter_ is an extension module. Refer to the link:../extensions.html[ext === What functionality this module provides ? -Tamaya _Filter_ provides a simple singleton accessor that allows to explicitly add +PropertyFilter+ instances +Tamaya _Filter_ provides a simple singleton accessor that allows to explicitly add +Filter+ instances active on the current thread only. This can be very useful in many scenarios, especially within Java EE web filters or similar. Additionally this module adds standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed @@ -22,7 +22,7 @@ explicitily no filtering is applied and everything is visible. === 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, so it will not run on Java 8 and beyond. === Installation @@ -43,19 +43,12 @@ To benefit from filter support you only must add the corresponding dependency to Tamaya Filter comes basically with 3 artifacts: -* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +PropertyFilter+ -instances on the current thread. -* The +org.apache.tamaya.filter.DefaultMetdataFilter+ is a +PropertyFilter+ with hides all entries starting with - an underscore ('_'), when a full property map is accessed. - - -==== The ConfigurationFilter - -The accessor mentioned implements the API for for adding +PropertyFilters+ to the current thread (as thread local): +* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +Filter+ +instances on the current thread: [source, java] ----------------------------------------------- -public final class ConfigurationFilter implements PropertyFilter{ +public final class ConfigurationFilter implements Filter{ ... @@ -105,20 +98,20 @@ finally { } ----------------------------------------------- -The +FilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local -managed filters: + +The +FilterChain+ is a simple compound structure combining multiple filters into one new (chained) filter: [source, java] ----------------------------------------------- -public final class FilterContext implements PropertyFilter { +public final class FilterChain implements Filter { - public void addIncludes(PropertyFilter filter); - public void addExcludes(int pos, PropertyFilter filter); - public PropertyFilter removeFilter(int pos); + public void addFilter(Filter filter); + public void addFilter(int pos, Filter filter); + public Filter removeFilter(int pos); public void clearFilters(); - public void setIncludes(PropertyFilter... filters); - public void setExcludes(Collection<PropertyFilter> filters); - public List<PropertyFilter> getFilters(); + public void setFilters(Filter... filters); + public void setFilters(Collection<Filter> filters); + public List<Filter> getFilters(); } ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_formats.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_formats.adoc b/content/documentation-new/extensions/mod_formats.adoc index aa7d559..fa7b1a5 100644 --- a/content/documentation-new/extensions/mod_formats.adoc +++ b/content/documentation-new/extensions/mod_formats.adoc @@ -18,7 +18,7 @@ Tamaya _Formats_ provides an abstraction for configuration formats provding the * Parsing of resources in can be implemented separately from interpreting the different aspects/parts parsed. As an example a file format can define different sections. Depending on the company specific semantics of the sections - a different set of +PropertySource+ instances must be created. + a different set of +ConfigSource+ instances must be created. * Similarly the configuration abstraction can also be used as an interface for integrating Tamaya with alternate frameworks that provide logic for reading configuration files, such as Apache commons.configuration. @@ -49,7 +49,7 @@ data structure (in our cases: property sources). So it is useful to separate con * a parser (+ConfigurationFormat+) that transfers a given format into an intermediate representation (+ConfigurationData+). * an optional customization, implemented by a _factory method pattern_ to adapt the mapping of +ConfigurationData+ read - to a collection of +PropertySources+ (they can have different ordinal semantics). + to a collection of +ConfigSources+ (they can have different ordinal semantics). ==== ConfigurationData @@ -111,10 +111,10 @@ public interface ConfigurationFormat { } ------------------------------------------------------- -=== Creating a default PropertySource for a ConfigurationFormat +=== Creating a default ConfigSource for a ConfigurationFormat The module defines a singleton +ConfigurationFormats+ which provides -an easy to use API for creating +ConfigurationData+ and +PropertySources+ +an easy to use API for creating +ConfigurationData+ and +ConfigSources+ using abstract +ConfigurationFormat+ implementations: [source,java] @@ -140,13 +140,13 @@ public final class ConfigurationFormats { Collection<ConfigurationFormat> formats) throws IOException; - public static PropertySource createPropertySource(URL url, ConfigurationFormat... formats) + public static ConfigSource createConfigSource(URL url, ConfigurationFormat... formats) throws IOException; - public static PropertySource createPropertySource(URL url, Collection<ConfigurationFormat> formats) + public static ConfigSource createConfigSource(URL url, Collection<ConfigurationFormat> formats) throws IOException; - public static PropertySource createPropertySource(String resource, InputStream inputStream, + public static ConfigSource createConfigSource(String resource, InputStream inputStream, ConfigurationFormat... formats); - public static PropertySource createPropertySource(String resource, InputStream inputStream, + public static ConfigSource createConfigSource(String resource, InputStream inputStream, Collection<ConfigurationFormat> formats); } ------------------------------------------------------- @@ -158,43 +158,43 @@ public final class ConfigurationFormats { * +readConfigurationData(...)+ reads data from an input and creates a corresponding +ConfigurationData+, either trying all known formats that declare its compatibility with the given input or the formats passed explicitly. -* +createPropertySource(...)+ allows to create a +PropertySource+ reading a given input and the formats +* +createConfigSource(...)+ allows to create a +ConfigSource+ reading a given input and the formats to be used or known. Hereby a default property mapping is applied. -So creating a +PropertySource+ from a resource is basically a one liner: +So creating a +ConfigSource+ from a resource is basically a one liner: [source,java] ------------------------------------------------------- URL url = ...; -PropertySource propertySource = ConfigurationFormats.createPropertySource(url); +ConfigSource configSource = ConfigurationFormats.createConfigSource(url); // constraining the formats to be used (assumption: json and yaml extensions are loaded) -PropertySource propertySource = ConfigurationFormats.createPropertySource( +ConfigSource configSource = ConfigurationFormats.createConfigSource( url, ConfigurationFormats.getFormats("json", "yaml")); ------------------------------------------------------- -=== Customize how ConfigurationData maps to PropertySource +=== Customize how ConfigurationData maps to ConfigSource -For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful: +For for the conversion of +ConfigurationData+ into a +ConfigSource+ different approaches can be useful: . The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties or/and as default properties. The most simple cases is, where all properties have been added as 'default' properties. In this case the default properties can be used as the property sources properties without any change. . If the format did also add section based properties, the combined properties returned can be used, hereby replacing the '::' separator with a '.' separator. -. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataPropertySource+ +. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataConfigSource+ and overriding the +Map<String,String> populateData(ConfigurationData data)+ method. -In most cases the usage of a +MappedConfigurationDataPropertySource+, is a good choice to start. This class +In most cases the usage of a +MappedConfigurationDataConfigSource+, is a good choice to start. This class provides a convenient default mapping and also allows to customized the mapping easily: [source,java] ------------------------------------------------------- ConfigurationData data = ...; -MappedConfigurationDataPropertySource ps = - new MappedConfigurationDataPropertySource(data){ +MappedConfigurationDataConfigSource ps = + new MappedConfigurationDataConfigSource(data){ protected Map<String, String> populateData(ConfigurationData data) { ... } @@ -206,23 +206,23 @@ resulting properties can have different semnatics, especially different prioriti names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the -appropriate collection of +PropertySource+ instances must be implemented. +appropriate collection of +ConfigSource+ instances must be implemented. -For this scenario the +BaseFormatPropertySourceProvider+ can be used, defining the following mapping +For this scenario the +BaseFormatConfigSourceProvider+ can be used, defining the following mapping function that mus be implemented: [source,java] ------------------------------------------------------- /** - * Method to create a {@link org.apache.tamaya.spi.PropertySource} based on the given entries read. + * Method to create a {@link org.apache.tamaya.spi.ConfigSource} based on the given entries read. * * @param data the configuration data, not null. - * @return the {@link org.apache.tamaya.spi.PropertySource} instance ready to be registered. + * @return the {@link org.apache.tamaya.spi.ConfigSource} instance ready to be registered. */ -protected abstract Collection<PropertySource> getPropertySources(ConfigurationData data); +protected abstract Collection<ConfigSource> getConfigSources(ConfigurationData data); ------------------------------------------------------- -When using Java 8 these mappings can be asily passed as parameters to the +createPropertySource+ +When using Java 8 these mappings can be asily passed as parameters to the +createConfigSource+ methods. @@ -235,7 +235,7 @@ The _formats_ module ships with 3 predefined formats: * `.xml` properties files, as defined by `java.util.Properties`, registered as `xml-properties`. -==== ini Configuration File Mapping +==== ini Config File Mapping This module implements the ini file format with the class +org.apache.tamaya.format.formats.IniConfigurationFormat+. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_functions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_functions.adoc b/content/documentation-new/extensions/mod_functions.adoc index 50a2b8b..bd52219 100644 --- a/content/documentation-new/extensions/mod_functions.adoc +++ b/content/documentation-new/extensions/mod_functions.adoc @@ -13,15 +13,17 @@ Tamaya _Functions_ is an extension module. Refer to the link:../extensions.html[ === What functionality this module provides ? -Tamaya _Functions_ provides several functional extensions using the +ConfigOperator,ConfigQuery+ extension points. Most -functional extension are accessible from the +ConfigurationFunction+ singleton. When importing its methods statically -one can use the methods to achieve some interesting effects, e.g. +Tamaya _Functions_ provides several functional extensions using the +UnaryOperator<Config>,Function<Config, T>+ extension +points. Most functional extension are accessible from the +ConfigurationFunctions+ singleton. Since the JSR API +does not provide any functional extension points it is recommended to adapt the +Config+ instance into .+FunctionalConfig+. +Then, when importing the functional methods statically they can very easily applied, e.g. [source,java] ------------------------------------------------------------------- import static org.apache.tamaya.functions.ConfigurationFunctions.*; -Set<String> sections = ConfigurationProvider.getConfiguration().with(areas("a", false).with(transitiveAreas()); +FunctionalConfig fc = FunctionalConfig.of(ConfigProvider.getConfig()); +Set<String> sections = fc.with(areas("a", false).with(transitiveAreas()); ------------------------------------------------------------------- The expression above returns all fully qualified section names that are child sections of the root section 'a'. @@ -29,7 +31,7 @@ So given the entries +a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4+ the reul === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8, so it can be used with Java 8 and beyond. === Installation @@ -45,50 +47,74 @@ For using the functionality shown in this document you only must add the corresp ----------------------------------------------- +=== FunctionalConfig + +The +FunctionalConfig+ actually adds the functional extension points +with+ and +query+ to .+Config+ instance, which +allow to chain expressions as seen in the introductionary snippet: + +[source, java] +----------------------------------------------- +public interface FunctionalConfig extends Config, ConfigContextSupplier { + + /** + * Enriches a {@link Config} instance with functional access points. + * @param config the config, not null + * @return a functional config instance. + */ + static FunctionalConfig of(Config config){ + ... + } + + default FunctionalConfig with(UnaryOperator<Config> operator); + default <T> T query(Function<Config, T> query); +} +----------------------------------------------- + + === The Provided Functions ==== Functions on +ConfigurationFunctions+ The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton. -* *ConfigOperator filter(PropertyMatcher matcher)* creates a +ConfigOperator+ that creates a +Configuration+ +* *UnaryOperator<Config> filter(PropertyMatcher matcher)* creates a +UnaryOperator<Config>+ that creates a +Configuration+ containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only the _key_, but also the _value_. -* *ConfigOperator map(KeyMapper keyMapper)* creates a +ConfigOperator+ that maps the keys as defined +* *UnaryOperator<Config> map(KeyMapper keyMapper)* creates a +UnaryOperator<Config>+ that maps the keys as defined by the given _keyMapper_. -* *ConfigOperator section(String section)* creates a +ConfigOperator+ that creates a +Configuration+ containing only +* *UnaryOperator<Config> section(String section)* creates a +UnaryOperator<Config>+ that creates a +Configuration+ containing only entries that are direct or indirect members of the given section. -* *ConfigOperator section(String areaKey, boolean stripKeys)* creates a +ConfigOperator+ that creates a +Configuration+ +* *UnaryOperator<Config> section(String areaKey, boolean stripKeys)* creates a +UnaryOperator<Config>+ that creates a +Configuration+ containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys. * *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member of a given section. * *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given _key_ is a direct or indirect member of at least one of the given _sectionKeys_. -* *ConfigQuery<Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that +* *Function<Config,Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that also have parameters present). -* *ConfigQuery<Set<String>> transitiveSections()* allows to query all the contained fully qualified section names, +* *Function<Config,Set<String>> transitiveSections()* allows to query all the contained fully qualified section names, including the transitive closure of sections. -* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully +* *Function<Config,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully qualified section names that are selected by the given _predicate_. -* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully +* *Function<Config,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully qualified section names that are selected by the given _predicate_, including the transitive closure of sections identified. -* *ConfigOperator sectionsRecursive(String... sectionKeys)* provides a +ConfigOperator+ that filters all sections identified +* *UnaryOperator<Config> sectionsRecursive(String... sectionKeys)* provides a +UnaryOperator<Config>+ that filters all sections identified by the given _sectionKeys_ and its child sections. -* *ConfigOperator sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +ConfigOperator+ +* *UnaryOperator<Config> sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +UnaryOperator<Config>+ that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or absolute (filtering only). -* *ConfigQuery<String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+ +* *Function<Config,String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+ representation. -==== Functions on +PropertySourceFunctions+ +==== Functions on +ConfigSourceFunctions+ -The following sections explain the provided functions defined by +PropertySourceFunctions+ singleton. +The following sections explain the provided functions defined by +ConfigSourceFunctions+ singleton. -* *PropertySource addMetaData(PropertySource propertySource, Map<String,String> metaData)* Creates a new +PropertySource+ +* *ConfigSource addMetaData(ConfigSource propertySource, Map<String,String> metaData)* Creates a new +ConfigSource+ with the given metadata added. * *boolean isKeyInSection(String key, String sectionKey)* Checks if the given _key_ is a direct or indirect member of one of the given _sectionKey_. @@ -101,9 +127,9 @@ The following sections explain the provided functions defined by +PropertySource from the given properties, also filtering with the given predicate. * *Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate)* Extracts the transitive sections from the given properties, also filtering with the given predicate. -* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +PropertySource+ +* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +ConfigSource+ only containing the sections that a direct or indirect children of the given _sectionKeys_. -* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +PropertySource+ +* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +ConfigSource+ only containing the sections that a direct or indirect children of the given _sectionKeys_. With _stripKeys_ one can select of the returned values should be relative to its selection of be fully qualified. * *String stripSectionKeys(String key, String... sectionKeys)* This function strips away the matching section key as given http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_hazelcast.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_hazelcast.adoc b/content/documentation-new/extensions/mod_hazelcast.adoc index 13487a9..e17aad6 100644 --- a/content/documentation-new/extensions/mod_hazelcast.adoc +++ b/content/documentation-new/extensions/mod_hazelcast.adoc @@ -16,14 +16,14 @@ Tamaya _Hazelcast_ is an extension module. Refer to the link:../extensions.html[ Tamaya _Hazelcast_ provides a property source which uses link:http://www.hazelcast.org[Hazelcast] as configuration backend. Hereby the -module supports read-only integration (as a +HazelcastPropertySource+ as well +module supports read-only integration (as a +HazelcastConfigSource+ as well as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module. === 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, so it will not run on Java 8 and beyond. === Installation @@ -44,18 +44,18 @@ To use _tamaya-hazelcast_ you only must add the corresponding dependency to your Hazelcast integration comes basically with 2 artifacts: -* The +org.apache.tamaya.hazelcast.HazelcastPropertySource+ is a +PropertySource+. The property source is not automatically +* The +org.apache.tamaya.hazelcast.HazelcastConfigSource+ is a +ConfigSource+. The property source is not automatically registered. Either register it using the _ServiceLoader_ yourself or implement - and register a corresponding `PropertySourceProvider`. + and register a corresponding `ConfigSourceProvider`. * 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:hazelcast+. Access of consul key/value pairs is through the normal Tamaya API. -=== The HazelcastPropertySource +=== The HazelcastConfigSource -The +HazelcastPropertySource+ is not automatically registered and provides different options how to integrate +The +HazelcastConfigSource+ is not automatically registered and provides different options how to integrate Tamaya with Hazelcast. [source, java] @@ -64,21 +64,21 @@ Tamaya with Hazelcast. * 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(); +public HazelcastConfigSource(); /** * 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); +public HazelcastConfigSource(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); +public HazelcastConfigSource(String name); /** * Creates a new instance, hereby using the given property source name and @@ -86,7 +86,7 @@ public HazelcastPropertySource(String name); * @param config the hazelcast config, not null. * @param name the property source name, not null. */ -public HazelcastPropertySource(String name, Config config); +public HazelcastConfigSource(String name, Config config); /** * Creates a new instance, hereby using the given property source name and the @@ -94,7 +94,7 @@ public HazelcastPropertySource(String name, Config config); * @param name * @param hazelcastInstance */ -public HazelcastPropertySource(String name, HazelcastInstance hazelcastInstance); +public HazelcastConfigSource(String name, HazelcastInstance hazelcastInstance); ----------------------------------------------- To use hazelcast as a configuration backend, you simply create the corresponding Hazelcast instance @@ -103,17 +103,16 @@ can be easily created asillustrated below: [source, java] ----------------------------------------------- -Config hazelcastConfig = new Config(); // define config settings HazelcastInstance hazelcastInstance = Hazelcast.newInstance(hazelcastConfig); -HazelcastPropertySource ps = new HazelcastPropertySource(hazelcastInstance); -ps.setName("myHazelcast-config"); -ps.setOrdinal(2000); -// Build your own configuration context -ConfigurationContextBuilder b = ConfigurationProvider.createNewConfigurationContextBuilder(); -b.addDefaultPropertyConverters().addDefaultPropertyFilter().addDefaultPropertySources(); +HazelcastConfigSource cs = new HazelcastConfigSource(hazelcastInstance); +cs.setName("myHazelcast-config"); +cs.setOrdinal(2000); +// Build your own configuration +ConfigBuilder b = ConfigProviderResolver.getInstance().getBuilder(); +b.addDiscoveredConverters().addDefaultSources().addDiscoveredSources(); // Add the hazelcast property source (as most significant) -b.addPropertySource(ps); +b.awithSource(cs); // build and use the configuration -Configuration config = b.build(); +Config config = b.build(); ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_injection.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_injection.adoc b/content/documentation-new/extensions/mod_injection.adoc index facb92c..67186e0 100644 --- a/content/documentation-new/extensions/mod_injection.adoc +++ b/content/documentation-new/extensions/mod_injection.adoc @@ -16,18 +16,19 @@ Tamaya _Injection_ is an extension module. Refer to the link:../extensions.html[ Tamaya _Injection_ provides functionality for injecting configured values into beans, or creating configuration template instances. -Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate +Inversion of Control (aka IoC/Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the according injection services. This module adds this functionality to Tamaya. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8, so it can be used with Java 8 and beyond. === Installation -Basically Tamaya's injection API is deployed as API artifact: +The basic injection API is defined by the configuration JSRÃs API. Nevertheless Tamaya's adds some +useful extensions. These extensions are deployed as optional API artifact: [source, xml] ----------------------------------------------- @@ -57,7 +58,7 @@ Similarly there are other injection implementations available, targetig platform === Core Concepts -Basically you annotate fields or methods in your beans with +@Config+ to enable configuration injection. Tamaya +Basically you annotate fields or methods in your beans with +@ConfigProperty+ to enable configuration injection. Tamaya additionally defines further annotations that allo you to define additional aspects such as default values, custom converters etc. The following example illustrates the basic functionality: code snippet: @@ -73,16 +74,17 @@ public class ConfiguredClass { 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}.") + @ConfigProperty(key="a.b.c.key1", defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") + @ConfigFaööbackKeys({"a.b.legacyKey",area1.key2"}) String value1; // Typical case - @Config("a.b.c.key2") + @ConfigProperty(key="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";) + @ConfigProperty(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json";) private URL accessUrl; // Config injection disabled for this property @@ -90,8 +92,8 @@ public class ConfiguredClass { private Integer int1; // Overriding the String -> BigDecimal converter with a custom implementation. - @Config("BD") - @WithPropertyConverter(MyBigDecimalRoundingAdapter.class) + @ConfigProperty(key="BD") + @WithConverter(MyBigDecimalRoundingAdapter.class) private BigDecimal bigNumber; ... @@ -100,19 +102,19 @@ public class ConfiguredClass { When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating -this feature a class must be annotated with +@ConfigAutoInject+: +this feature a class must be annotated with +@ConfigAutoDetect+: [source, java] . An autoinjected bean class -------------------------------------------- package a.b; -@ConfigAutoInject +@ConfigAutoDetect public final class Tenant { private int id; private String name; private String description; - @NoConfig // prevents auto injection for this field + @NoConfig // prevents auto detection for this field private String id2; public int getId(){ @@ -129,7 +131,7 @@ public final class Tenant { 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): +Tamaya inject the configuration: [source,java] .Configuring the +ConfiguredClass+ Instance @@ -150,7 +152,8 @@ documentation. 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. +hereby must not be annotated with +@ConfigProperty+ for being configurable. + ==== Accessing Supplier instances @@ -176,7 +179,7 @@ Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance(). -------------------------------------------- Hereby this annotation can be used in multiple ways and combined with other annotations such as -+@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+. ++@WithLoadPolicy+, +@WithConverter+. ==== Minimal Example @@ -195,18 +198,19 @@ pubic class ConfiguredItem{ 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+) +* The current valid +Config+ is evaluated by calling +Config cfg = ConfigProvider.getConfig();+ +* The current property value (String) is evaluated by calling +cfg.getValue("aValue", Type.class);+ + for each possible key (mutliple keys are possible). +* if not successful, an error is thrown * On success, since no type conversion is involved, the value is injected. === The Annotations in detail -==== Using `@Config` +==== Using `@ConfigProperty` + +This is the main JSR annotation targeting a field in a class for configuration injection. -This is the main annotation targeting a field in a class for configuration injection. ===== Evaluating of _configuration keys_ @@ -233,7 +237,7 @@ declaring type: -------------------------------------------- @ConfigDefaultSections("a.b.c", "deprecated") pubic class MyClass{ - @Config + @ConfigProperty private String myField; } -------------------------------------------- @@ -254,7 +258,8 @@ it is also possible to define absolute key entries, e.g. -------------------------------------------- @ConfigDefaultSections("a.b.c") pubic class MyClass{ - @Config("myField" /* relative */, "[absolute.key]") + @ConfigProperty("myField" /* relative */) + @ConfigFallbackKeys("[absolute.key]") private String myField; } -------------------------------------------- @@ -275,7 +280,8 @@ In the next example we explicitly define the _default_ property value: -------------------------------------------- pubic class ConfiguredItem{ - @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}") + @ConfigProperty(key="aValue", defaultValue="${env:java.version}") + @ConfigFallbackKeys({"a.b.value","a.b.deprecated.value"}) private String aValue; } -------------------------------------------- @@ -283,12 +289,12 @@ pubic class ConfiguredItem{ ==== Automatically inject all items using `@ConfigAutoInject` -Using `@ConfigAutoInject` allows you to automatically select all properties found for +Using `@ConfigAutoDetect` allows you to automatically select all properties found for configuration injection: [source,java] -------------------------------------------- -@ConfigAutoInject +@ConfigAutoDetect pubic class ConfiguredItem{ private transient int sum; @@ -299,8 +305,8 @@ pubic class ConfiguredItem{ } -------------------------------------------- -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 +Adding the `@NoConfig` annotation prevents a field or method to be auto-detected from +configuration. This is especially useful, if a type is annotated as @ConfigAutoDetect with auto-confiuration turned on as follows: [source,java] @@ -313,28 +319,9 @@ In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignor 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] --------------------------------------------- +==== Adding custom property converters using `@WithConverter` -@WithConfigOperator(MyConfigView.class) -pubic class ConfiguredItem{ - - @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 +The @WithConverter annotation allows you to define a class of type +Converter+, 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. @@ -343,8 +330,8 @@ various use cases, e.g. adding custom formats, config models, decryption. pubic class ConfiguredItem{ - @WithPropertyConverter(MyPropertyConverter.class) - @Config + @WithConverter(MyPropertyConverter.class) + @ConfigProperty private String a; } @@ -360,7 +347,7 @@ commit new values exactly, when convenient for you. -------------------------------------------- pubic class ConfiguredItem{ - @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}") + @ConfigProperty(key="aValue", defaultValue="${env:java.version}") private DynamicValue aValue; } -------------------------------------------- @@ -423,7 +410,7 @@ Dynamic values also allow on-the-fly reevaluation of the value by calling +evalu instance is not changed. -===== The Loading policy enum +===== The LoadPolicy enum The +LoadPolicy+ enum defines different configuration loading behaviour to be applied: @@ -467,16 +454,15 @@ The event published is very simple: [source,java] -------------------------------------------- public interface ConfiguredType { - Class getArea(); + Class getType(); String getName(); Collection<ConfiguredField> getConfiguredFields(); Collection<ConfiguredMethod> getConfiguredMethods(); void configure(Object instance, Configuration config); } - public interface ConfiguredField { - Class<?> getArea(); + Class<?> getType(); Collection<String> getConfiguredKeys(); String getName(); String getSignature(); http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_jndi.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_jndi.adoc b/content/documentation-new/extensions/mod_jndi.adoc index c3f12f8..a167e9e 100644 --- a/content/documentation-new/extensions/mod_jndi.adoc +++ b/content/documentation-new/extensions/mod_jndi.adoc @@ -12,13 +12,13 @@ Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[exten === What functionality this module provides ? -Tamaya _JNDI_ provides a simple +PropertySource+ that reads values from a +Tamaya _JNDI_ provides a simple +ConfigySource+ that reads values from a JNDI context. === 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, so it will not run on Java 8 and beyond. === Installation @@ -38,7 +38,7 @@ your module: === The Functionality Provided -Main artifact is the +JNDIPropertySource+ class, which implements a +Main artifact is the +JNDIConfigSource+ class, which implements a property source based on a JNDI context: [source, java] @@ -60,9 +60,9 @@ will return an empty map instance. After calling `setScannable(true);` a call to `getProperties()` will return a String representation of the JNDI tree. Hereby leaves of the tree are converted using `String.valueOf(leaveObject)`. -This module automatically registers an instance of +JNDIPropertySource+ with a +This module automatically registers an instance of +JNDIConfigSource+ with a default ordinal of +200+. You can extend this class or manually instantiate it, e.g. as part of a -+PropertySourceProvider+. If no `Context` is passed explicitly, a new ++ConfigSourceProvider+. If no `Context` is passed explicitly, a new +InitialContext+ is created, without any environment parameters set. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_jodatime.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_jodatime.adoc b/content/documentation-new/extensions/mod_jodatime.adoc index a49fa7b..67a88a1 100644 --- a/content/documentation-new/extensions/mod_jodatime.adoc +++ b/content/documentation-new/extensions/mod_jodatime.adoc @@ -38,7 +38,7 @@ Joda-Time based values directly from a given configuration. [source,java] ----------------------------------------------- -Configuration configuration = ConfigurationProvider.getConfiguration(); +Config configuration = ConfigProvider.getConfig(); DateTime pit = configuration.get("pointInTime", DateTime.class) ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_json.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_json.adoc b/content/documentation-new/extensions/mod_json.adoc index d22ad2f..a6e0572 100644 --- a/content/documentation-new/extensions/mod_json.adoc +++ b/content/documentation-new/extensions/mod_json.adoc @@ -39,7 +39,7 @@ This extension uses SPI defined by the +tamaya.formats+ extension module. === Compatibility -The module is based on Java 7, so it will run on Java 7 and beyond. +The module is based on Java 8, so it will run on Java 8 and beyond. === Installation @@ -75,6 +75,6 @@ registers the _json_ format automatically using the `ServiceContext`): [source, java] ----------------------------------------------- -PropertySource ps = ConfigurationFormats.createPropertySource( +ConfigSource ps = ConfigurationFormats.createConfigSource( getClassLoader().getResource("myFileConfig.json")); ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_management.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_management.adoc b/content/documentation-new/extensions/mod_management.adoc index ca38d18..df45aeb 100644 --- a/content/documentation-new/extensions/mod_management.adoc +++ b/content/documentation-new/extensions/mod_management.adoc @@ -17,7 +17,7 @@ accessing configuration. === Compatibility -The module is based on Java 7, so it will run on Java 7 and beyond. +The module is based on Java 8, so it will run on Java 8 and beyond. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_metamodel.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_metamodel.adoc b/content/documentation-new/extensions/mod_metamodel.adoc index bddf076..ed03b25 100644 --- a/content/documentation-new/extensions/mod_metamodel.adoc +++ b/content/documentation-new/extensions/mod_metamodel.adoc @@ -39,7 +39,7 @@ By default it uses an XML based configuration format as illustrated below: <!-- Configuration definition. --> - <property-sources> + <sources> <source enabled="${stage=TEST || stage=PTA || stage=PROD}" type="env-properties"> <filter type="PropertyMapping"> @@ -60,18 +60,18 @@ By default it uses an XML based configuration format as illustrated below: <param name="location">config.json</param> </source> ... - </property-sources> + </sources> </configuration> ----------------------------------------------- -The module basically provides an XML representation to the +ConfigurationContextBuilder+ API. -It creates a corresponding +ConfigurationContext+ and registers the corresponding +Configuration+ -as the system's _default_ configuration (accessible from `ConfigurationProvider.getConfiguration()`. +The module basically provides an XML representation to the +ConfigBuilder+ API. +It creates and registers the corresponding +Config+ +as the system's _default_ configuration (accessible from `ConfigProvider.getConfig(ClassLoader cl)`. === 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, so it will not run on Java 8 and beyond. === Installation @@ -90,29 +90,29 @@ To use _metamodel_ features you only must add the corresponding dependency to yo === Creating a Configuration using Meta-Configuration -The basic feature of this module is the capability of creating a +Configuration+ completely -based on a meta-configuration file. For this the +MetaConfiguration+ main singleton +The basic feature of this module is the capability of creating a +Config+ completely +based on a meta-configuration file. For this the +MetaConfig+ main singleton provides different methods: [source, java) ----------------------------------------------- -public final class MetaConfiguration { +public final class MetaConfig { public static void configure(); public static void configure(URL metaConfig); - public static ConfigurationContextBuilder createContextBuilder(URL metaConfig); - public static Configuration createConfiguration(URL metaConfig); + public static ConfigBuilder createBuilder(URL metaConfig); + public static Config createConfiguration(URL metaConfig); ----------------------------------------------- * If you have supplied your meta-configuration at `META-INF/tamaya-config.xml` you simply - call +MetaConfiguration.configure();+. This will read the meta-configuration and + call +MetaConfig.configure();+. This will read the meta-configuration and configure Tamaya's _default_ configuration. Alternatively you can choose your own metaconfiguration location by passing an alternate `URL` ro read from. * With +MetaConfiguration.createContextBuilder()+ you can stop a step earlier: a new - instance of +ConfigurationContextBuilder+ is created and configured with all the + instance of +ConfigBuilder+ is created and configured with all the entries found in your meta-configuration. Also here you can optionally pass your custom location for the meta-configuration resouce. -* Finally +MetaConfiguration.createConfiguration(URL)+ allows you to create an - arbitrary +Configuration+ instance using a meta-configuration file. The `Configuration` +* Finally +MetaConfig.createConfig(URL)+ allows you to create an + arbitrary +Config+ instance using a meta-configuration file. The `Config` instance is completely independent and not registered as _default_ configuration, so it's lifecycle and usage is completely under your control. @@ -378,12 +378,12 @@ XML metaconfiguration, e.g. [source, xml] ----------------------------------------------- -<property-sources> +<sources> <source type="file" refreshable="true"> <name>config.json</name> <param name="location">config.json</param> </source> -</property-sources> +</sources> ----------------------------------------------- @@ -411,7 +411,7 @@ as well (see next chapter). <!-- PART THREE: Configuration definition. --> - <property-sources> + <sources> <source enabled="${stage=TEST || stage=PTA || stage=PROD}" type="env-properties"> <filter type="PropertyMapping"> @@ -454,8 +454,8 @@ as well (see next chapter). <param name="ttl">30 SECOND</param> </filter> </source> - </property-sources> - <property-filters> + </sources> + <filters> <filter type="UsageTrackerFilter"/> <filter type="AccessControl"> <param name="roles">admin,power-user</param> @@ -466,11 +466,11 @@ as well (see next chapter). <param name="ttl">30000</param> <param name="expression">cached.*</param> </filter> - </property-filters> - <property-converters> + </filters> + <converters> <!--<converter type="AllInOneConverter"/>--> <default-converters/> - </property-converters> + </converters> </configuration> ----------------------------------------------- @@ -505,23 +505,23 @@ type +org.apache.tamaya.metamodel.spi.MetaConfigurationReader+: [source,java] ----------------------------------------------------------- -public interface MetaConfigurationReader { +public interface MetaConfigReader { /** * Reads meta-configuration from the given document and configures the current * context builder. The priority of readers is determined by the priorization policy * implemented by the {@link org.apache.tamaya.spi.ServiceContext}, * @param document the meta-configuration document - * @param contextBuilder the context builder to use. + * @param configBuilder the config builder to use. */ - void read(Document document, ConfigurationContextBuilder contextBuilder); + void read(Document document, ConfigBuilder configBuilder); } ----------------------------------------------------------- -Hereby we also see that an instance of `ConfigurationContextBuilder` is passed. +Hereby we also see that an instance of `ConfigBuilder` is passed. Remember, we mentioned earlier that meta-configuration basically is a XML -API to the building a configuration using a +ConfigurationContextBuilder+. So +API to the building a configuration using a +ConfigBuilder+. So all you can do with the meta-config XML can also be done programmatically using the Java API. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/5675df62/content/documentation-new/extensions/mod_microprofile.adoc ---------------------------------------------------------------------- diff --git a/content/documentation-new/extensions/mod_microprofile.adoc b/content/documentation-new/extensions/mod_microprofile.adoc deleted file mode 100644 index 9d5951d..0000000 --- a/content/documentation-new/extensions/mod_microprofile.adoc +++ /dev/null @@ -1,93 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya - Extension: Microprofile Implementation - -toc::[] - - -[[Spring]] -== Tamaya Microprofile Implementation (Extension Module) - -Tamaya _Microprofile_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. - - -=== What functionality this module provides ? - -Tamaya _Microprofile_ currently provides full integration for the Microprofile Configuration API: - -* A Microprofile +ConfigSource+ implementation can be used with Tamaya. -* A Tamaya +PropertySource+ can be used with any Microprofile implementation. -* The same is also true for +Converter,PropertyConverter+. -* Nevertheless Tamaya also fully implements the Microprofile API and also successfully is compatible with the - Microprofile TCK. - - -=== Compatibility - -Both modules are based on Java 8, so they will run on Java 8 and beyond. The implemented Microprofile API is currently -version 1.1. - - -=== Installation - -To benefit from Tamaya Microprofile you only must one of the following dependencies to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-microprofile</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== Using Microprofile API - -Refer to http://microprofile.io/project/eclipse/microprofile-config for details on how the API works and should be used. In general, you will see -many similarities with Tamaya, since Tamaya heavily influenced the design of microprofile.io regarding configuration. -Nevertheless Tamaya's API is much more complete and provides far more feature as of now. Further changes in this area -may be good to be expected, since as of now also a corresponding specification (JSR) has been started and will -be supported by Tamaya as well. - -[source, java] --------------------------------------------------------- -// SE API - -Config config = ConfigProvider.getConfig(); -String serverUrl = config.getValue("acme.myprj.some.url", String.class); -callToServer(serverUrl); - -// ===================================================================== - -// CDI Injection API - -@ApplicationScoped -public class InjectedConfigUsageSample { - - @Inject - private Config config; - - //The property myprj.some.url must exist in one of the configsources, otherwise a - //DeploymentException will be thrown. - @Inject - @ConfigProperty(name="myprj.some.url") - private String someUrl; - //The following code injects an Optional value of myprj.some.port property. - //Contrary to natively injecting the configured value this will not lead to a - //DeploymentException if the configured value is missing. - @Inject - @ConfigProperty(name="myprj.some.port") - private Optional<Integer> somePort; - //Injects a Provider for the value of myprj.some.dynamic.timeout property to - //resolve the property dynamically. Each invocation to Provider#get() will - //resolve the latest value from underlying Config. - //The existence of configured values will get checked during startup. - //Instances of Provider<T> are guaranteed to be Serializable. - @Inject - @ConfigProperty(name="myprj.some.dynamic.timeout", defaultValue="100") - private javax.inject.Provider<Long> timeout; -} --------------------------------------------------------- -
