tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject incubator-tamaya-site git commit: Improved docs.
Date Mon, 13 Feb 2017 23:06:41 GMT
Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master 76ae9629c -> 276266806


Improved docs.


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/27626680
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/27626680
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/27626680

Branch: refs/heads/master
Commit: 276266806b75d1cde85f31b36e054baafc09ca52
Parents: 76ae962
Author: anatole <anatole@apache.org>
Authored: Tue Feb 14 00:06:31 2017 +0100
Committer: anatole <anatole@apache.org>
Committed: Tue Feb 14 00:06:31 2017 +0100

----------------------------------------------------------------------
 .../documentation/extensions/mod_formats.adoc   | 142 +++--
 content/documentation/extensions/mod_json.adoc  |  54 +-
 .../extensions/mod_management.adoc              |   7 +-
 .../extensions/mod_metamodel-staged.adoc        |  61 --
 .../documentation/extensions/mod_metamodel.adoc | 632 +++++++++++++++++++
 content/documentation/extensions/mod_model.adoc | 454 -------------
 6 files changed, 775 insertions(+), 575 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/27626680/content/documentation/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_formats.adoc b/content/documentation/extensions/mod_formats.adoc
index 073b4aa..5c4f746 100644
--- a/content/documentation/extensions/mod_formats.adoc
+++ b/content/documentation/extensions/mod_formats.adoc
@@ -111,6 +111,69 @@ public interface ConfigurationFormat {
 }
 -------------------------------------------------------
 
+=== Creating a default PropertySource for a ConfigurationFormat
+
+The module defines a singleton +ConfigurationFormats+ which provides
+an easy to use API for creating +ConfigurationData+ and +PropertySources+
+using abstract +ConfigurationFormat+ implementations:
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigurationFormats {
+
+    public static List<ConfigurationFormat> getFormats();
+    public static List<ConfigurationFormat> getFormats(String... formatNames);
+    public static List<ConfigurationFormat> getFormats(final URL url);
+
+    public static ConfigurationData readConfigurationData(final URL url)
+    throws IOException;
+    public static ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats)
+    throws IOException;
+    public static ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats)
+    throws IOException;
+    public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats);
+    public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats);
+    public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
+                                                          ConfigurationFormat... formats)
+    throws IOException;
+    public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
+                                                          Collection<ConfigurationFormat> formats)
+    throws IOException;
+
+    public static PropertySource createPropertySource(URL url, ConfigurationFormat... formats)
+    throws IOException;
+    public static PropertySource createPropertySource(URL url, Collection<ConfigurationFormat> formats)
+    throws IOException;
+    public static PropertySource createPropertySource(String resource, InputStream inputStream,
+                                                      ConfigurationFormat... formats);
+    public static PropertySource createPropertySource(String resource, InputStream inputStream,
+                                                       Collection<ConfigurationFormat> formats);
+}
+-------------------------------------------------------
+
+* +getFormats()+ returns all registered formats.
+* +getFormats(String...)+ allows to access all formats with a given name.
+* +getFormats(URL url)+ allows to access all formats that declare that can optionally read an input from
+  a given `URL`.
+* +readConfigurationData(...)+ reads data from an input and creates a corresponding +ConfigurationData+,
+  either trying all known formats that declare its compatibility with the given input or the formats
+  passed explicitly.
+* +createPropertySource(...)+ allows to create a +PropertySource+ reading a given input and the formats
+  to be used or known. Hereby a default property mapping is applied.
+
+So creating a +PropertySource+ from a resource is basically a one liner:
+
+[source,java]
+-------------------------------------------------------
+URL url = ...;
+PropertySource propertySource = ConfigurationFormats.createPropertySource(url);
+
+// constraining the formats to be used (assumption: json and yaml extensions are loaded)
+PropertySource propertySource = ConfigurationFormats.createPropertySource(
+                                    url,
+                                    ConfigurationFormats.getFormats("json", "yaml"));
+-------------------------------------------------------
+
 
 === Customize how ConfigurationData maps to PropertySource
 
@@ -124,17 +187,18 @@ For for the conversion of +ConfigurationData+ into a +PropertySource+ different
 . In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataPropertySource+
   and overriding the +Map<String,String> populateData(ConfigurationData data)+ method.
 
-In most cases the usage of a +FlattenedDefaultPropertySource+, is a good choice to start. This class
+In most cases the usage of a +MappedConfigurationDataPropertySource+, is a good choice to start. This class
 provides a convenient default mapping and also allows to customized the mapping easily:
 
 [source,java]
 -------------------------------------------------------
 ConfigurationData data = ...;
-FlattenedDefaultPropertySource ps = new FlattenedDefaultPropertySource(data){
-  protected Map<String, String> populateData(ConfigurationData data) {
-    ...
-  }
-};
+MappedConfigurationDataPropertySource ps =
+  new MappedConfigurationDataPropertySource(data){
+    protected Map<String, String> populateData(ConfigurationData data) {
+      ...
+    }
+  };
 -------------------------------------------------------
 
 Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
@@ -158,15 +222,28 @@ function that mus be implemented:
 protected abstract Collection<PropertySource> getPropertySources(ConfigurationData data);
 -------------------------------------------------------
 
+When using Java 8 these mappings can be asily passed as parameters to the +createPropertySource+
+methods.
+
+
+=== Predefined formats
+
+The _formats_ module ships with 3 predefined formats:
+
+* `.ini` files, commonly known from Microsoft based systems, registered as `ini`.
+* `.properties` files, as defined by `java.util.Properties`, registered as `properties`.
+* `.xml` properties files, as defined by `java.util.Properties`, registered as `xml-properties`.
 
-=== Examples
 
-==== Mapping ini-Files
+==== ini Configuration File Mapping
 
-Consider the following ini-file:
+This module implements the ini file format with the class
++org.apache.tamaya.format.formats.IniConfigurationFormat+.
+
+The default mapping is bext illustrated by a small example, so consider the
+following `.ini` file:
 
 [source,listing]
-.Example.ini
 -------------------------------------------------------
 a=valA
 a.b=valB
@@ -179,10 +256,9 @@ aa.b.c=SectionValC
 a=val2Section2
 -------------------------------------------------------
 
-This file content coud be mapped to the following structure:
+This file content by default is mapped to the following Tamaya properties:
 
 [source,listing]
-.Mapping of Example.ini
 -------------------------------------------------------
 a=valA
 a.b=valB
@@ -191,39 +267,25 @@ section1::a.b.c=SectionValC
 section2::a=val2Section2
 -------------------------------------------------------
 
-Nevertheless from the +ConfigurationData+ instance a more complex algorithm can access all the different parts:
+Summarizing
 
-* the_default_ properties (a, a.b)
-* the section +section1+, with properties +aa, aa.b.c+
-* the section +section2+, qith properties +a+
+* entries without a section are mapped to the _default_ section.
+* entries with a section are mapped to a corresponding section, hereby everything between
+  the brackets is used as section name (trimmed).
+* section names are separated using a double colon (`::`).
 
++ConfigurationData+ allows to access all the different parts:
 
-==== Mapping xml-Files
+* the _default_ properties (a, a.b)
+* the section +section1+, with properties +aa, aa.b.c+
+* the section +section2+, with properties +a+
 
-The same concept can also be applied to xml-files. Consider the following configuration file:
 
-[source,xml]
-.Example.conf
--------------------------------------------------------
-<config>
-  <default>
-    <a>valA</a>
-    <a.b>valB</a.B>
-  </default>
+==== XML Property and ordinary Property Files
 
-  <section id="section1">
-    <param id="aa">sectionValA</aa>
-    <param id="aa.b.c">SectionValC</aa.b.c>
-  </section>
-  <section id="section2">
-    <param id="a">val2Section2</aa>
-  </section>
-</config>
--------------------------------------------------------
+This module also ships with +ConfigurationFormat+ implementations that reuse the parsing
+functionality provided with +java.util.Properties+:
 
-This file basically describes the same configuration as the ini-based version we have seen before. The formats
-module hereby ships with 3 format classes:
+* `org.apache.tamaya.format.formats.PropertiesFormat` uses `Properties.read(InputStream)`.
+* `org.apache.tamaya.format.formats.PropertiesXmlFormat` uses `Properties.readFromXml(InputStream)`.
 
-* +PropertiesFormat+ providing support for .properties files.
-* +PropertiesXmlFormat+ providing support for xml.property files.
-* +IniConfiguratonFormat+ providing support for xml.property files.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/27626680/content/documentation/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_json.adoc b/content/documentation/extensions/mod_json.adoc
index c51454e..30ad772 100644
--- a/content/documentation/extensions/mod_json.adoc
+++ b/content/documentation/extensions/mod_json.adoc
@@ -12,7 +12,30 @@ Tamaya _JSON_ is an extension module. Refer to the link:../extensions.html[exten
 
 === What functionality this module provides ?
 
-Tamaya _JSON_ provides support for reading configuration using JSON format:
+Tamaya _JSON_ provides support for reading configuration using JSON
+format:
+
+[source, json]
+-----------------------------------------------
+{
+  "a.b"{
+    "key1": "blabla",
+    "key2": true,
+  }
+}
+-----------------------------------------------
+
+Hereby the hierarchical structure of the JSON document will be mapped to a
+flat key-value pairs of type `String`, e.g. the bove will be mapped to
+
+[source, properties]
+-----------------------------------------------
+a.b.key1=blabla
+a.b.key2=true
+-----------------------------------------------
+
+This extension uses SPI defined by the +tamaya.formats+ extension module.
+
 
 === Compatibility
 
@@ -21,7 +44,7 @@ The module is based on Java 7, so it will run on Java 7 and beyond.
 
 === Installation
 
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
+To use the JSON extension module you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -34,9 +57,11 @@ To benefit from configuration builder support you only must add the correspondin
 
 This extension also transitively requires the +tamaya.formats+ module.
 
+
 === Reading configuration in JSON
 
-For reading JSON based onfiguration most easily a +JSONFormat+ can be provided:
+For reading JSON based onfiguration most easily a +JSONFormat+ can be
+used:
 
 [source, java]
 -----------------------------------------------
@@ -44,20 +69,13 @@ ConfigurationData dataRead = ConfigurationFormats.readConfig(
     getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
 -----------------------------------------------
 
-=== Examples
+Or, if you are fine with the _default_ mapping you can directly create a
++PropertySource+ using the _formats_ API (this works since this module
+registers the _json_ format automatically using the `ServiceContext`):
 
-The JSON module adds instances of +ConfigurationFormat+ so JSON configuration can be read and mapped to the
-according property maps. E.g. the following file is a simple and correct JSON configuration:
+[source, java]
+-----------------------------------------------
+PropertySource ps = ConfigurationFormats.createPropertySource(
+    getClassLoader().getResource("myFileConfig.json"));
+-----------------------------------------------
 
-[source,listing]
-----------------------------------------------------------------
-{
-  "a" : "A",
-  "b" : "B",
-  "c" : "C",
-  "d" : {
-      "o" : "O",
-      "p" : "P"
-    }
-}
-----------------------------------------------------------------

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/27626680/content/documentation/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_management.adoc b/content/documentation/extensions/mod_management.adoc
index 03000e7..8db8318 100644
--- a/content/documentation/extensions/mod_management.adoc
+++ b/content/documentation/extensions/mod_management.adoc
@@ -12,7 +12,8 @@ Tamaya _Management_ is an extension module. Refer to the link:../extensions.html
 
 === What functionality this module provides ?
 
-The Tamaya _Management_ module provides support for registering a JMX management bean for accessing configuration.
+The Tamaya _Management_ module provides support for registering a JMX management bean for
+accessing configuration.
 
 === Compatibility
 
@@ -21,7 +22,8 @@ The module is based on Java 7, so it will run on Java 7 and beyond.
 
 === Installation
 
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
+To use the _management_ extension you only must add the corresponding dependency
+to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -64,6 +66,7 @@ current configuration.
 * +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
   section keys.
 
+
 === Registering the ManagedConfigMBean
 
 For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/27626680/content/documentation/extensions/mod_metamodel-staged.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_metamodel-staged.adoc b/content/documentation/extensions/mod_metamodel-staged.adoc
deleted file mode 100644
index 3c8d24c..0000000
--- a/content/documentation/extensions/mod_metamodel-staged.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Staged PropertySources
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Metamodel: Staged PropertySources (Extension Module)
-
-Tamaya _Staged_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
-
-=== Overview
-
-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 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>{tamaya_version}</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-site/blob/27626680/content/documentation/extensions/mod_metamodel.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_metamodel.adoc b/content/documentation/extensions/mod_metamodel.adoc
new file mode 100644
index 0000000..f7ec32c
--- /dev/null
+++ b/content/documentation/extensions/mod_metamodel.adoc
@@ -0,0 +1,632 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Metamodel (Configuration of Tamaya)
+
+toc::[]
+
+
+[[Model]]
+== Tamaya Metamodel (Configuration of Tamaya) (Extension Module)
+
+Tamaya _metamodel_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
+
+
+=== What functionality this module provides ?
+
+The Tamaya _metamodel_ module provides support for configuring the Tamaya system itself. It
+allows, like a logging configuration, to configure how your configuration framework should
+work, where to find configuration and how it is combined using overrides, filters etc.
+
+By default it uses an XML based configuration format as illustrated below:
+
+[source, xml]
+.Extract from `tamaya-config.xml`
+-----------------------------------------------
+<configuration>
+    <!-- Context is evaluated first. -->
+    <context>
+        <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
+        <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
+        <context-entry name="app">${properties:system.APP?default=NONE}</context-entry>
+        <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry>
+        <context-entry name="company">Trivadis</context-entry>
+        <context-entry name="default-formats">yaml,json</context-entry>
+        <context-entry name="default-refresh-period">5 SECOND</context-entry>
+    </context>
+
+    <!-- combinationPolicy type="" / -->
+
+    <!-- Configuration definition. -->
+
+    <property-sources>
+       <source enabled="${stage=TEST || stage=PTA || stage=PROD}"
+           type="env-properties">
+           <filter type="PropertyMapping">
+               <param name="mapTarget">ENV.</param>
+           </filter>
+           <filter type="AccessMask">
+               <param name="roles">admin,power-user</param>
+               <param name="policy">mask</param>
+               <param name="mask">*****</param>
+               <param name="matchExpression">SEC_</param>
+           </filter>
+       </source>
+       <source type="sys-properties" >
+           <filter type="ImmutablePropertySource" />
+       </source>
+       <source type="file" refreshable="true">
+           <name>config.json</name>
+           <param name="location">config.json</param>
+       </source>
+       ...
+    </property-sources>
+</configuration>
+-----------------------------------------------
+
+The module basically provides an XML representation to the +ConfigurationContextBuilder+ API.
+It creates a corresponding +ConfigurationContext+ and registers the corresponding +Configuration+
+as the system's _default_ configuration (accessible from `ConfigurationProvider.getConfiguration()`.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To use _metamodel_ features you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+  <groupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-model</artifactId>
+  <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Creating a Configuration using Meta-Configuration
+
+The basic feature of this module is the capability of creating a +Configuration+ completely
+based on a meta-configuration file. For this the +MetaConfiguration+ main singleton
+provides different methods:
+
+[source, java)
+-----------------------------------------------
+public final class MetaConfiguration {
+    public static void configure();
+    public static void configure(URL metaConfig);
+    public static ConfigurationContextBuilder createContextBuilder(URL metaConfig);
+    public static Configuration createConfiguration(URL metaConfig);
+-----------------------------------------------
+
+* If you have supplied your meta-configuration at `META-INF/tamaya-config.xml` you simply
+  call +MetaConfiguration.configure();+. This will read the meta-configuration and
+  configure Tamaya's _default_ configuration. Alternatively you can choose your own
+  metaconfiguration location by passing an alternate `URL` ro read from.
+* With +MetaConfiguration.createContextBuilder()+ you can stop a step earlier: a new
+  instance of +ConfigurationContextBuilder+ is created and configured with all the
+  entries found in your meta-configuration. Also here you can optionally pass your
+  custom location for the meta-configuration resouce.
+* Finally +MetaConfiguration.createConfiguration(URL)+ allows you to create an
+  arbitrary +Configuration+ instance using a meta-configuration file. The `Configuration`
+  instance is completely independent and not registered as _default_ configuration, so
+  it's lifecycle and usage is completely under your control.
+
+
+=== MetaContext
+
+When thinking what are the various input parameters for determining a correct configuration, there
+might be different things relevant in different scenarios, especially for developers in different
+companies. A good example of such an input parameter is the current `STAGE`. All these kinf od inputs
+can be summarized in some sort of meta-configuration, commonly known as a _context_. So
+the metamodel extension ships with a +MetaContext+ class that allows to define a common meta-context,
+that can be accessed by components as needed to determine the correct settings to be applied:
+
+[source, java)
+-----------------------------------------------
+public final class MetaContext {
+
+    ...
+
+    public static MetaContext getInstance(String contextName);
+
+    /**
+     * Access the default context. Contexts are managed as weak references in this class. If no
+     * such context exists, a new instance is created.
+     * @return the context instance, never null.
+     */
+    public static MetaContext getDefaultInstance();
+
+    /**
+     * Access a context by name. Contexts are managed as weak references in this class. If no
+     * such valid context exists, a new instance is created, using the given {@code validSupplier}.
+     * @param contextName the context name, not null.
+     * @return the context instance, never null.
+     */
+    public static MetaContext getInstance(String contextName, Supplier<Boolean> validSupplier);
+
+    /**
+     * Access the thread-based context. If no such context
+     * exists a new one will be created.
+     * @param reinit if true, clear's the thread's context.
+     * @return the corresponding context, never null.
+     */
+    public static MetaContext getThreadInstance(boolean reinit);
+
+    /**
+     * Access the current context, which actually is the current context, combined with the thread based
+     * context (overriding).
+     * @return the corresponding context, never null.
+     */
+    public MetaContext getCurrentInstance();
+
+     /**
+     * Access the current context, which actually is the current context, combined with the thread based
+     * context (overriding).
+     * @param reinit if true, clear's the thread's context.
+     * @return the corresponding context, never null.
+     */
+    public MetaContext getCurrentInstance(boolean reinit);
+
+
+    /**
+     * Method to evaluate if a context is valid. This basically depends on the
+     * {@code validSupplier}, if any is set. If no supplier is present the context is valid.
+     *
+     * @return true, if this context is valid.
+     */
+    public boolean isValid();
+
+    /**
+     * Combine this context with the other contexts given, hereby only contexts are included
+     * which are {@code valid}, see {@link #isValid()}.
+     * @param contexts the context to merge with this context.
+     * @return the newly created Context.
+     */
+    public MetaContext combineWith(MetaContext... contexts);
+
+    /**
+     * Access the given context property.
+     * @param key the key, not null
+     * @return the value, or null.
+     */
+    public String getProperty(String key);
+
+    /**
+     * Access the given context property.
+     * @param key the key, not the default value.
+     * @param defaultValue the default value to be returned, if no value is defined, or the
+     *                     stored value's TTL has been reached.
+     * @return the value, default value or null.
+     */
+    public String getProperty(String key, String defaultValue);
+
+    /**
+     * Sets the given context property.
+     * @param key the key, not null.
+     * @param value the value, not null.
+     * @return the porevious value, or null.
+     */
+    public String setProperty(String key, String value);
+
+    /**
+     * Sets the given context property.
+     * @param key the key, not null.
+     * @param value the value, not null.
+     * @param ttl the time to live. Zero or less than zero means, no timeout.
+     * @param unit the target time unit.
+     * @return the porevious value, or null.
+     */
+    public String setProperty(String key, String value, int ttl, TimeUnit unit);
+
+    /**
+     * Sets the given property unless there is already a value defined.
+     * @param key the key, not null.
+     * @param value the value, not null.
+     */
+    public void setPropertyIfAbsent(String key, String value);
+
+    /**
+     * Sets the given property unless there is already a value defined.
+     * @param key the key, not null.
+     * @param value the value, not null.
+     * @param ttl the time to live. Zero or less than zero means, no timeout.
+     * @param unit the target time unit.
+     */
+    public void setPropertyIfAbsent(String key, String value, long ttl, TimeUnit unit);
+
+    /**
+     * Adds all properties given, overriding any existing properties.
+     * @param properties the properties, not null.
+     */
+    public void setProperties(Map<String,String> properties);
+
+    /**
+     * Adds all properties given, overriding any existing properties.
+     * @param properties the properties, not null.
+     * @param ttl the time to live. Zero or less than zero means, no timeout.
+     * @param unit the target time unit.
+     */
+    public void setProperties(Map<String,String> properties, long ttl, TimeUnit unit);
+
+    /**
+     * Checks if all the given properties are present.
+     * @param keys the keys to check, not null.
+     * @return true, if all the given keys are existing.
+     */
+    public boolean checkProperties(String... keys);
+
+    /**
+     * Access all the current context properties.
+     * @return the properties, never null.
+     */
+    public Map<String,String> getProperties();
+}
+-----------------------------------------------
+
+As you see, a +MetaContext+ has the following aspects:
+
+* there are multiple context's possible, identified by their name.
+* Accessing an instance that does not yet exist, will create a new one.
+* there is one shared _default_ instance.
+* they store ordinary `String,String` key, value pairs.
+* they can be _combined_ into a overriging hierarchy
+* accessing the _default_ MetaContext returns the global instance combined with
+  a threaded override instance. Passing `reinit` will clear the thread instance's
+  data.
+
+
+==== Configuring MetaContexts
+
+`MetaContext` instances can be configured in the _meta-configuration_ in the first
+`meta-context` section as illustrated below:
+
+[source, xml]
+-----------------------------------------------
+<!-- Configuring the default context -->
+<context>
+    <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
+    <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
+    <context-entry name="app">${properties:system.APP?default=NONE}</context-entry>
+    <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry>
+    <context-entry name="company">Trivadis</context-entry>
+    <context-entry name="default-formats">yaml,json</context-entry>
+    <context-entry name="default-refresh-period">5 SECOND</context-entry>
+</context>
+<!-- Configuring a context named 'APP' -->
+<context name="APP">
+    <context-entry name="application">someAppName</context-entry>
+</context>
+-----------------------------------------------
+
+As shown above multiple contexts can be configured. Keys and values are of type `String`.
+
+
+===== Using Expressions
+
+As shown before, it is possible to add simple expressions, enclosed in `${}`. Hereby the
+contents must be formatted as `evaluator:expression`, which then internally must be interpreted by
+the +org.apache.tamaya.metamodel.internal.SimpleResolver+, which effectively reads and
+applied context entries.
+
+Currently the following placeholders for context entries are provided:
+
+* properties - mapping to system properties (`properties:sys:KEY`) or
+  environment properties (`properties:env:KEY`) or other MetaContext
+   entries initialized already (`properties:ctx[:CTXNAME]:KEY`)
+* java - mapping to a static method or field, returning a `String` value.
+
+
+=== General Extensions
+
+Working with meta-models requires additional aspects to be generalized to separate
+concerns and reuse some of the common functionality. These concepts are shown in the following
+subsections.
+
+=== Enabled
+
+Things can be dynamically enabled or disabled, e.g. based on context. This can be
+modelled by the +Enabled+ interface:
+
+[source, java]
+-----------------------------------------------
+public interface Enabled {
+
+    /**
+     * Returns the enabled property.
+     * @return the enabled value.
+     */
+    boolean isEnabled();
+
+    /**
+     * Enables/disables this property source.
+     * @param enabled the enabled value.
+     */
+    void setEnabled(boolean enabled);
+}
+-----------------------------------------------
+
++Enabled+ can be used as a mixin-logic, e.g. for decorating property sources,
+property source providers, filters and converters. The decorator can also, if not
+set explicitly, evaluate the _enabled_ property based on the current runtime
+context.
+
+
+=== Refreshable
+
+Similar to _Enabled_ things can also be refreshable.
+
+[source, java]
+-----------------------------------------------
+public interface Refreshable {
+
+    /**
+     * Refreshes the given instance.
+     */
+    void refresh();
+}
+-----------------------------------------------
+
+This can be used to define a common API for refreshing artifctas. Similar to
+_Enabled_ this can be applied as a decorator/mix-in interface to property
+sources and property source providers. This property also is supported in the
+XML metaconfiguration, e.g.
+
+[source, xml]
+-----------------------------------------------
+<property-sources>
+    <source type="file" refreshable="true">
+       <name>config.json</name>
+       <param name="location">config.json</param>
+    </source>
+</property-sources>
+-----------------------------------------------
+
+
+=== The MetaConfiguration XML Structure
+
+In general the `tamaya-config.xml` file does never apply an XML schema or
+similar. Nevertheless there is a common DSL structure, which can be extended
+as well (see next chapter).
+
+[source, xml]
+-----------------------------------------------
+<configuration>
+    <!-- PART ONE: Contexts initialization. -->
+    <context>
+        <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
+        <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
+        ...
+    </context>
+    <context name="APP">
+        <context-entry name="application">someAppName</context-entry>
+    </context>
+
+    <!-- PART TWO: Global settings of ConfigurationContext. -->
+    <!-- combinationPolicy type="" / -->
+
+    <!-- PART THREE: Configuration definition. -->
+
+    <property-sources>
+       <source enabled="${stage=TEST || stage=PTA || stage=PROD}"
+           type="env-properties">
+           <filter type="PropertyMapping">
+               <param name="mapTarget">ENV.</param>
+           </filter>
+           <filter type="AccessMask">
+               <param name="roles">admin,power-user</param>
+               <param name="policy">mask</param>
+               <param name="mask">*****</param>
+               <param name="matchExpression">SEC_</param>
+           </filter>
+       </source>
+       <source type="sys-properties" >
+           <filter type="ImmutablePropertySource" />
+       </source>
+       <source type="file" refreshable="true">
+           <name>config.json</name>
+           <param name="location">config.json</param>
+       </source>
+        <source type="file" refreshable="true">
+            <name>config.xml</name>
+            <param name="location">config.xml</param>
+            <param name="formats">xml-properties</param>
+        </source>
+       <source-provider type="resource">
+           <name>classpath:application-config.yml</name>
+           <param name="location">/META-INF/application-config.yml</param>
+       </source-provider>
+       <source type="ch.mypack.MyClassSource" />
+       <!--<include enabled="${stage==TEST}">TEST-config.xml</include>-->
+       <source-provider type="resource" enabled="${configdir != null}">
+           <name>config-dir</name>
+           <param name="location">/${configdir}/**/*.json</param>
+       </source-provider>
+       <source type="url" refreshable="true">
+           <name>remote</name>
+           <param name="location">https://www.confdrive.com/cfg/customerId=1234</param>
+           <param name="formats">json</param>
+           <filter type="CachedPropertySource">
+               <param name="ttl">30 SECOND</param>
+           </filter>
+       </source>
+    </property-sources>
+    <property-filters>
+        <filter type="UsageTrackerFilter"/>
+        <filter type="AccessControl">
+            <param name="roles">admin,power-user</param>
+            <param name="policy">hide</param>
+            <param name="expression">*.secret</param>
+        </filter>
+        <filter type="Cache">
+            <param name="ttl">30000</param>
+            <param name="expression">cached.*</param>
+        </filter>
+    </property-filters>
+    <property-converters>
+    <!--<converter type="AllInOneConverter"/>-->
+        <default-converters/>
+    </property-converters>
+</configuration>
+-----------------------------------------------
+
+The different parts in fact are not hardcoded, but implemented
+as independent components, where each of them gets access to the
+XML DOM tree to read the configuration aspects of interest.
+Instances related must implement the ++ interface and register it to
+the `ServiceContext`. Reading order is mapped using `@Priority`
+annotations.
+For further details refer to the SPI section in this document.
+
+
+== Model SPI
+
+=== Extending the XML DSL
+
+The XML DSL can be extended in various ways:
+
+* Basically adding a new feature maps to adding a new section to the
+  meta-config XML. This can be easily done, by implementing +MetaConfigurationReader+
+  and do whatever is appropriate for your use case.
+* For adding new expression capabilities for `MetaContext`entries +SimpleResolver+ must
+  be implemented.
+* For allowing customized parameterization of artifacts, e.g. property sources,
+  property source providers, converters and filters etc. you may implement +ItemFactory+
+  instances.
+
+=== MetaConfigurationReader
+
+XML metaconfiguration is effectively processed by instances of
+type +org.apache.tamaya.metamodel.spi.MetaConfigurationReader+:
+
+[source,java]
+-----------------------------------------------------------
+public interface MetaConfigurationReader {
+
+     /**
+      * Reads meta-configuration from the given document and configures the current
+      * context builder. The priority of readers is determined by the priorization policy
+      * implemented by the {@link org.apache.tamaya.spi.ServiceContext},
+      * @param document the meta-configuration document
+      * @param contextBuilder the context builder to use.
+      */
+     void read(Document document, ConfigurationContextBuilder contextBuilder);
+
+ }
+-----------------------------------------------------------
+
+Hereby we also see that an instance of `ConfigurationContextBuilder` is passed.
+Remember, we mentioned earlier that meta-configuration basically is a XML
+API to the building a configuration using a +ConfigurationContextBuilder+. So
+all you can do with the meta-config XML can also be done programmatically using
+the Java API.
+
+This module provides instances of this class for reading of meta-context,
+property-sources, property source providers, converters, filters and more.
+Look into the +org.apache.tamaya.metamodel.internal+ package for further details.
+
+New instances implementing this interface must be registered into the current
++ServiceContext+, by default the +ServiceLoader+ is used.
+
+
+=== ItemFactory
+
+Instances of +ItemFactory+ allow to configure artifacts using XML data:
+
+[source, java]
+-----------------------------------------------------------
+public interface ItemFactory<T> {
+
+    /**
+     * Get the factory name.
+     * @return the factory name, not null.
+     */
+    String getName();
+
+    /**
+     * Create a new instance.
+     * @param parameters the parameters for configuring the instance.
+     * @return the new instance, not null.
+     */
+    T create(Map<String,String> parameters);
+
+    /**
+     * Get the target type created by this factory. This can be used to
+     * assign the factory to an acording item base type, e.g. a PropertySource,
+     * PropertySourceProvider, PropertyFilter etc.
+     * @return the target type, not null.
+     */
+    Class<? extends T> getType();
+
+}
+-----------------------------------------------------------
+
+The factory's name hereby is used as a short cut, e.g. have a look at the following
+XML snippet defining a `PropertySource` to be added:
+
+[source, xml]
+-----------------------------------------------------------
+<source type="file" refreshable="true">
+   <name>config.json</name>
+   <param name="location">config.json</param>
+</source>
+-----------------------------------------------------------
+
+In the above snippet _file_ equals to the factory name, which provides the user
+a simple to use short name, instead of adding the fully qualified classname
+(which is always possible).
+
+The _location_ paramter with its value is passed as `Map` to the `create` method.
+
+
+=== ItemFactoryManager
+
+This singleton class manages the _ItemFactory_ instances found, hereby allowing
+accessing and registering instances. This singleton is actually used by the
+component parsers (type `MetaConfigurationReader`).
+
+[source, java]
+-----------------------------------------------------------
+public final class ItemFactoryManager {
+
+    ...
+
+    public static ItemFactoryManager getInstance();
+
+    public <T> List<ItemFactory<T>> getFactories(Class<T> type);
+    public <T> ItemFactory<T> getFactory(Class<T> type, String id);
+
+    public <T> void registerItemFactory(ItemFactory<T> factory);
+
+}
+-----------------------------------------------------------
+
+
+=== Extended Implementations
+
+The package +org.apache.tamaya.metamodel.ext+ contains a few useful
+implementations that also can be used in your meta-configuration and
+show how mixin-functionality can be added without touching property source
+implementations.
+
+As of now the package contains
+
+* +EnabledPropertySource+: a decorator for a `PropertySource`
+  adding the capability to _enable/disable_ the property source.
+* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider`
+  adding the capability to _enable/disable_ the property source provider.
+* +RefreshablePropertySource+: a decorator for a `PropertySource`
+  adding the capability to _refresh_ the property source.
+* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider`
+  adding the capability to _refresh_ the property source provider.
+
+Not yet implemented but planned are implementations to add the following
+functionality:
+
+* _caching_ of entries for a given time.
+* _immutability_ of entries, so a configuration data (or parts of it) will
+  never change later.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/27626680/content/documentation/extensions/mod_model.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_model.adoc b/content/documentation/extensions/mod_model.adoc
deleted file mode 100644
index 0f74cfb..0000000
--- a/content/documentation/extensions/mod_model.adoc
+++ /dev/null
@@ -1,454 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Model Documentation and Validation
-
-toc::[]
-
-
-[[Model]]
-== Tamaya Model Documentation and Validation (Extension Module)
-
-Tamaya _Model_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
-
-=== What functionality this module provides ?
-
-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>{tamaya_version}</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).


Mime
View raw message