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/06 15:42:13 UTC
incubator-tamaya git commit: TAMAYA-182: Adapted API documentation to
include builder support.$ Adapted configuration for new module structure.
Repository: incubator-tamaya
Updated Branches:
refs/heads/master eafcadea6 -> 924613847
TAMAYA-182: Adapted API documentation to include builder support.$
Adapted configuration for new module structure.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/92461384
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/92461384
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/92461384
Branch: refs/heads/master
Commit: 924613847f098b66c285ff0592470bcef764df82
Parents: eafcade
Author: anatole <an...@apache.org>
Authored: Sun Nov 6 16:38:16 2016 +0100
Committer: anatole <an...@apache.org>
Committed: Sun Nov 6 16:38:16 2016 +0100
----------------------------------------------------------------------
src/site/asciidoc/API.adoc | 125 ++++-
src/site/asciidoc/Core.adoc | 6 +-
src/site/asciidoc/extensions.adoc | 74 +--
src/site/asciidoc/extensions/mod_builder.adoc | 100 ----
.../extensions/mod_metamodel-staged.adoc | 76 ---
src/site/asciidoc/extensions/mod_model.adoc | 465 -------------------
.../asciidoc/extensions/mod_usagetracker.adoc | 169 +++++++
.../asciidoc/extensions/mod_validation.adoc | 111 +++++
8 files changed, 416 insertions(+), 710 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/API.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/API.adoc b/src/site/asciidoc/API.adoc
index f8d01c1..6aac2da 100644
--- a/src/site/asciidoc/API.adoc
+++ b/src/site/asciidoc/API.adoc
@@ -22,7 +22,7 @@ include::temp-properties-files-for-site/attributes.adoc[]
== 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]]
@@ -50,10 +50,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.
@@ -201,7 +205,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
@@ -327,7 +331,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+.
@@ -348,7 +352,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
@@ -419,7 +423,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]
@@ -428,7 +432,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
@@ -440,8 +445,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.
@@ -451,7 +456,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
@@ -461,9 +466,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+
@@ -477,10 +482,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);
--------------------------------------------
@@ -499,6 +535,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/blob/92461384/src/site/asciidoc/Core.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/Core.adoc b/src/site/asciidoc/Core.adoc
index e31c319..927004b 100644
--- a/src/site/asciidoc/Core.adoc
+++ b/src/site/asciidoc/Core.adoc
@@ -35,7 +35,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
@@ -115,6 +116,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/blob/92461384/src/site/asciidoc/extensions.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions.adoc b/src/site/asciidoc/extensions.adoc
index 939241b..14b3e58 100644
--- a/src/site/asciidoc/extensions.adoc
+++ b/src/site/asciidoc/extensions.adoc
@@ -34,72 +34,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. | -
-|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_builder.adoc b/src/site/asciidoc/extensions/mod_builder.adoc
deleted file mode 100644
index 8555dc9..0000000
--- a/src/site/asciidoc/extensions/mod_builder.adoc
+++ /dev/null
@@ -1,100 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Builder
-
-include::temp-properties-files-for-site/attributes.adoc[]
-
-
-[[BuilderCore]]
-== Tamaya Builder (Extension Module)
-=== 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.
-
-=== Compatibility
-
-The module is based on Java 7, so it will run on Java 7 and does
-not require Java 8. The +ConfigurationProvider+
-as defined by the API, provides a builder instance for +ConfigurationContext+
-in a similar way. A +Configuration+ can also be created by passing an instance of a +ConfigurationContext+:
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding
-dependency to your module:
-
-[source,xml,subs="verbatim,attributes"]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-builder</artifactId>
- <version>{tamaya_version_development}</version>
-</dependency>
------------------------------------------------
-
-=== Supported Functionality
-
-The builder allows you to add +PropertySource+ instances:
-
-[source,java]
-----------------------------------------------------------------
-ConfigurationBuilder builder = new ConfigurationBuilder();
-builder.addPropertySources(sourceOne).addPropertySources(sourceTwo);
-Configuration config = builder.build();
-----------------------------------------------------------------
-
-Similarly you can add filters:
-
-[source,java]
-----------------------------------------------------------------
-builder.addPropertyFilters(new MyConfigFilter());
-----------------------------------------------------------------
-
-...or +PropertySourceProvider+ instances:
-
-[source,java]
-----------------------------------------------------------------
-builder.addPropertySourceProvider(new MyPropertySourceProvider());
-----------------------------------------------------------------
-
-Also the builder module allows to include/exclude any filters and property source already known to the current
-+ConfigurationContext+:
-
-[source,java]
-----------------------------------------------------------------
-builder.disableProvidedPropertyConverters();
-builder.enableProvidedPropertyConverters();
-
-builder.disableProvidedPropertyFilters();
-builder.enableProvidedPropertyFilters();
-
-builder.disableProvidedPropertySources();
-builder.enableProvidedPropertySources();
-----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_metamodel-staged.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_metamodel-staged.adoc b/src/site/asciidoc/extensions/mod_metamodel-staged.adoc
deleted file mode 100644
index 9fb89c3..0000000
--- a/src/site/asciidoc/extensions/mod_metamodel-staged.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Staged PropertySources
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Metamodel: Staged PropertySources (Extension Module)
-=== Overview
-
-The Tamaya Staged PropertySources extension provides a base class and default implementation for loading
-multistaged configuration easily from a common configuration location.
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext.metamodels</groupId>
- <artifactId>tamaya-metamodel.staged</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-The component will not register any components. The component basically provides the following options:
-
-* Use it as default configuration extension. Hereby you should define your stages in use by setting the
- +env.STAGE+ system property with the stages to be loaded in order of precedence (most significant last),
- e.g. +sys-env,DEFAULTS,TEST,DEVELOPMENT. _Additionally_ you must register
- +org.apache.tamaya.staged.StagedConfigPropertiesProvider+ as in
-
---------------------------------------------------------------
-META-INF
-|_service
- |_org.apache.tamaya.spi.PropertySourceProvider
---------------------------------------------------------------
-
-Tamaya will then load .properties files from +System.getenv(),
-classpath:DEFAULTS.properties, classpath:TEST.properties+ and
-+classpath:DEVELOPMENT.properties+
-
-* For more advanced requirements, such as alternate locations, patterns or formats, you can also extend one of the
- provided classes (+org.apache.tamaya.staged.StagedConfigPropertiesProvider+,
- ** +BaseStagedPropertySourceProvider+). Extending provides features such as:
-
- ** Defining a prefix for all entries provided/loaded.
- ** Using alternate locations or formats.
- ** Defining the ordinals used.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_model.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_model.adoc b/src/site/asciidoc/extensions/mod_model.adoc
deleted file mode 100644
index 0bc9f74..0000000
--- a/src/site/asciidoc/extensions/mod_model.adoc
+++ /dev/null
@@ -1,465 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Model Documentation and Validation
-
-toc::[]
-
-
-[[ExtModel]]
-== Tamaya Model Documentation and Validation (Extension Module)
-=== Overview
-
-The Tamaya model module provides support for documenting configuration and validating configuration read and processed
-against this model. Documentation and config models can be provided in different ways:
-
-* as separate meta-model documents
-* by providers that check classes/packages for configuration annotations (planned)
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-model</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-
-=== Describing the Configuration Meta-Model
-
-Basically configuration is modelled using key, value-pairs. Looking at a keys
-+a.b.c.param1+ and +a.b.c.param2+ the following concepts can be used to defined/describe
-configuration:
-
-. the _configuration section:_ In our case this equals to +a.b.c+, which itself also includes the
- transitive entries +a.b+ and +a+.
-. the _configuration parameter:_ Basically parameters are adressed using their fully qualified names,
- which equals to the containing section name and the relative parameter name, separated by the dor separator.
- In the above example +a.b.c.param1+ and +a.b.c.param2+ are the fully qualified parameter names.
-
-Now with only these 2 concepts a simple configuration meta-model can be defined as
-
-* a meta-model's name, used just for grouping different meta-models and entries to better separate
- descriptions, e.g. in a management console or generated configuration documentation site.
-* a set of sections.
-* a set of parameters.
-* Both, sections (+.model.target=Section+) as well as parameter models (+.model.target=Parameter+)
- ** can be modelled by a meta-data entry, by default +_my.config.key.model+.
- ** may be required, or optional (+.model.required=true|false+)
- ** may have an optional description
-* Parameters additionally have
- ** a _type_ (+.model.type=Classname+), described by the fully qualified class name, into which any configured (String)
- value must be convertable into. If no type is configured +java.ui.lang.String+ is assumed as default.
- ** an optional regular expression that can be used to validate the +String+ values returned from a
- configuration (+.model.expression=regexpression+).
-
-Given these concepts a configuration can be fully described. Entries that are not contained in one of the given
-sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of
-a section), are called _undefined_. Undefined parameters should be grouped with its parent section. Each section, as
-well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and
-only if
-
-. the section itself is (directly) _undefined_
-. the section is not a _super section_ of a defined section.
-
-As en example the section definition of +a.b.c+ also implicitly includes the sections +a.b+ and +a+ to be defined
-sections, despite the fact that section properties, such as description and custom configModels are not inherited to
-its parent, or child section.
-
-
-=== Defining Meta-Configuration Model
-
-The configuration meta-model is defined by simple configuration meta-data entries. The section for all model
-configuration by default is called +model+, which results in entries such as +_my.config.key.model.target=Section+.
-Within this section fully qualified configuration keys defines
-which part of the configuration is targeted by certain entries.
-
-==== Defining Sections
-
-First we start to define some configuration sections, the example below starts with the most important
-variants supported:
-
-[source,listing]
--------------------------------------------------------------------------------
-# Metamodel information
-_model.provider=ConfigModel Extension
-
-# org.mycompany.root (optional section)
-_org.mycompany.root.model.target=Section
-_org.mycompany.root.model.description=Root section defining my company configuration.
-
-# org.mycompany.security (required section)
-_org.mycompany.security.model.target=Section
-_org.mycompany.security.model.required=true
-_org.mycompany.security.model.description=Security related settings.\
- refer for further details to XXX.
-
-# minmal section
-_minimal.model.target=Section
-
-# custom validated section
-_validated.model.target=Section
-_validated.model.validator=org.apache.tamaya.model.TestValidator
--------------------------------------------------------------------------------
-
-Above +org.mycompany.root+ transitively defines 3 sections:
-
-* org
-* org.mycompany
-* org.mycompany.root
-
-All sections are optional. Additionally the model above also defines a required section +org.mycompany.security+.
-Required sections are checked so the section is not empty. It is not checked for any specific parameter hereby,
-only the existance of any child parameter is validated.
-
-The _class_ attribute has to be defined for any section definition, because if not set a model entry is, by default,
-defined to be a parameter configModel entry. Given above the entry for the section +minimal+ shows such a minimal
-entry.
-
-+validated+ defines a section, which is validated through a customizable validator. Hereby an ordered list of validators
-can be provided, separated by commas.
-
-
-==== Defining Parameters
-
-Similarly parameters also can be defined:
-
-[source,listing]
--------------------------------------------------------------------------------
-# org.mycompany.root.name (required parameter)
-_org.mycompany.root.name.model.target=Parameter
-_org.mycompany.root.name.model.required=true
-_org.mycompany.root.name.model.description=The company's name, also used in the application's main header.
-
-# org.mycompany.security (required parameters)
-_org.mycompany.security.uid.model.required=true
-_org.mycompany.security.uid.model.description=The user id.
-_org.mycompany.security.realm.model.required=true
-_org.mycompany.security.realm.model.validator=org.apache.tamaya.model.RealmValidator
-_org.mycompany.security.realm.model.description=The security realm required.
-_org.mycompany.security.tokenid.model.description=The token id, if the token service is used (optional).
-
-# A minmal parameter
-_minimalClass.model.target=Class
--------------------------------------------------------------------------------
-
-Similarly as when defining section also parameter entries define transitively its containing sections. E.g.
-the entry above for +org.mycompany.security.realm+ also defines the following sections (as optional).
-
-* org
-* org.mycompany
-* org.mycompany.security
-
-Additional entries for section, e.g. configModels to be done, can be added as described in the previous section,
-but are optional.
-
-Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it's
-parameter type to be defined. In the example above we define a parameter +minimalClass+ of type +Class+.
-Types hereby are fully qualified class names, whereas as 'java.ui.lang' for built-in language types can be
-ommitted.
-
-==== Model Locations
-
-By default the configuration model can be defined at the following locations:
-
-* +classpath*:META-INF/configmodel.properties+, separate to the current +Configuration+. This functionality is enabled
- by default, but can be disabled by adding +org.apache.tamaya.model.default.enabled=false+ to your current
- +Configuration+.
-* +implicitly as part of the current +Configuration+. THis can be disabled by setting
- the +org.apache.tamaya.model.integrated.enabled+ configuration poarameter to +false+.
-* customized by configuring the +org.apache.tamaya.model.resources+ in the current +Configuration+. This
- parameter allows to define the locations from where the model extension is trying to read the
- model configuration. If the _resources extension_ is available in your system it is used to
- evaluate the locations. If not the default +Classloader.getResources+ command is issued. Also it
- is required that the _formats extension_ is available, since this is used to effectively read the
- data. This extension also allows you to use alternate representation formats such as +ini, xml, yml, json+.
-
-
-=== Tracking Configuration Access
-
-The model module also allows tracking which code accesses configuration properties or configuration parameters.
-It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly
-ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length.
-The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+
-instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage
-statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+.
-
-Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+.
-+ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status.
-
-The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing:
-
-* the access point (+fqn.ClassName#method(line: xxx)+).
-* the number of accesses
-* the first an last access
-* the values read
-* the access stacktrace (filtered by ignored packages).
-
-[source,java]
------------------------------------------------------------
-public final class Usage {
- [...]
- public String getKey();
- public void clearMetrics();
- public int getReferenceCount();
- public int getUsageCount();
- public Collection<AccessDetail> getAccessDetails(Class type);
- public Collection<AccessDetail> getAccessDetails(Package pack);
- public Collection<AccessDetail> getAccessDetails(String lookupExpression);
- public Collection<AccessDetail> getAccessDetails();
- public void trackUsage(String value);
- public void trackUsage(String value, int maxTraceLength);
-
-
- public static final class AccessDetail {
- [...]
- public void clearStats();
- public long trackAccess(String value);
- public long getAccessCount();
- public String getAccessPoint();
- public long getFirstAccessTS();
- public long getLastAccessTS();
- public String[] getStackTrace();
- public Map<Long, String> getTrackedValues();
- }
-
-}
------------------------------------------------------------
-
-With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main
-singleton for configuration statistics is defined as follows:
-
-[source,java]
------------------------------------------------------------
-public final class ConfigUsageStats{
- public static Set<String> getIgnoredUsagePackages();
- public static void addIgnoredUsagePackages(String... packageName);
- public static void enableUsageTracking(boolean enabled);
- public static Usage getUsage(String key);
- public static Collection<Usage> getUsages();
- public static void clearUsageStats();
- public static Usage getUsageAllProperties();
- public static boolean isUsageTrackingEnabled();
- public static String getUsageInfo();
-}
------------------------------------------------------------
-
-==== Customizing the Stacktrage for Usage Reporting
-
-The stacktrace tracked by the system can be customized in several ways:
-
-* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names.
-* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a
- negative value will disable stacktrace logging completelely.
-
-
-=== Accessing Usage Statistics
-
-Bascially usage statistics are available in two forms:
-
-* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+
- singleton.
-* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics
- can be obtained, as illustrated below (a snipped from the current test output):
-
-[source,listing]
------------------------------------------------------------
-Apache Tamaya Configuration Usage Metrics
-=========================================
-DATE: Sat Apr 30 21:51:09 CEST 2016
-
-220 <<all>>:
- - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-3 java.version:
- - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
- - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-
------------------------------------------------------------
-
-
-==== Programmatic API
-
-Basically the configModel module provides a simple API to access the defined +ConfigModel+ instances and
-validating the current +Configuration+ against the models as follows:
-
-[source,java]
------------------------------------------------------------
-public final class ConfigModelManager {
-
- private ConfigModelManager() {}
-
- public static Collection<ConfigModel> getModels();
- public static Collection<ConfigModel> findModels(ModelType type, String namePattern);
- public static <T extends ConfigModel> T getModel(String name, Class<T> modelType);
- public static Collection<ConfigModel> findModels(String namePattern);
-
- public static Collection<ValidationResult> validate();
- public static Collection<ValidationResult> validate(boolean showUndefined);
- public static Collection<ValidationResult> validate(Configuration config);
- public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined);
-
- public static void registerMBean();
- public static void registerMBean(String context);
-
-}
------------------------------------------------------------
-
-This singleton allows to validate the current or any +Configuration+ instance. All the ConfigModels read also are
-available from the +getModels+ method. This models can be used to provide documentation, e.g. as part of a CLI interface
-or shown on a documentation web server.
-
-A +ConfigModel+ hereby is defined as one single part of configuration, typically corresponding to a specific concern
-of your system. As an example you can define different models for different modules or products plugged together.
-With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a
-single configuration source (e.g. for configuring the machine's IP address and subnet settings only once.
-
-[source,java]
------------------------------------------------------------
-public interface ConfigModel {
-
- ModelTarget getType();
- String getName();
- String getProvider();
- boolean isRequired();
- String getDescription();
- Collection<ValidationResult> validate(Configuration config);
-}
------------------------------------------------------------
-
-
-Hereby +ModelTarget+ defines more details on the kind of model:
-
-[source,java]
------------------------------------------------------------
-public enum ModelTarget {
- /**
- * A configuration section.
- */
- Section,
- /**
- * A configuration paramter.
- */
- Parameter,
- /**
- * ConfigModel that is a container of other validations.
- */
- Group
-}
------------------------------------------------------------
-
-A +ValidationResult+ models one validation executed by a +ConfigModel+ on a certain +Configuration+ instance:
-
-[source,java]
------------------------------------------------------------
-public final class ValidationResult {
-
- public static ValidationResult ofValid(ConfigModel configModel);
- public static ValidationResult ofMissing(ConfigModel configModel);
- public static ValidationResult ofMissing(ConfigModel configModel, String message);
- public static ValidationResult ofError(ConfigModel configModel, String error);
- public static ValidationResult ofWarning(ConfigModel configModel, String warning);
- public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage);
- public static ValidationResult ofDeprecated(ConfigModel configModel);
- public static ValidationResult ofUndefined(final String key);
- public static ValidationResult of(ConfigModel configModel, ValidationState result, String message);
-
- public ConfigModel getConfigModel();
- public ValidationState getResult();
- public String getMessage(),
-}
------------------------------------------------------------
-
-The result of a complete validation on a concrete +Configuration+ instance finally is mapped as a
-+Collection<ValidationResult>+, refer to the methods on +ConfigModelManager+.
-
-
-=== Auto-Documentation of Classes with Configuration Injection
-
-A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
-(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
-models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
-time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
-behaviour. Nevertheless this means that after your system has been started you should have access to a complete
-set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
-(through injection).
-
-
-== Model SPI
-=== Registering Configuration Models
-
-The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is
-the +ModelProviderSpi+ interface, which allows any kind of additional config models to be added to the system:
-
-[source,java]
------------------------------------------------------------
-public interface ModelProviderSpi {
-
- Collection<ConfigModel> getConfigModels();
-
-}
------------------------------------------------------------
-
-New instances implementing this interface must be registered into the current +ServiceContext+, by default the
-+ServiceLoader+ is used.
-
-
-=== The ConfigUsageStatsSpi
-
-The methods for managing and tracking of configuration changes are similarly delegated to an
-implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI.
-By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking
-logic can be adapted or replaced.
-
-=== Other Utility Classes
-
-The module also provides further utility classes that may be useful for implementing models or testing:
-
-* +AbstractModel+ provides a base class that can be extended, when implementing +ConfigModel+.
-* +AreaConfigModel+ provides a +ConfigModel+ implementation (with a corresponding +Builder+) to model the
- requirement of certain configuration sections being present, or opionally present, in the model.
-* +ParameterModel+ provides an implementation base class for validating parameters on existence and compliance
- with a regular expression.
-* +ConfigDocumentationMBean+ is the MBean registered that models similar functionality as +ConfigModelManager+.
-* +ConfigModelGroup+ provides a +ConfigModel+ that groups several child models.
-* +ConfigModelReader+ allows to read +ConfigModels+ from properties files as described at the beginning of this
- document.
-
-
-=== Switches to enable/disable functionality
-
-The model module provides different switches that can be used to activate or deactivate features:
-
-* +tamaya.model.integrated.enabled+ allows to deactivate reading inline metaconfiguration delivered with
- the normal Tamaya Configuration. By default inline entries (+_.abcd.model.*+) are evaluated.
-* +tamaya.model.default.enabled+ allows to deactivate reading metamodel information from
- +classpath:META-INF/configmodel.properties+. By default it is active.
-* +tamaya.model.resources+ allows to define additional resources (loaded through the resources extension),
- that can be used to read metamodel information in any format using Tamaya's format module.
-* the system property +tamaya.model.autoModelEvents+ allows to activate/deactivate the automatic
- documentation of classes configured and published by Tamaya +ConfiguredType+ event instances (e.g. published by
- Tamaya's injection modules).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_usagetracker.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_usagetracker.adoc b/src/site/asciidoc/extensions/mod_usagetracker.adoc
new file mode 100644
index 0000000..41d4871
--- /dev/null
+++ b/src/site/asciidoc/extensions/mod_usagetracker.adoc
@@ -0,0 +1,169 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Usage Tracking
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Usage Tracking (Extension Module)
+=== Overview
+
+Tamaya Usage Tracking allows to record and count the configuration access and consumer locations in your local
+VM.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+To benefit from configuration mutability support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-usagetracker</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Tracking Configuration Access
+
+The model module also allows tracking which code accesses configuration properties or configuration parameters.
+It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly
+ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length.
+The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+
+instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage
+statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+.
+
+Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+.
++ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status.
+
+The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing:
+
+* the access point (+fqn.ClassName#method(line: xxx)+).
+* the number of accesses
+* the first an last access
+* the values read
+* the access stacktrace (filtered by ignored packages).
+
+[source,java]
+-----------------------------------------------------------
+public final class Usage {
+ [...]
+ public String getKey();
+ public void clearMetrics();
+ public int getReferenceCount();
+ public int getUsageCount();
+ public Collection<AccessDetail> getAccessDetails(Class type);
+ public Collection<AccessDetail> getAccessDetails(Package pack);
+ public Collection<AccessDetail> getAccessDetails(String lookupExpression);
+ public Collection<AccessDetail> getAccessDetails();
+ public void trackUsage(String value);
+ public void trackUsage(String value, int maxTraceLength);
+
+
+ public static final class AccessDetail {
+ [...]
+ public void clearStats();
+ public long trackAccess(String value);
+ public long getAccessCount();
+ public String getAccessPoint();
+ public long getFirstAccessTS();
+ public long getLastAccessTS();
+ public String[] getStackTrace();
+ public Map<Long, String> getTrackedValues();
+ }
+
+}
+-----------------------------------------------------------
+
+With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main
+singleton for configuration statistics is defined as follows:
+
+[source,java]
+-----------------------------------------------------------
+public final class ConfigUsageStats{
+ public static Set<String> getIgnoredUsagePackages();
+ public static void addIgnoredUsagePackages(String... packageName);
+ public static void enableUsageTracking(boolean enabled);
+ public static Usage getUsage(String key);
+ public static Collection<Usage> getUsages();
+ public static void clearUsageStats();
+ public static Usage getUsageAllProperties();
+ public static boolean isUsageTrackingEnabled();
+ public static String getUsageInfo();
+}
+-----------------------------------------------------------
+
+==== Customizing the Stacktrage for Usage Reporting
+
+The stacktrace tracked by the system can be customized in several ways:
+
+* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names.
+* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a
+ negative value will disable stacktrace logging completelely.
+
+
+=== Accessing Usage Statistics
+
+Bascially usage statistics are available in two forms:
+
+* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+
+ singleton.
+* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics
+ can be obtained, as illustrated below (a snipped from the current test output):
+
+[source,listing]
+-----------------------------------------------------------
+Apache Tamaya Configuration Usage Metrics
+=========================================
+DATE: Sat Apr 30 21:51:09 CEST 2016
+
+220 <<all>>:
+ - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+3 java.version:
+ - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+ - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+
+-----------------------------------------------------------
+
+
+=== Auto-Documentation of Classes with Configuration Injection
+
+A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
+(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
+models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
+time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
+behaviour. Nevertheless this means that after your system has been started you should have access to a complete
+set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
+(through injection).
+
+
+== UsageTracker Module SPI
+
+=== The ConfigUsageStatsSpi
+
+The methods for managing and tracking of configuration changes are similarly delegated to an
+implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI.
+By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking
+logic can be adapted or replaced.
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_validation.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_validation.adoc b/src/site/asciidoc/extensions/mod_validation.adoc
new file mode 100644
index 0000000..777a1d7
--- /dev/null
+++ b/src/site/asciidoc/extensions/mod_validation.adoc
@@ -0,0 +1,111 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Configuration Validation
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Validation: Validating Configuration (Extension Module)
+=== Overview
+
+The Tamaya Validation extension adds support to validate a configuration against a set of rules
+defined in a Tamaya Metaconfiguration XML file.
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya Metamodel feature you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-validation</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+The component will extend Tamaya's +tamaya-metamodel+ module and adds an additional meta provider ruleset
+so validation rules can also be added to the default meta configuration XML file as separate sections.
+
+
+=== Usage
+
+This module expects meta-configuration to be located at the following locations. Hereby multiple files
+are supported:
+
+[source, text]
+-----------------------------------------------
+-Dtamaya-validation=<an URL> // any resolvable URL
+./tamaya-validation-*.xml // file
+META-INF/tamaya-validation-*.xml // classpath (multiple entries-possible)
+-----------------------------------------------
+
+=== The Validation XML Format
+
+The configuration validation is defined by simple configuration meta-data entries.
+
+[source, xml]
+-----------------------------------------------
+<configuration-validation>
+ ...
+ <provider>The Validation Provider</provider> <!-- optional -->
+ <section name="org.mycompany">
+ <section name="security" required="true">
+ <description>The description of ma area.</description>
+ </section>
+ </section>
+ <section name="minimal"/>
+ <section name="validated.sections" at-least="1">
+ <section name="customValidated" validator="myFQValidatorClassName"/>
+ <section name="withParams" >
+ <param name="int" type="int"/>
+ <param name="aText" expression="[a|b|c]" required="true"/>
+ <param name="aValidatedText" validator="myValidatorClass">
+ <description>This kind of params are more complex...</description>
+ </param>
+ </section>
+ </section>
+ <validator class="a,b,c,MyGlobalValidator"/>
+</configuration-validation>
+-----------------------------------------------
+
+==== The Example Explained
+
+* The *provider* entry is used for generating validation message, when a validation fails.
+* Section itself can be recursively defined, where each level can have it's own validations.
+* Sections added, but without validation rules are _defined_ section. Configuration outside of
+ defined sections can be flagged out using WARNING messages.
+* Sections can be _reuired_ and additionally also _validated_.
+* There is also the possibility to register global validators, which are called by the validation
+ logic once a configuration has been completely loaded.
+
+Similar to sections also parameters can be validated:
+
+* they can be marked as _required_
+* they can have a certain type, meaning they must be convertible to the given type
+* they can have an additional custom validator.
+* they can have an optional description for error analysis and error output.
+
+Similar to section parameters that are not defined, but encountered may be flagged out with
+a WARNING message.