You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2016/11/18 06:07:20 UTC
[2/2] incubator-tamaya-site git commit: Moved asciidocs latest from
core to site, keeping jbake headers in place.
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 <an...@apache.org>
Authored: Fri Nov 18 07:07:11 2016 +0100
Committer: Anatole Tresch <an...@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. | -
-|=======