Moved asciidocs latest from core to site, keeping jbake headers in place.
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/06e3e4c0 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/06e3e4c0 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/06e3e4c0 Branch: refs/heads/master Commit: 06e3e4c088177bc14d476ab2414300de94342b23 Parents: 40e8f73 Author: Anatole Tresch <anat...@apache.org> Authored: Fri Nov 18 07:07:11 2016 +0100 Committer: Anatole Tresch <anat...@apache.org> Committed: Fri Nov 18 07:07:11 2016 +0100 ---------------------------------------------------------------------- content/api.adoc | 125 ++++++++++++++++++++++++++++++++++++------- content/core.adoc | 6 ++- content/extensions.adoc | 74 +++++++++---------------- 3 files changed, 136 insertions(+), 69 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/06e3e4c0/content/api.adoc ---------------------------------------------------------------------- diff --git a/content/api.adoc b/content/api.adoc index f830585..98256ce 100644 --- a/content/api.adoc +++ b/content/api.adoc @@ -23,7 +23,7 @@ == Apache Tamaya: API Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required -that build the base of all the other mechanisms. As a starting point we recommend you read the corresponding +that are the base of all the other mechanisms. As a starting point we recommend you read the corresponding llink:HighLevelDesign.html[High Level Design Documentation] [[API]] @@ -51,10 +51,14 @@ The API provides the artifacts as described in the link:HighLevelDesign.html[Hig ** +ConfigurationProviderSpi+ defines the SPI that is used as a backing bean for the +ConfigurationProvider+ singleton. ** +PropertyFilter+, which allows filtering of property values prior getting returned to the caller. - ** +ConfigurationContext+, which provides the container that contains the property sources and filters that form a - configuration. ** +PropertyValueCombinationPolicy+ optionally can be registered to change the way how different key/value pairs are combined to build up the final +Configuration+ passed over to the filters registered. + ** +ConfigurationContext+, which provides a container for all the artifacts needed to build up a +Configuration+. + For example a context contains the property sources, property filters, converters and combination policy used. + Also the ordering of the property sources is defined by the context. A context instance given a + +Configuration+ can be created by calling +ConfigurationProvider.createConfiguration(context);+. + ** Similarly a +ConfigurationContext+ can be created using a +ConfigurationContextBuilder+. This builder can be + obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+. ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack. ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded. @@ -202,7 +206,7 @@ Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+. [[PropertyConverter]] -==== Property Converters +==== Property Type Conversion As illustrated in the previous section, +Configuration+ also to access non String types. Nevertheless internally all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the @@ -328,7 +332,7 @@ property sources with additional combination/aggregation rules in place. [[PropertySourceProvider]] -==== Interface PropertySourceProvider +=== Interface PropertySourceProvider Instances of this type can be used to register multiple instances of +PropertySource+. @@ -349,7 +353,7 @@ current active +ServiceContext+. [[PropertyFilter]] -==== Interface PropertyFilter +=== Interface PropertyFilter Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated before a +Configuration+ instance is passed to the user. Filters can hereby used for multiple purposes, such as @@ -420,7 +424,7 @@ public interface PropertyValueCombinationPolicy{ [[ConfigurationContext]] ==== The Configuration Context -A +Configuration+ is basically based on a so called +ConfigurationContext+, which is +A +Configuration+ is created from a +ConfigurationContext+, which is accessible from +Configuration.getContext()+: [source,java] @@ -429,7 +433,8 @@ accessible from +Configuration.getContext()+: ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext(); -------------------------------------------- -The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+: +The +ConfigurationContext+ provides access to the internal artifacts that determine the final +Configuration+ and +also defines the ordering of the property sources, filters and converters contained: * +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances). * +PropertyFilters+ registered, which filter values before they are returned to the client @@ -441,8 +446,8 @@ The +ConfigurationContext+ provides access to the internal building blocks that [[Mutability]] ==== Changing the current Configuration Context -By default the +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed -or even not wanted. Nevertheless there are use cases where the current +ConfigurationContext+ (and +A +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed. Nevertheless +there are use cases where the current +ConfigurationContext+ (and consequently +Configuration+) must be adapted: * New configuration files where detected in a folder observed by Tamaya. @@ -452,7 +457,7 @@ consequently +Configuration+) must be adapted: * Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the tests executed. -In such cases the +ConfigurationContext+ must be mutable, meaning it must be possible: +In such cases the +ConfigurationContext+ must be changed, meaning it must be possible: * to add or remove +PropertySource+ instances * to add or remove +PropertyFilter+ instances @@ -462,9 +467,9 @@ In such cases the +ConfigurationContext+ must be mutable, meaning it must be pos This can be achieved by obtaining an instance of +ConfigurationContextBuilder+. Instances of this builder can be accessed either -* from the current +ConfigurationContext+, hereby returning a builder instance preinitialized with the values from the - current +ConfigurationContext+ -* from the current +ConfigurationProvider+ singleton. +* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the + current +ConfigurationContext+. +* calling +ConfigurationProvider.getConfigurationContextBuilder()+. [source,java] .Accessing a +ConfigurationContextBuilder+ @@ -478,10 +483,41 @@ With such a builder a new +ConfigurationContext+ can be created and then applied [source,java] .Creating and applying a new +ConfigurationContext+ -------------------------------------------- -ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext() - .toBuilder(); -ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource()) - .addPropertyFilter(new MyFilter()).build(); +ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext() + .toBuilder(); + .addPropertySources(new MyPropertySource()) + .addPropertyFilter(new MyFilter()) + .build(); +-------------------------------------------- + +Hereby the builder provides several methods for adding, removing of property sources and also operations +for programmatically change the property sourcepriorities, e.g. + +[source,java] +.Chain manipulation using +ConfigurationContextBuilder+ +-------------------------------------------- +PropertySource propertySource = builder.getPropertySource("sourceId"); + +// changing the priority of a property source. The ordinal value hereby is not considered. +// Instead the position of the property source within the chain is changed. +builder.decreasePriority(propertySource); + +// Alternately a comparator expression can be passed to establish the defined ordering... +builder.sortPropertyFilters(MyFilterComparator::compare); +-------------------------------------------- + +Finally if the new context is ready a new configuration can be created, or the context is applied to the +current configuration. + +[source,java] +.Creating and applying a new +ConfigurationContext+ +-------------------------------------------- +ConfigurationContext context = builder.build(); + +// Creates a new matching Configuration instance +Configuration newConfig = ConfigurationProvider.createConfiguration(context); + +// Apply the new context to replace the current configuration: ConfigurationProvider.setConfigurationContext(context); -------------------------------------------- @@ -500,6 +536,59 @@ One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interf * to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context. * Performing changes as set with the current +ConfigurationContextBuilder+. += Interface ConfigurationContextBuilder + +include::temp-properties-files-for-site/attributes.adoc[] + +[[BuilderCore]] +== Interface ConfigurationContextBuilder +=== Overview + +The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances, +e.g. as follows: + +[source,java] +--------------------------------------------------------------- +ConfigurationBuilder builder = new ConfigurationBuilder(); +// do something +Configuration config = builder.build(); +--------------------------------------------------------------- + +Basically the builder allows to create configuration instances completely independent of the current configuration +setup. This gives you full control on the +Configuration+ setup. + + +=== Supported Functionality + +The builder allows you to add +PropertySource+ instances: + +[source,java] +---------------------------------------------------------------- +ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder(); +builder.addPropertySources(sourceOne, sourceTwo, sourceThree +Configuration config = ConfigurationProvider.createConfiguration(builder.build()); +---------------------------------------------------------------- + +Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided +by the property sources. This allows alternate ordering policies easily being implemented because +creating a configuration based on a configuration context is already implemented and provided by the core +API. + +Similarly you can add filters: + +[source,java] +---------------------------------------------------------------- +builder.addPropertyFilters(new MyConfigFilter()); +---------------------------------------------------------------- + +...or +PropertySourceProvider+ instances: + +[source,java] +---------------------------------------------------------------- +builder.addPropertySourceProvider(new MyPropertySourceProvider()); +---------------------------------------------------------------- + + [[ServiceContext]] ==== The ServiceContext http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/06e3e4c0/content/core.adoc ---------------------------------------------------------------------- diff --git a/content/core.adoc b/content/core.adoc index fe891b2..ea3a7c6 100644 --- a/content/core.adoc +++ b/content/core.adoc @@ -36,7 +36,8 @@ hereby providing type conversion for all important types. * A simple default configuration setup using the current classpath and an optional staging variable. * It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and registers them in the global +ConfigurationContext+ -* It provides a +ConfigurationContextBuilder+ and allows changing the current +ConfigurationContext+. +* It provides a +ConfigurationContextBuilder+ implementation (class +DefaultConfigurationContextBuilder+) and allows + changing the current +ConfigurationContext+. The overall size of the library is very small. All required components are implemented and registered, so basically the Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible @@ -116,6 +117,9 @@ By default, and if no annotation is added +0+ is used as priority. Hereby higher * if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is still defined and predictable in almost all scenarios. +NOTE: Sorting the property sources based on their ordinal value is only the default ordering principle applied. By implementing + your own implementation of +ConfigurationProviderSpi+ you can apply a different logic: + [[RegisteringPropertySources]] === Registering Property Sources http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/06e3e4c0/content/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/extensions.adoc b/content/extensions.adoc index 93b34b5..577fd67 100644 --- a/content/extensions.adoc +++ b/content/extensions.adoc @@ -36,72 +36,46 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati |+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.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-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] -|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation] -|======= - - -=== Extensions - -Extensions in _draft state_ are tested well and normally should have rather stable APIs. Nevertheless API changes may -still occurr, but we try to prevent such changes if possible. - -NOTE All extensions currently run on Java 7 as well as on Java 8. - -[width="100%",frame="1",options="header",grid="all"] -|======= -|_Artifact_ |_Description_ |_Links_ -|+org.apache.tamaya.ext:tamaya-builder+ |Provides a fluent-style builder for configurations | link:extensions/mod_builder.html[Documentation] -|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.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-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation] -|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] -|+org.apache.tamaya.ext:tamaya-model+ |Provides support documenting ang validating configuration during runtime. |link:extensions/mod_model.html[Documentation] +|+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-injection-cdi-se+ | Java EE/standalone compliant CDI integration using Tamaya SE injection mechanism. | link:extensions/mod_cdi.html[Documentation] |+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation] -|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation] +|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.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-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation] |+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] |+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation] -|======= - -=== Integrations - -These extensions integrate/bridge Tamayas functionality with other frameworks turning their configuration capabilities -from a sledgehammer to a scalpell: - -[width="100%",frame="1",options="header",grid="all"] -|======= -|_Artifact_ |_Description_ |_Links_ -|+org.apache.tamaya.ext:tamaya-cdi+ | Java EE/standalone compliant CDI integration | link:extensions/mod_cdi.html[Documentation] -|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation] |+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation] -|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.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] |======= -=== Extensions in Experimental Stage +=== Extensions Sandbox -Extensions in _experimental mode_ may still be under discussions. API changes may still happen, so use them -very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state. +Extensions in _draft state_ rather experimental or not yet very mature. API changes may occurr at any time +and the may also have severe issues. So use at your own risk or join and help us getting them stable and +well tested! + +NOTE All extensions currently run on Java 7 as well as on Java 8. [width="100%",frame="1",options="header",grid="all"] |======= |_Artifact_ |_Description_ |_Links_ +|+org.apache.tamaya.ext:tamaya-commons+ |Combines Tamaya's Format Abstraction with Apache Commons. | - |+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation] -|+org.apache.tamaya.ext:tamaya-staged+ |Simple configuration extension to add staged config. | link:extensions/mod_metamodel-staged.html[Documentation] +|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.html[Documentation] +|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] +|+org.apache.tamaya.ext:tamaya-metamodel+ |Provides support defining configuration using XML based meta-configuration. |link:extensions/mod_metamodel.html[Documentation] +|+org.apache.tamaya.ext:tamaya-validation+ |Provides support for XML based meta-configuration allowing to validate configuration read. |link:extensions/mod_validation.html[Documentation] +|+org.apache.tamaya.ext:tamaya-usagetracker+ |Provides support tracking of configuration usage and the consumer locations consuming configuration. |link:extensions/mod_usagetracker.html[Documentation] +|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation] +|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.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-configured-sysprops+ | Allows Tamaya to integrate with +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] +|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation] +|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation] +|+org.apache.tamaya.ext:tamaya-ui+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation] |======= - -=== Integrations in Experimental Stage - -Integrations in _experimental mode_ may still be under discussions, or may even not compile ! API changes may still happen, so use them -very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state. - -[width="100%",frame="1",options="header",grid="all"] -|======= -|_Artifact_ |_Description_ |_Links_ -|+org.apache.tamaya.ext:tamaya-commons+ |Integration with Apache Commons Configuration. | - -|=======
