tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject svn commit: r1697094 - in /incubator/tamaya/site/trunk/content/documentation: API.html Core.html index.html mod_builder.html mod_events.html mod_injection.html mod_jodatime.html mod_resolver.html mod_resources.html modules.html
Date Sat, 22 Aug 2015 15:35:18 GMT
Author: anatole
Date: Sat Aug 22 15:35:17 2015
New Revision: 1697094

URL: http://svn.apache.org/r1697094
Log:
Updated site for latest release.

Modified:
    incubator/tamaya/site/trunk/content/documentation/API.html
    incubator/tamaya/site/trunk/content/documentation/Core.html
    incubator/tamaya/site/trunk/content/documentation/index.html
    incubator/tamaya/site/trunk/content/documentation/mod_builder.html
    incubator/tamaya/site/trunk/content/documentation/mod_events.html
    incubator/tamaya/site/trunk/content/documentation/mod_injection.html
    incubator/tamaya/site/trunk/content/documentation/mod_jodatime.html
    incubator/tamaya/site/trunk/content/documentation/mod_resolver.html
    incubator/tamaya/site/trunk/content/documentation/mod_resources.html
    incubator/tamaya/site/trunk/content/documentation/modules.html

Modified: incubator/tamaya/site/trunk/content/documentation/API.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/API.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/API.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/API.html Sat Aug 22 15:35:17 2015
@@ -1006,7 +1006,7 @@ use Lambdas and method references in Jav
 <table>
 <tr>
 <td class="icon">
-<img src="data:image/png:base64," alt="Note">
+<div class="title">Note</div>
 </td>
 <td class="content">
 <code>ConfigSecurity</code> is an arbitrary class only for demonstration purposes.
@@ -1515,7 +1515,7 @@ further details.</p>
 <div id="footer">
 <div id="footer-text">
 Version 0.1-SNAPSHOT<br>
-Last updated 2015-04-29 19:47:55 MESZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/Core.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/Core.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/Core.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/Core.html Sat Aug 22 15:35:17 2015
@@ -765,7 +765,7 @@ class names of the converters to be regi
 <table>
 <tr>
 <td class="icon">
-<img src="data:image/png:base64," alt="Note">
+<div class="title">Note</div>
 </td>
 <td class="content">
 API Implementations can be read-only thus not allowing adding additional converters programmatically.
@@ -988,7 +988,8 @@ present that loads all .properties files
 <div class="sectionbody">
 <div class="paragraph">
 <p>The Core module only implements the <a href="API.html">API</a>. Many users require/wish additional functionality from a
-configuration system. Fortunately there are numerous extensions available, that add different functionality.
+configuration system. Fortunately there are numerous extensions available that add further functionality
+(most of them are compatible with Java 7 and 8, so you can use regardless which version of the API you are using).
 Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath.</p>
 </div>
 <div class="paragraph">
@@ -1000,7 +1001,7 @@ Loading extensions hereby is trivial: yo
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-03-03 12:58:16 MEZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/index.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/index.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/index.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/index.html Sat Aug 22 15:35:17 2015
@@ -516,19 +516,22 @@ table.CodeRay td.code>pre{padding:0}
 <ul class="sectlevel1">
 <li><a href="#_introduction">1. Introduction</a>
 <ul class="sectlevel2">
-<li><a href="#_working_group">1.1. Working Group</a></li>
-<li><a href="#_goals">1.2. Goals</a></li>
-<li><a href="#_required_java_version">1.3. Required Java version</a></li>
+<li><a href="#WhatIsTamaya">1.1. What is Apache Tamaya?</a></li>
+<li><a href="#_what_is_apache_tamaya_not">1.2. What is Apache Tamaya NOT?</a></li>
+<li><a href="#WhatCanIDoEithTamaya">1.3. And what can I do with Apache Tamaya?</a></li>
+<li><a href="#WorkingGroup">1.4. Working Group</a></li>
+<li><a href="#_goals">1.5. Goals</a></li>
+<li><a href="#_targets">1.6. Targets</a></li>
+<li><a href="#_required_java_version">1.7. Required Java version</a></li>
 </ul>
 </li>
-<li><a href="#_overview">2. Overview</a>
+<li><a href="#_where_should_i_continue">2. Where should I continue</a>
 <ul class="sectlevel2">
-<li><a href="#_how_is_tamaya_organized">2.1. How is Tamaya organized</a></li>
+<li><a href="#_further_documentation">2.1. Further Documentation</a></li>
+<li><a href="#_api_documentation">2.2. API Documentation</a></li>
+<li><a href="#_examples">2.3. Examples</a></li>
 </ul>
 </li>
-<li><a href="#_further_information">3. Further Information</a></li>
-<li><a href="#_detailed_documentation">4. Detailed Documentation</a></li>
-<li><a href="#_examples">5. Examples</a></li>
 </ul>
 </div>
 </div>
@@ -569,12 +572,86 @@ under the License.</pre>
 <div class="sect1">
 <h2 id="_introduction">1. Introduction</h2>
 <div class="sectionbody">
+<div class="sect2">
+<h3 id="WhatIsTamaya">1.1. What is Apache Tamaya?</h3>
+<div class="paragraph">
+<p>Tamaya is a very powerful yet flexible configuration solution. It&#8217;s core is built based on a few simple concepts.
+Summarizing Tamaya provides you</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>a simple <em>key/value</em> configuration model.</p>
+</li>
+<li>
+<p>a uniform API for accessing <em>configuration</em>, regardless if you are running in a Java SE, Java EE or OSGI environment.
+This API is capable of hiding all the complexities in configuration management, your developers only need to know,
+where and in which format configuration can be added to the system.</p>
+</li>
+<li>
+<p>A <code>ConfigurationBuilder</code> allowing you to create a configuration completely manually and managing the configuration
+lifecycle on your own.</p>
+</li>
+<li>
+<p>a minimalistic implementation, which in the future might also be targeting Java ME environments.</p>
+</li>
+<li>
+<p>a powerful SPI that allows you to extend/adapt Tamaya with all kind of additional mechanisms commonly used in
+many use cases.</p>
+</li>
+<li>
+<p>a bunch of modules that can be added to your classpath thus adding different functionality to your system as needed.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_what_is_apache_tamaya_not">1.2. What is Apache Tamaya NOT?</h3>
+<div class="paragraph">
+<p>Nevertheless there are a few things that are not part of Tamaya:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Tamaya comes as a modular framework, where you have to decide, which features make sense for you. So you have to do
+a selection, which modules make sense.</p>
+</li>
+<li>
+<p>Though Tamaya comes with a very minimalistic configuration scheme out-of-the-box, it does by default typically not
+cover your enterprise requirements. Also here Tamaya offers hooks and examples showing how you can easily
+replace your current configuration logic with Tamaya. So you must know how you want to organize configuration in
+your enterprise context, such as supported file locations, formats, overriding and filter rules etc.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect2">
+<h3 id="WhatCanIDoEithTamaya">1.3. And what can I do with Apache Tamaya?</h3>
 <div class="paragraph">
-<p>This documentation describes the Tamaya Configuration System. It provides an overview of the different building blocks and
-links you to more detailed documentations.</p>
+<p>There are basically two main usage scenarios, which are synergetic:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>In an enterprise context you can easily implement a configuration architecture for your whole company and deploy the
+logic as an extension module. All application development teams in your company can then depend on this module (and the
+basic Tamaya core implementation). As a result all applications/modules in your company follow the same configuration
+policy, which makes it much more simpler to move people between your teams. Similarly additional tooling functionality
+can help you to manage configuration on application as well as on enterprise level, e.g. providing command line or
+REST support to access the supported configuration entries, types and values, configuration validation and more.</p>
+</li>
+<li>
+<p>If you are writing an application, application component or library you can support configuration using Tamaya by
+adding it as an optional dependency. If done so your users/customers can use Tamaya to connect their current enterprise
+configuration infrastructure transparently to your code. As an example you can use Tamaya to read your default
+configuration files, but since Tamaya is so easily extendable, customers can deploy an additional jar, which then
+allows them to add their own configuration mechanisms such as databases, datagrids or REST services.</p>
+</li>
+</ul>
+</div>
 </div>
 <div class="sect2">
-<h3 id="_working_group">1.1. Working Group</h3>
+<h3 id="WorkingGroup">1.4. Working Group</h3>
 <div class="paragraph">
 <p>This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This
 specification is the result of the collaborative work of the members of the Tamaya Users Group and the community at
@@ -582,15 +659,16 @@ large.</p>
 </div>
 </div>
 <div class="sect2">
-<h3 id="_goals">1.2. Goals</h3>
+<h3 id="_goals">1.5. Goals</h3>
 <div class="paragraph">
 <p>Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of
 well defined aspects of a software product without having to recompile/rebuild the code. Summarizing configuration
 can affect basically every part of a system, which renders configuration to a real cross-cutting concern, usable in
 many facets.</p>
 </div>
-<div class="sect3">
-<h4 id="_targets">1.2.1. Targets</h4>
+</div>
+<div class="sect2">
+<h3 id="_targets">1.6. Targets</h3>
 <div class="paragraph">
 <p>Tamaya targets to support all general configuration aspects in a system, e.g.</p>
 </div>
@@ -654,22 +732,6 @@ URIs are supported by default.</p>
 </li>
 </ul>
 </div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_required_java_version">1.3. Required Java version</h3>
-<div class="paragraph">
-<p>The full API is based on Java SE 8.0 language features, whereas a compatible implementation of API and Core
-is similarly available for Java SE 7 as well.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_overview">2. Overview</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_how_is_tamaya_organized">2.1. How is Tamaya organized</h3>
 <div class="paragraph">
 <p>The Tamaya project consists of the following parts:</p>
 </div>
@@ -687,18 +749,17 @@ It is modelled in a extensible way and o
 <p>Reading configuration as type safe values, including type conversion.</p>
 </li>
 <li>
-<p>Extending configuration using operators and queries.</p>
+<p>Converting/mapping configuration using operators and queries.</p>
 </li>
 <li>
-<p>An SPI providing abstractions for component lifecycle, property sources, property source providers, configuration
-context and property filters.</p>
+<p>An SPI providing abstractions for handling property sources, property filters and component lifecycle management.</p>
 </li>
 </ul>
 </div>
 </li>
 <li>
-<p>The <a href="Core.html">Core</a> implements the <a href="API.html">API</a>. Basically with the core part (and the API) you are ready to go, but you may
-add additional extensions that provide more features that are very useful.</p>
+<p>The <a href="Core.html">Core</a> implements the <a href="API.html">API</a>. Basically with the core part (and the API) you are ready
+to go, but you may want to add additional extensions that provide more features that are very useful.</p>
 </li>
 <li>
 <p>Extensions are additional libraries that you can add to your project setup. Most important features are:</p>
@@ -734,58 +795,83 @@ add additional extensions that provide m
 </ul>
 </div>
 </div>
+<div class="sect2">
+<h3 id="_required_java_version">1.7. Required Java version</h3>
+<div class="paragraph">
+<p>The full API is based on Java SE 8.0 language features, whereas a compatible implementation of API and Core
+is similarly available for Java SE 7 as well.</p>
+</div>
+</div>
 </div>
 </div>
 <div class="sect1">
-<h2 id="_further_information">3. Further Information</h2>
+<h2 id="_where_should_i_continue">2. Where should I continue</h2>
 <div class="sectionbody">
+<div class="sect2">
+<h3 id="_further_documentation">2.1. Further Documentation</h3>
 <div class="ulist">
 <ul>
 <li>
-<p>There is a small document discussing <a href="usecases.html">Use Cases</a> and</p>
+<p>If you want to have a deeper look at the API/SPI, we recommend the <a href="API.html">API documentation</a>.</p>
 </li>
 <li>
-<p>a document discussing <a href="requirements.html">Requirements</a>.</p>
+<p>If you want to have an overview about the available modules, continue <a href="modules.html">here</a>.</p>
+</li>
+<li>
+<p>If you want to look to the numerous examples, continue <a href="examples.html">here</a>.</p>
+</li>
+<li>
+<p>If you are interested in the software design in place, continue <a href="HighLevelDesign.html">here</a>.</p>
 </li>
 </ul>
 </div>
+<div class="paragraph">
+<p>Finally
+* If you are interested in the collected requirements, continue <a href="Requirements.html">here</a>.
+* If you are interested in the collected use cases, continue <a href="usecases.html">here</a>.</p>
 </div>
 </div>
-<div class="sect1">
-<h2 id="_detailed_documentation">4. Detailed Documentation</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_api_documentation">2.2. API Documentation</h3>
+<div class="paragraph">
+<p>Javadoc of the current API</p>
+</div>
 <div class="ulist">
 <ul>
 <li>
-<p><a href="API.html">Tamaya API Documentation</a> and <a href="../javadoc/api/index.html">API Javadoc</a></p>
-</li>
-<li>
-<p><a href="Core.html">Tamaya Core Documentation</a> and <a href="../javadoc/core/index.html">Core Javadoc</a></p>
-</li>
-<li>
-<p><a href="modules.html">Tamaya Modules Documentation</a> and <a href="../javadoc/modules/index.html">Extensions Javadoc</a></p>
+<p><a href="API.html">General API Documentation</a> and <a href="../javadoc/api/java7/index.html">API Javadoc for Java7</a> /
+<a href="../javadoc/api/java8/index.html">API Javadoc for Java8</a></p>
 </li>
 </ul>
 </div>
+<div class="paragraph">
+<p>Javadoc of the current Core Implementation</p>
 </div>
-</div>
-<div class="sect1">
-<h2 id="_examples">5. Examples</h2>
-<div class="sectionbody">
 <div class="ulist">
 <ul>
 <li>
-<p>A comprehensive set of examples can be found <a href="../examples.html">here</a>.</p>
+<p><a href="Core.html">General Core Documentation</a> and <a href="../javadoc/core/java7/index.html">Core Javadoc for Java7</a> /
+<a href="../javadoc/core/java8/index.html">Core Javadoc for Java8</a></p>
 </li>
 </ul>
 </div>
+<div class="paragraph">
+<p>Javadoc of the current Extension Modules</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_examples">2.3. Examples</h3>
+<div class="paragraph">
+<p>A comprehensive set of examples can be found <a href="../examples.html">here</a>.</p>
+</div>
+</div>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
 Version 0.1-SNAPSHOT<br>
-Last updated 2015-03-03 12:58:26 MEZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/mod_builder.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/mod_builder.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/mod_builder.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/mod_builder.html Sat Aug 22 15:35:17 2015
@@ -515,12 +515,92 @@ table.CodeRay td.code>pre{padding:0}
 </div>
 </div>
 <div class="sect1">
-<h2 id="Core">Tamaya Builder (Extension Module)</h2>
+<h2 id="BuilderCore">Tamaya Builder (Extension Module)</h2>
 <div class="sectionbody">
 <div class="sect2">
 <h3 id="_overview">Overview</h3>
 <div class="paragraph">
-<p>TBW</p>
+<p>The Tamaya builder module provides a generic (one time) builder for creating Configuration instances,
+e.g. as follows:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">ConfigurationBuilder builder = <span class="keyword">new</span> ConfigurationBuilder();
+<span class="comment">// do something</span>
+<span class="predefined-type">Configuration</span> config = builder.build();</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Basically the builder allows to create configuration instances completely independent of the current configuration
+setup. This gives you full control on the Configuration setup.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_compatibility">Compatibility</h3>
+<div class="paragraph">
+<p>The module is based on Java 8, so it will not run on Java 7. This might be not that bad, since 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:</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installation">Installation</h3>
+<div class="paragraph">
+<p>To benefit from configuration builder support you only must add the corresponding dependency to your module:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
+  <span class="tag">&lt;groupId&gt;</span>org.apache.tamaya.ext<span class="tag">&lt;/groupId&gt;</span>
+  <span class="tag">&lt;artifactId&gt;</span>tamaya-builder<span class="tag">&lt;/artifactId&gt;</span>
+  <span class="tag">&lt;version&gt;</span>{tamayaVersion}<span class="tag">&lt;/version&gt;</span>
+<span class="tag">&lt;/dependency&gt;</span></code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_supported_functionality">Supported Functionality</h3>
+<div class="paragraph">
+<p>The builder allows you to add PropertySource instances:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">ConfigurationBuilder builder = <span class="keyword">new</span> ConfigurationBuilder();
+builder.addPropertySources(sourceOne).addPropertySources(sourceTwo);
+<span class="predefined-type">Configuration</span> config = builder.build();</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Similarly you can add filters:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">builder.addPropertyFilters(<span class="keyword">new</span> MyConfigFilter());</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>&#8230;&#8203;or PropertySourceProvider instances:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">builder.addPropertySourceProvider(<span class="keyword">new</span> MyPropertySourceProvider());</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Also the builder module allows to include/exclude any filters and property source already known to the current
+ConfigurationContext:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">builder.disableProvidedPropertyConverters();
+builder.enableProvidedPropertyConverters();
+
+builder.disableProvidedPropertyFilters();
+builder.enableProvidedPropertyFilters();
+
+builder.disableProvidedPropertySources();
+builder.enableProvidedPropertySources();</code></pre>
+</div>
 </div>
 </div>
 </div>
@@ -529,7 +609,7 @@ table.CodeRay td.code>pre{padding:0}
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-04-16 22:34:28 MESZ
+Last updated 2015-08-06 01:18:00 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/mod_events.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/mod_events.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/mod_events.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/mod_events.html Sat Aug 22 15:35:17 2015
@@ -5,8 +5,7 @@
 <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 1.5.2">
-<meta name="author" content="'''">
-<title>Apache Tamaya Extension: Events</title>
+<title>Apache Tamaya&#8201;&#8212;&#8201;Extension: Events</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">
 <style>
 /* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
@@ -504,27 +503,11 @@ table.CodeRay td.code>pre{padding:0}
 <body class="article">
 <div id="header">
 <h1>Apache Tamaya&#8201;&#8212;&#8201;Extension: Events</h1>
-<div class="details">
-<span id="author" class="author">Anatole Tresch</span><br>
-<span id="email" class="email">&lt;<a href="mailto:anatole@apache.org" title="Apache Tamaya Extension: Events">anatole@apache.org</a>&gt;</span><br>
-<span id="revnumber">version 0.1.1,</span>
-<span id="revdate">March 2015</span>
-<br><span id="revremark">Incubator</span>
-</div>
-<div id="toc" class="toc">
-<div id="toctitle">Table of Contents</div>
-<ul class="sectlevel1">
-<li><a href="#Core">Tamaya Events (Extension Module)</a>
-<ul class="sectlevel2">
-<li><a href="#_overview">Overview</a></li>
-</ul>
-</li>
-</ul>
-</div>
 </div>
 <div id="content">
 <div id="preamble">
 <div class="sectionbody">
+<hr>
 <div style="page-break-after: always;"></div>
 <!-- toc disabled -->
 <div style="page-break-after: always;"></div>
@@ -537,14 +520,378 @@ table.CodeRay td.code>pre{padding:0}
 <div class="sect2">
 <h3 id="_overview">Overview</h3>
 <div class="paragraph">
-<p>Tamaya Events is an extension module. Refer to the <a href=":modules.html">extensions documentation</a> for further details
+<p>Tamaya Events is an extension module. Refer to the <a href="modules.html" title="Apache Tamaya Extension: Events">extensions documentation</a> for further details
 about modules.</p>
 </div>
 <div class="paragraph">
 <p>Tamaya Events provides an abstraction for events like change events, when configuration has bee changed.</p>
 </div>
+</div>
+<div class="sect2">
+<h3 id="_compatibility">Compatibility</h3>
+<div class="paragraph">
+<p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installation">Installation</h3>
+<div class="paragraph">
+<p>To benefit from configuration event support you only must add the corresponding dependency to your module:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
+  <span class="tag">&lt;groupId&gt;</span>org.apache.tamaya.ext<span class="tag">&lt;/groupId&gt;</span>
+  <span class="tag">&lt;artifactId&gt;</span>tamaya-events<span class="tag">&lt;/artifactId&gt;</span>
+  <span class="tag">&lt;version&gt;</span>{tamayaVersion}<span class="tag">&lt;/version&gt;</span>
+<span class="tag">&lt;/dependency&gt;</span></code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_core_architecture">Core Architecture</h3>
+<div class="paragraph">
+<p>The core of the module are the ConfigEventListener interface and the ConfigEvent class, which defines an abstraction
+for event handling and observation:</p>
+</div>
+<div class="listingblock">
+<div class="title">ConfigEvent</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">ConfigEvent</span> {
+
+    <span class="directive">public</span> ConfigEvent() {
+    }
+
+    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> addListener(ConfigEventListener&lt;?&gt; l);
+    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> removeListener(ConfigEventListener&lt;?&gt; l);
+    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> fireEvent(<span class="predefined-type">Object</span> event);
+    <span class="directive">public</span> <span class="directive">static</span> &lt;T&gt; <span class="type">void</span> fireEvent(T event, <span class="predefined-type">Class</span>&lt;T&gt; eventType);
+
+}
+
+<span class="comment">// @FunctionalInterface</span>
+<span class="directive">public</span> <span class="type">interface</span> <span class="class">ConfigEventListener</span>&lt;T&gt; {
+    <span class="comment">/**
+     * Called if an event occurred.
+     * @param event the event, not null.
+     */</span>
+    <span class="type">void</span> onConfigEvent(T event);
+
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This mechanism can now be used to propagate configuration changes to all interested stakeholders. The next sections
+give more details on the the provided event implementations and abstractions that are used to implement such
+features.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_modelling_configuration_changes">Modelling Configuration Changes</h3>
+<div class="paragraph">
+<p>This module provides a serializable and thread-safe abstraction modlling a configuration change. A change hereby may
+be</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>additional configuration entries</p>
+</li>
+<li>
+<p>removed configuration entries</p>
+</li>
+<li>
+<p>changes on entries</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>This is also reflected in the ChangeType enum</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">enum</span> ChangeType {
+    NEW,
+    DELETED,
+    UPDATED,
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This enum type is used within the ConfigurationChange class:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">ConfigurationChange</span> <span class="directive">implements</span> <span class="predefined-type">Serializable</span>{
+
+    <span class="directive">public</span> <span class="directive">static</span> ConfigurationChange emptyChangeSet(<span class="predefined-type">Configuration</span> configuration);
+
+    <span class="directive">public</span> <span class="predefined-type">Configuration</span> getConfiguration();
+
+    <span class="directive">public</span> <span class="predefined-type">String</span> getVersion();
+    <span class="directive">public</span> <span class="type">long</span> getTimestamp();
+    <span class="directive">public</span> <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">PropertyChangeEvent</span>&gt; getEvents();
+
+    <span class="directive">public</span> <span class="type">int</span> getRemovedSize();
+    <span class="directive">public</span> <span class="type">int</span> getAddedSize();
+    <span class="directive">public</span> <span class="type">int</span> getUpdatedSize();
+
+    <span class="directive">public</span> <span class="type">boolean</span> isRemoved(<span class="predefined-type">String</span> key);
+    <span class="directive">public</span> <span class="type">boolean</span> isAdded(<span class="predefined-type">String</span> key);
+    <span class="directive">public</span> <span class="type">boolean</span> isUpdated(<span class="predefined-type">String</span> key);
+    <span class="directive">public</span> <span class="type">boolean</span> containsKey(<span class="predefined-type">String</span> key);
+    <span class="directive">public</span> <span class="type">boolean</span> isEmpty();
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>New instances of this class hereby are created using a fluent builder:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Configuration</span> config = ...;
+ConfigurationChange change = ConfigurationChangeBuilder.of(config)
+  .addChange(<span class="string"><span class="delimiter">&quot;</span><span class="content">MyKey</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">newValue</span><span class="delimiter">&quot;</span></span>)
+  .removeKeys(<span class="string"><span class="delimiter">&quot;</span><span class="content">myRemovedKey</span><span class="delimiter">&quot;</span></span>).build();</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Also it is possible to directly compare 2 instances of configurations to create a matching ConfigurationChange
+instance:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">Comparing <span class="integer">2</span> configurations
+-------------------------------------------------------
+<span class="predefined-type">Configuration</span> config = ...;
+<span class="predefined-type">Configuration</span> changedConfig = ...;
+ConfigurationChange change = ConfigurationChangeBuilder.of(config)
+  .addChanges(changedConfig).build();
+-------------------------------------------------------</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>So a ConfigurationChange allows you to evaluate the changes on a configuration. This allows you to listen to changes
+and react in your client code as useful, once you encounter changes that are relevant to you, e.g. by reconfiguring
+your component. Of course, your code has to register itself to listen for appropriate changes by implementing
+a ConfigEventListener:</p>
+</div>
+<div class="listingblock">
+<div class="title">Implementing a ConfigChangeListener</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">MyConfigChangeListener</span> <span class="directive">implements</span> ConfigChangeListener&lt;ConfigurationChange&gt;{
+
+  <span class="directive">private</span> <span class="predefined-type">Configuration</span> config = ConfigurationProvider.getConfiguration();
+
+  <span class="directive">public</span> <span class="type">void</span> onConfigEvent(ConfigurationChange event){
+     <span class="keyword">if</span>(event.getConfiguration()==config){
+       <span class="comment">// do something</span>
+     }
+  }
+
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can <strong>register</strong> your implementation in 2 ways:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Manually by calling ConfigEvent.addListener(new MyConfigChangeListener())</p>
+</li>
+<li>
+<p>Automatically by registering your listener using the ServiceLoader under
+META-INF/services/org.apache.tamaya.ConfigEventListener</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_modelling_propertysource_changes">Modelling PropertySource Changes</h3>
+<div class="paragraph">
+<p>Beside that a whole configuration changes, also PropertySource instance can change, e.g. by a configuration file
+edited on the fly. This is similarly to ConfigurationChange reflected by the classes PropertySourceChange,
+PropertySourceChangeBuilder.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_modelling_configuration_context_changes">Modelling Configuration Context Changes</h3>
+<div class="paragraph">
+<p>The ConfigurationContext models the container that manages all subcomponents that are used to define and
+evalaute a Configuration. In the case where configuration is dynamically loaded, e.g. by observing changes on a
+file folder, the ConfigurationContext may change, so a corresponding ConfigurationContextChange event is
+defined:</p>
+</div>
+<div class="listingblock">
+<div class="title">Implementing a ConfigChangeListener</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">ConfigurationContextChange</span> <span class="directive">implements</span> <span class="predefined-type">Serializable</span>{
+
+    <span class="directive">public</span> <span class="directive">static</span> ConfigurationContextChange emptyChangeSet();
+
+    <span class="directive">public</span> <span class="predefined-type">String</span> getVersion();
+    <span class="directive">public</span> <span class="type">long</span> getTimestamp();
+    <span class="directive">public</span> <span class="predefined-type">Collection</span>&lt;PropertySourceChange&gt; getPropertySourceChanges();
+    <span class="directive">public</span> <span class="predefined-type">Collection</span>&lt;PropertySourceChange&gt; getPropertySourceUpdates();
+    <span class="directive">public</span> <span class="predefined-type">Collection</span>&lt;PropertySource&gt; getRemovedPropertySources();
+    <span class="directive">public</span> <span class="predefined-type">Collection</span>&lt;PropertySource&gt; getAddedPropertySources();
+    <span class="directive">public</span> <span class="predefined-type">Collection</span>&lt;PropertySource&gt; getUpdatedPropertySources();
+    <span class="directive">public</span> <span class="type">boolean</span> isAffected(PropertySource propertySource);
+    <span class="directive">public</span> <span class="type">boolean</span> isEmpty();
+}</code></pre>
+</div>
+</div>
 <div class="paragraph">
-<p>tbc&#8230;&#8203;</p>
+<p>Similar to the ConfigurationChange class you also must use a ConfigurationContextChangeBuilder to create instances
+of ConfigurationContextChange.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_modelling_of_an_observing_propertysourceprovider">Modelling of an observing PropertySourceProvider.</h3>
+<div class="paragraph">
+<p>In Tamaya configuration data is provided by instances of PropertySource, which in case of a configuration directory
+may be provided by an implementation of PropertySourceProvider. The events module provides a base provider
+implementation that</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>observes all changes in a Path</p>
+</li>
+<li>
+<p>tries to reevaluate corresponding resources based on the ConfigurationFormats supported.</p>
+</li>
+<li>
+<p>it creates an instance of ConfigurationContextChange reflecting the changed ConfigurationContext and triggers
+this event by calling ConfigEvent.fireEvent(contextChange);.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Additionally this module registers an instance of ConfigEventListener&lt;ConfigurationContextChange&gt;+, which listenes to
+these events. If such an event is triggered the listener tries to apply the changes by</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>accessing the current Configuration and its ConfigurationContext</p>
+</li>
+<li>
+<p>checking if the event is affecting the current ConfigurationContext.</p>
+</li>
+<li>
+<p>in the case the current context is affected, based on the current ConfigurationContext a new context is created,
+whereas</p>
+<div class="olist loweralpha">
+<ol class="loweralpha" type="a">
+<li>
+<p>all PropertySources provided by this provider implementation type are removed.</p>
+</li>
+<li>
+<p>the new PropertySources loaded are added.</p>
+</li>
+</ol>
+</div>
+</li>
+<li>
+<p>Finally the listener tries to apply the new ConfigurationContext by calling the corresponding API methods of the
+ConfigurationProvider:</p>
+</li>
+</ol>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">try</span> {
+    ConfigurationProvider.setConfigurationContext(newContext);
+} <span class="keyword">catch</span> (<span class="exception">Exception</span> e) {
+    LOG.log(<span class="predefined-type">Level</span>.INFO, <span class="string"><span class="delimiter">&quot;</span><span class="content">Failed to update the current ConfigurationContext due to config model changes</span><span class="delimiter">&quot;</span></span>, e);
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>So if the current ConfigurationProvider supports reloading of the current ConfigurationContext this will apply the
+changes to the current Configuration. Otherwise the change is logged, but no further actions are taken.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_freezing_configurations_and_propertysources">Freezing Configurations and PropertySources</h3>
+<div class="paragraph">
+<p>Configuration instances as well as PropertySources are explicitly not required to be serializable. To enable easy
+serialization of these types as well as to fix a current state (e.g. for later comparison with a newly loaded instance)
+Tamaya allows to <strong>freeze</strong> instances of these types. Freezing hereby means</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>all key/values are read-out by calling the getProperties() method.</p>
+</li>
+<li>
+<p>a meta data entry is added of the form [meta]frozenAt=223273777652325677, whichdefines the UTC timestamp in
+milliseconds when this instance was frozen.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>In code this is done easily as follows:</p>
+</div>
+<div class="listingblock">
+<div class="title">Freezing the current Configuration</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Configuration</span> frozenConfig = FrozenConfiguration.of(ConfigurationProvider.getConfiguration());</code></pre>
+</div>
+</div>
+<div class="olist lowerroman">
+<ol class="lowerroman" type="i">
+<li>
+<p>and similarly for a PropertySource:</p>
+</li>
+</ol>
+</div>
+<div class="listingblock">
+<div class="title">Freezing the current Configuration</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">PropertySource frozenSource = FrozenPropertySource.of(ConfigurationProvider.getConfiguration());</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_spis">SPIs</h3>
+<div class="paragraph">
+<p>This component also defines an additional SPI, which allows to implement/adapt the mechanism how events are forwarded/
+received and how ConfigEventListeners are managed. This enables to use external eventing systems, such as CDI,
+instead of the simple SE, fully synchronized implementation provided by default.</p>
+</div>
+<div class="listingblock">
+<div class="title">SPI: ConfigEventSpi</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">ConfigEventSpi</span> {
+    <span class="comment">/**
+     * Add a listener for observing events. References of this
+     * component to the listeners must be managed as weak references.
+     *
+     * @param l the listener not null.
+     */</span>
+    &lt;T&gt; <span class="type">void</span> addListener(ConfigEventListener&lt;T&gt; l);
+
+
+    <span class="comment">/**
+     * Removes a listener for observing events.
+     *
+     * @param l the listener not null.
+     */</span>
+    &lt;T&gt; <span class="type">void</span> removeListener(ConfigEventListener&lt;T&gt; l);
+
+    <span class="comment">/**
+     * Publishes an event to all interested listeners.
+     *
+     * @param event     the event, not null.
+     * @param eventType the event type.
+     */</span>
+    &lt;T&gt; <span class="type">void</span> fireEvent(T event, <span class="predefined-type">Class</span>&lt;T&gt; eventType);
+
+}</code></pre>
+</div>
 </div>
 </div>
 </div>
@@ -553,7 +900,7 @@ about modules.</p>
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-03-03 15:56:26 MEZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/mod_injection.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/mod_injection.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/mod_injection.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/mod_injection.html Sat Aug 22 15:35:17 2015
@@ -531,7 +531,34 @@ template instances.</p>
 <p>Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate
 code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a
 built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the
-according injection services. This module adds this functionality to Tamaya. As an example refer to the following
+according injection services. This module adds this functionality to Tamaya.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_compatibility">Compatibility</h3>
+<div class="paragraph">
+<p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installation">Installation</h3>
+<div class="paragraph">
+<p>To benefit from configuration event support you only must add the corresponding dependency to your module:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
+  <span class="tag">&lt;groupId&gt;</span>org.apache.tamaya.ext<span class="tag">&lt;/groupId&gt;</span>
+  <span class="tag">&lt;artifactId&gt;</span>tamaya-injection<span class="tag">&lt;/artifactId&gt;</span>
+  <span class="tag">&lt;version&gt;</span>{tamayaVersion}<span class="tag">&lt;/version&gt;</span>
+<span class="tag">&lt;/dependency&gt;</span></code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_core_concepts">Core Concepts</h3>
+<div class="paragraph">
+<p>As an example refer to the following
 code snippet:</p>
 </div>
 <div class="listingblock">
@@ -563,7 +590,7 @@ code snippet:</p>
 
     <span class="comment">// Overriding the String -&gt; BigDecimal converter with a custom implementation.</span>
     <span class="annotation">@ConfiguredProperty</span>(keys=<span class="string"><span class="delimiter">&quot;</span><span class="content">BD</span><span class="delimiter">&quot;</span></span>)
-    <span class="annotation">@WithAdapter</span>(MyBigDecimalRoundingAdapter.class)
+    <span class="annotation">@WithPropertyConverter</span>(MyBigDecimalRoundingAdapter.class)
     <span class="directive">private</span> <span class="predefined-type">BigDecimal</span> bigNumber;
 
     ...
@@ -582,8 +609,11 @@ Tamaya inject the configuration (or thro
 ConfigurationInjector.configure(configuredClass);</code></pre>
 </div>
 </div>
+</div>
+<div class="sect2">
+<h3 id="_the_annotations_in_detail">The Annotations in detail</h3>
 <div class="sect3">
-<h4 id="_the_annotations_in_detail">The Annotations in detail</h4>
+<h4 id="_the_configurationinjector">The ConfigurationInjector</h4>
 <div class="paragraph">
 <p>The ConfigurationInjector interface provides methods that allow any kind of instances to be configured
 by passing the instances to T ConfigurationInjector.getInstance().configure(T);. The classes passed
@@ -620,6 +650,7 @@ name=&lt;unnamed&gt;</code></pre>
 <div class="content">
 <pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">a.b</span>;
 
+<span class="annotation">@ConfiguredType</span>(autoConfigure=<span class="predefined-constant">true</span>)
 <span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">Tenant</span>{
   <span class="directive">private</span> <span class="type">int</span> id;
   <span class="directive">private</span> <span class="predefined-type">String</span> name;
@@ -639,20 +670,39 @@ name=&lt;unnamed&gt;</code></pre>
 Tenant tenant = ConfigurationInjector.getInstance().configure(<span class="keyword">new</span> Tenant());</code></pre>
 </div>
 </div>
+</div>
+<div class="sect3">
+<h4 id="_accessing_configureditemsupplier_instances">Accessing ConfiguredItemSupplier instances</h4>
 <div class="paragraph">
 <p>In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
 by the current context. This can be done using Suppliers:</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">Supplier&lt;Tenant&gt; configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(Tenant::<span class="keyword">new</span>);</code></pre>
+<pre class="CodeRay highlight"><code data-lang="java">ConfiguredItemSupplier&lt;Tenant&gt; configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
+  <span class="keyword">new</span> ConfiguredItemSupplier&lt;Tenant&gt;(){
+     <span class="directive">public</span> Tenant get(){
+       <span class="keyword">return</span> <span class="keyword">new</span> Tenant();
+     }
+});</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p>Hereby this annotation can be
-used in multiple ways and combined with other annotations such as @DefaultValue,
-@WithLoadPolicy, @WithConfig, @WithConfigOperator, @WithPropertyAdapter.</p>
+<p>With Java 8 it&#8217;s even more simpler:</p>
 </div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">ConfiguredItemSupplier&lt;Tenant&gt; configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
+  Tenant::<span class="keyword">new</span>);</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Hereby this annotation can be used in multiple ways and combined with other annotations such as @DefaultValue,
+@WithLoadPolicy, @WithConfigOperator, @WithPropertyConverter.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_minimal_example">Minimal Example</h4>
 <div class="paragraph">
 <p>To illustrate the mechanism below the most simple variant of a configured class is given:</p>
 </div>
@@ -690,6 +740,9 @@ configuration, so future config changes
 </li>
 </ul>
 </div>
+</div>
+<div class="sect3">
+<h4 id="_using_defaultvalue">Using @DefaultValue</h4>
 <div class="paragraph">
 <p>In the next example we explicitly define the property value:</p>
 </div>
@@ -697,20 +750,191 @@ configuration, so future config changes
 <div class="content">
 <pre class="CodeRay highlight"><code data-lang="java">pubic <span class="type">class</span> <span class="class">ConfiguredItem</span>{
 
-  <span class="annotation">@ConfiguredProperty</span>
-  <span class="annotation">@ConfiguredProperty</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">a.b.value</span><span class="delimiter">&quot;</span></span>)
-  <span class="annotation">@configuredProperty</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">a.b.deprecated.value</span><span class="delimiter">&quot;</span></span>)
+  <span class="annotation">@ConfiguredProperty</span>(keys={<span class="string"><span class="delimiter">&quot;</span><span class="content">aValue</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">a.b.value</span><span class="delimiter">&quot;</span></span>,<span class="string"><span class="delimiter">&quot;</span><span class="content">a.b.deprecated.value</span><span class="delimiter">&quot;</span></span>})
   <span class="annotation">@DefaultValue</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">${env:java.version}</span><span class="delimiter">&quot;</span></span>)
   <span class="directive">private</span> <span class="predefined-type">String</span> aValue;
 }</code></pre>
 </div>
 </div>
+</div>
+<div class="sect3">
+<h4 id="_inject_a_dynamicvalue_property">Inject a DynamicValue Property</h4>
+<div class="paragraph">
+<p>Within this example we evaluate a dynamic value. This mechanism allows you to listen for configuration changes and to
+commit new values exactly, when convenient for you.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">pubic <span class="type">class</span> <span class="class">ConfiguredItem</span>{
+
+  <span class="annotation">@ConfiguredProperty</span>(keys={<span class="string"><span class="delimiter">&quot;</span><span class="content">aValue</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">a.b.value</span><span class="delimiter">&quot;</span></span>,<span class="string"><span class="delimiter">&quot;</span><span class="content">a.b.deprecated.value</span><span class="delimiter">&quot;</span></span>})
+  <span class="annotation">@DefaultValue</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">${env:java.version}</span><span class="delimiter">&quot;</span></span>)
+  <span class="directive">private</span> DynamicValue aValue;
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The DynamicValue provides you the following functionality:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">DynamicValue</span>&lt;T&gt; {
+
+    <span class="type">enum</span> UpdatePolicy{
+        IMMEDIATE,
+        EXPLCIT,
+        NEVER,
+        LOG_AND_DISCARD
+    }
+
+    T get();
+    T getNewValue();
+    T evaluateValue();
+    T commitAndGet();
+    <span class="type">void</span> commit();
+    <span class="type">void</span> discard();
+    <span class="type">boolean</span> updateValue();
+
+    <span class="type">void</span> setUpdatePolicy(UpdatePolicy updatePolicy);
+    UpdatePolicy getUpdatePolicy();
+    <span class="type">void</span> addListener(<span class="predefined-type">PropertyChangeListener</span> l);
+    <span class="type">void</span> removeListener(<span class="predefined-type">PropertyChangeListener</span> l);
+
+    <span class="type">boolean</span> isPresent();
+    T orElse(T other);
+    T orElseGet(ConfiguredItemSupplier&lt;? <span class="directive">extends</span> T&gt; other);
+    &lt;X <span class="directive">extends</span> <span class="predefined-type">Throwable</span>&gt; T orElseThrow(ConfiguredItemSupplier&lt;? <span class="directive">extends</span> X&gt; exceptionSupplier) <span class="directive">throws</span> X;
+
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Summarizing this class looks somehow similar to the new Optional class added with Java 8. It provides
+a wrapper class around a configured instance. Additionally this class provides functionality that gives
+active control, to manage a configured value based on a +LoadingPolicy:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>IMMEDEATE means that when the configuration system detects a change on the underlying value, the new value
+is automatically applied without any further notice.</p>
+</li>
+<li>
+<p>EXPLICIT means that a new configuration value is signalled by setting the newValue property. if getNewValue()
+returns a non null value, the new value can be applied by calling commit(). You can always access the newest value,
+hereby implicitly applying it, by accessing it via commitAndGet(). Also it is possible ti ignore a change by calling
+discard().</p>
+</li>
+<li>
+<p>NEVER means the configured value is evaluated once and never updated. All changes are silently discarded.</p>
+</li>
+<li>
+<p>LOG_AND_DISCARD similar to NEVER, but changes are logged before they are discarded.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Summarizing a DynamicValue allows you</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>to reload actively updates of configured values.</p>
+</li>
+<li>
+<p>update implicitly or explicitly all changes on the value.</p>
+</li>
+<li>
+<p>add listeners that observe changes of a certain value.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Dynamic values also allow on-the-fly reevaluation of the value by calling evaluateValue(). Hereby the value of the
+instance is not changed.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_ommitting_injection_using_noconfig">Ommitting Injection using @NoConfig</h4>
+<div class="paragraph">
+<p>Adding the @NoConfig annotation prevents a field or method to be selected (mostly auto-selected) for
+configuration. This is especially useful, if a type is annotated as @ConfiguredType with auto-confiuration
+turned on as follows:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ConfiguredType</span>(autoConfigure=<span class="predefined-constant">true</span>)
+pubic <span class="type">class</span> <span class="class">ConfiguredItem</span>{
+
+  <span class="annotation">@NoConfig</span>
+  <span class="directive">private</span> <span class="directive">transient</span> <span class="type">int</span> sum;
+
+  <span class="directive">private</span> <span class="predefined-type">String</span> a;
+  <span class="directive">private</span> <span class="predefined-type">String</span> b;
+  Private <span class="predefined-type">String</span> c;
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>In this case the fields a,b,c are configured, whereas the field sum is ignored regarding
+configuration.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_adding_custom_operators_using_withconfigoperator">Adding custom operators using @WithConfigOperator</h4>
+<div class="paragraph">
+<p>The @WithConfigOperator annotation allows you define a class of type ConfigOperator, to being applied
+to the final Configuration, BEFORE the value is injected. This can be used for various use cases, e.g.
+filtering or validating the visible properties for a certain use case.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@WithConfigOperator</span>(MyConfigView.class)
+pubic <span class="type">class</span> <span class="class">ConfiguredItem</span>{
+
+  <span class="annotation">@ConfiguredProperty</span>
+  <span class="directive">private</span> <span class="predefined-type">String</span> a;
+
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_adding_custom_property_converters_using_withpropertyconverter">Adding custom property converters using @WithPropertyConverter</h4>
 <div class="paragraph">
-<p>Within this example we evaluate multiple possible keys. Evaluation is aborted if a key could be successfully
-resolved. Hereby the ordering of the annotations define the ordering of resolution, so in the example above
-resolution equals to "aValue", "a.b.value", "a.b.deprecated.value". If no value could be read
-from the configuration, it uses the value from the @DefaultValue annotation. Interesting here
-is that this value is not static, it is evaluated by calling Configuration.evaluateValue(Configuration, String).</p>
+<p>The @WithPropertyConverter annotation allows you to define a class of type PropertyConverter, to be applied
+on a property configured to convert the String value to the expected injected type. This can be used for
+various use cases, e.g. adding custom formats, validation, decryption.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">pubic <span class="type">class</span> <span class="class">ConfiguredItem</span>{
+
+  <span class="annotation">@WithPropertyConverter</span>(MyPropertyConverter.class)
+  <span class="annotation">@ConfiguredProperty</span>
+  <span class="directive">private</span> <span class="predefined-type">String</span> a;
+
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_defining_the_loading_policy_to_be_applied_to_configured_values_using_withloadpolicy">Defining the loading policy to be applied to configured values using @WithLoadPolicy</h4>
+<div class="paragraph">
+<p>The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The LoadPolicy
+enum hereby defines the various loading modes.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@WithLoadPolicy</span>(LoadPolicy.NEVER)
+pubic <span class="type">class</span> <span class="class">BootTimeStableConfig</span>{
+
+  <span class="annotation">@WithPropertyConverter</span>(MyPropertyConverter.class)
+  <span class="annotation">@ConfiguredProperty</span>
+  <span class="directive">private</span> <span class="predefined-type">String</span> a;
+
+}</code></pre>
+</div>
 </div>
 </div>
 </div>
@@ -720,7 +944,7 @@ is that this value is not static, it is
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-04-16 22:34:28 MESZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/mod_jodatime.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/mod_jodatime.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/mod_jodatime.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/mod_jodatime.html Sat Aug 22 15:35:17 2015
@@ -571,7 +571,7 @@ DateTime pit = configuration.get(<span c
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-04-16 22:34:28 MESZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/mod_resolver.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/mod_resolver.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/mod_resolver.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/mod_resolver.html Sat Aug 22 15:35:17 2015
@@ -5,7 +5,7 @@
 <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 1.5.2">
-<title>Untitled</title>
+<title>Apache Tamaya&#8201;&#8212;&#8201;Extension: Resolver</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">
 <style>
 /* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
@@ -502,31 +502,153 @@ table.CodeRay td.code>pre{padding:0}
 </head>
 <body class="article">
 <div id="header">
+<h1>Apache Tamaya&#8201;&#8212;&#8201;Extension: Resolver</h1>
 </div>
 <div id="content">
+<div class="sect1">
+<h2 id="Core">1. Tamaya Resolver (Extension Module)</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_overview">1.1. Overview</h3>
 <div class="paragraph">
-<p>Apache Tamaya&#8201;&#8212;&#8201;Extension: Resolver</p>
+<p>Tamaya Resolver is an extension module. Refer to the <a href="modules.html" title="Apache Tamaya Extension: Resolver">extensions documentation</a> for further details
+about modules.</p>
+</div>
+<div class="paragraph">
+<p>Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (${...} placeholder
+expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents
+cycles to loop endlessly.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_compatibility">1.2. Compatibility</h3>
+<div class="paragraph">
+<p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installation">1.3. Installation</h3>
+<div class="paragraph">
+<p>To benefit from dynamic value resolution you only must add the corresponding dependency to your module:</p>
 </div>
-<div class="exampleblock">
+<div class="listingblock">
 <div class="content">
-<hr>
-<div style="page-break-after: always;"></div>
-<!-- toc disabled -->
-<div style="page-break-after: always;"></div>
-<div style="page-break-after: always;"></div>
-<div id="Core" class="paragraph">
-<p>== Tamaya Events (Extension Module)
-=== Overview</p>
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
+  <span class="tag">&lt;groupId&gt;</span>org.apache.tamaya.ext<span class="tag">&lt;/groupId&gt;</span>
+  <span class="tag">&lt;artifactId&gt;</span>tamaya-resolver<span class="tag">&lt;/artifactId&gt;</span>
+  <span class="tag">&lt;version&gt;</span>{tamayaVersion}<span class="tag">&lt;/version&gt;</span>
+<span class="tag">&lt;/dependency&gt;</span></code></pre>
+</div>
 </div>
 <div class="paragraph">
-<p>Tamaya Resolver is an extension module. Refer to the <a href=":modules.html" title="Apache Tamaya Extension: Resolver">extensions documentation</a> for further details
-about modules.</p>
+<p>The module automatically registers an according PropertyFilter that is automatically called, whenever a value
+is accessed.</p>
+</div>
 </div>
+<div class="sect2">
+<h3 id="_available_resolvers">1.4. Available Resolvers</h3>
 <div class="paragraph">
-<p>Tamaya Events provides an abstraction for events like change events, when configuration has bee changed.</p>
+<p>Currently the module defined the following resolvers:</p>
 </div>
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 1. Available Resolvers</caption>
+<colgroup>
+<col style="width: 33%;">
+<col style="width: 33%;">
+<col style="width: 33%;">
+</colgroup>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Expression</em></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Description</em></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Example</em></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">conf:&lt;configKey&gt;</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Reads another configKey and replaces the expression with the value found.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">conf-ref=${conf:anotherConf.entryKey}</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">resource:&lt;resourceRef&gt;</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Reads a resource from the current classpath and replaces the expression with the given text content.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">cp-ref=${resource:Testresource.txt}</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">file:&lt;fileRef&gt;</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Reads a resource from the current classpath and replaces the expression with the given text content.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">file-ref=${file:c:\myFile.txt}</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">url:&lt;url&gt;</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Reads an URL and replaces the expression with the given text content.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">url-ref=${url:http://www.google.com}</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="sect2">
+<h3 id="_spi_implementing_your_own_resolvers">1.5. SPI: Implementing your own Resolvers</h3>
 <div class="paragraph">
-<p>tbc&#8230;&#8203;</p>
+<p>The module also provides an easy but powerful SPI for adding your own resolver implementations. Basically the
+first and most important thing to do is implementing the ExpressionResolver interface:</p>
+</div>
+<div class="listingblock">
+<div class="title">Implementing a Custom Resolver</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">PwdDecrypter</span> <span class="directive">implements</span> ExpressionResolver {
+
+  <span class="annotation">@Override</span>
+  <span class="directive">public</span> <span class="predefined-type">String</span> getResolverPrefix(){
+     <span class="keyword">return</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">decrypt:</span><span class="delimiter">&quot;</span></span>;
+  }
+
+  <span class="annotation">@Override</span>
+  <span class="directive">public</span> <span class="predefined-type">String</span> evaluate(<span class="predefined-type">String</span> expression){
+    <span class="keyword">return</span> decrypt(expression);
+  }
+
+  <span class="directive">private</span> <span class="predefined-type">String</span> decrypt(<span class="predefined-type">String</span> s){
+    ...
+  }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Basically that is all you must do, after having registered the class with the ServiceLoader it will be found
+and loaded by the implementation. With that all expressions that start with the given prefix are passed to the
+resolver, so all the following expressions will be sent to the implementation:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="listing">blabla ${decrypt:myname}
+blabla ${decrypt:myname} foo blabla ${decrypt:myname}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Hereby evaluation is repeasted until no further change of values could be detetced. In case of a endless loop
+the evaluation is broken after a (configurable) number of cycles.</p>
+</div>
+<div class="paragraph">
+<p>Under the hood instances of ExpressionResolver are managed by an implementation of the ExpressionEvaluator
+interface:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">ExpressionEvaluator</span> {
+    <span class="comment">/**
+     * Evaluates the current expression.
+     * @param key the key, not null.
+     * @param value the value to be filtered/evaluated.
+     * @return the filtered/evaluated value, including null.
+     */</span>
+    <span class="predefined-type">String</span> evaluateExpression(<span class="predefined-type">String</span> key, <span class="predefined-type">String</span> value);
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Implementing and registering this interface gives you full control, but in most cases yhou should be fine with
+the default implementation in place.</p>
+</div>
 </div>
 </div>
 </div>
@@ -534,7 +656,7 @@ about modules.</p>
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-03-03 15:59:42 MEZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/mod_resources.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/mod_resources.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/mod_resources.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/mod_resources.html Sat Aug 22 15:35:17 2015
@@ -5,7 +5,7 @@
 <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 1.5.2">
-<title>Untitled</title>
+<title>Apache Tamaya&#8201;&#8212;&#8201;Extension: Resources</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">
 <style>
 /* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
@@ -502,24 +502,25 @@ table.CodeRay td.code>pre{padding:0}
 </head>
 <body class="article">
 <div id="header">
+<h1>Apache Tamaya&#8201;&#8212;&#8201;Extension: Resources</h1>
 </div>
 <div id="content">
-<div class="paragraph">
-<p>Apache Tamaya&#8201;&#8212;&#8201;Extension: Resources</p>
-</div>
-<div class="exampleblock">
-<div class="content">
+<div id="preamble">
+<div class="sectionbody">
 <hr>
 <div style="page-break-after: always;"></div>
 <!-- toc disabled -->
 <div style="page-break-after: always;"></div>
 <div style="page-break-after: always;"></div>
-<div id="Core" class="paragraph">
-<p>== Tamaya Resources (Extension Module)
-=== Overview</p>
 </div>
+</div>
+<div class="sect1">
+<h2 id="Core">Tamaya Resources (Extension Module)</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_overview">Overview</h3>
 <div class="paragraph">
-<p>Tamaya Resources is an extension module. Refer to the <a href=":modules.html" title="Apache Tamaya Extension: Resources">extensions documentation</a> for further details
+<p>Tamaya Resources is an extension module. Refer to the <a href="modules.html" title="Apache Tamaya Extension: Resources">extensions documentation</a> for further details
 about modules.</p>
 </div>
 <div class="paragraph">
@@ -531,20 +532,25 @@ ant-styled resource patterns. To use thi
 <pre class="CodeRay highlight"><code data-lang="listing">&lt;dependency&gt;
   &lt;grooupId&gt;org.apache.tamaya.ext&lt;/groupId&gt;
   &lt;artifactId&gt;tamaya-resources&lt;/artifactId&gt;
-  &lt;version&gt;CURRENT_VERSION&lt;/version&gt;
+  &lt;version&gt;{tamayaVersion}&lt;/version&gt;
 &lt;/dependency&gt;</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p>The module&#8217;s main entry point is the singleton class org.apache.tamaya.resource.Resources. This class provides
-access to a ResourceResolver instance:</p>
+<p>The module&#8217;s main entry point is the singleton class org.apache.tamaya.resource.ConfigResources. This class
+provides access to a ResourceResolver instance:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">ResourceResolver resolver = ConfigResources.getResourceResolver();</code></pre>
+</div>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">ResourceResolver</span> {
-    <span class="keyword">default</span> <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">Collection</span>&lt;<span class="predefined-type">String</span>&gt; expressions) {...}
-    <span class="keyword">default</span> <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">String</span>... expressions) {...}
-    <span class="keyword">default</span> <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">ClassLoader</span> classLoader, <span class="predefined-type">String</span>... expressions){...}
+    <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">Collection</span>&lt;<span class="predefined-type">String</span>&gt; expressions) {...}
+    <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">String</span>... expressions) {...}
+    <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">ClassLoader</span> classLoader, <span class="predefined-type">String</span>... expressions){...}
     <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">URL</span>&gt; getResources(<span class="predefined-type">ClassLoader</span> classLoader, <span class="predefined-type">Collection</span>&lt;<span class="predefined-type">String</span>&gt; expressions);
 }</code></pre>
 </div>
@@ -554,10 +560,27 @@ access to a ResourceResolver instance:</
 current classpath the target ClassLoader to be used can be passed additionally.</p>
 </div>
 <div class="paragraph">
-<p>=== Valid Expression Examples</p>
+<p>The default implementation provides resource resolution mechanism similar to the functionality offered by Spring.
+So by default resources can be looked up</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>from files</p>
+</li>
+<li>
+<p>from the classpath</p>
+</li>
+<li>
+<p>optionally ant-styled expressions can be used.</p>
+</li>
+</ul>
 </div>
+</div>
+<div class="sect2">
+<h3 id="_valid_expression_examples">Valid Expression Examples</h3>
 <div class="paragraph">
-<p>There are numerous ways how a resource pattern can be defined, Following the most important variants
+<p>There are numerous ways how a resource pattern can be defined. Following the most important variants
 are listed:</p>
 </div>
 <div class="listingblock">
@@ -591,9 +614,9 @@ myroot/b*/b?/*.file</code></pre>
 in the classpath. This can be used to implement PropertySourceProvider implementations that are based on
 corresponding resource path patterns instead of concrete files.</p>
 </div>
-<div class="paragraph">
-<p>=== Overall Usage Example</p>
 </div>
+<div class="sect2">
+<h3 id="_overall_usage_example">Overall Usage Example</h3>
 <div class="paragraph">
 <p>Given the functionality we can easily implement a PropertySourceProvider that reads all files from a classpath
 location, hereby traversing down all folders:</p>
@@ -650,12 +673,25 @@ location, hereby traversing down all fol
 </div>
 </div>
 </div>
+<div class="sect2">
+<h3 id="_spi">SPI</h3>
+<div class="paragraph">
+<p>The ResourceResolver that is returned by the ConfigResources singleton is determined by the
+current ServiceContext, by default you can replace the default implementation by registering an
+alternate implemenetation with an overriding @Priority annotation added using the ServiceLoader.</p>
+</div>
+<div class="paragraph">
+<p>Additionally a BaseResourceResolver class can be used to reduce the amount of code to be written
+on your own.</p>
+</div>
+</div>
+</div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
 Version 0.1.1<br>
-Last updated 2015-03-03 17:28:30 MEZ
+Last updated 2015-08-04 21:27:21 MESZ
 </div>
 </div>
 </body>

Modified: incubator/tamaya/site/trunk/content/documentation/modules.html
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation/modules.html?rev=1697094&r1=1697093&r2=1697094&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/documentation/modules.html (original)
+++ incubator/tamaya/site/trunk/content/documentation/modules.html Sat Aug 22 15:35:17 2015
@@ -507,7 +507,7 @@ table.CodeRay td.code>pre{padding:0}
 <div class="details">
 <span id="author" class="author">Anatole Tresch</span><br>
 <span id="email" class="email">&lt;<a href="mailto:anatole@apache.org" title="Apache Tamaya Extension Modules">anatole@apache.org</a>&gt;</span><br>
-<span id="revnumber">version 0.1-SNAPSHOT,</span>
+<span id="revnumber">version 0.1-incubating,</span>
 <span id="revdate">March 2015</span>
 <br><span id="revremark">Incubator</span>
 </div>
@@ -525,13 +525,41 @@ table.CodeRay td.code>pre{padding:0}
 <h2 id="_mature_extensions">1. Mature Extensions</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>N/A</p>
+<p>Mature extensions have a stable API and SPI, similar to the API and Implementations provided.</p>
 </div>
+<table class="tableblock frame-1 grid-all spread">
+<colgroup>
+<col style="width: 33%;">
+<col style="width: 33%;">
+<col style="width: 33%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top"><em>Artifact</em></th>
+<th class="tableblock halign-left valign-top"><em>Description</em></th>
+<th class="tableblock halign-left valign-top"><em>Links</em></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">N/A: currently no extensions have reached that maturity level.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+</tr>
+</tbody>
+</table>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_draft_extensions">2. Draft Extensions</h2>
 <div class="sectionbody">
+<div class="paragraph">
+<p>Extensions in <em>draft state</em> 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.</p>
+</div>
+<div class="paragraph">
+<p>NOTE All extensions, despite the <em>tamaya-builder</em> module, currently run on Java 7 as well as on Java 8.</p>
+</div>
 <table class="tableblock frame-1 grid-all spread">
 <colgroup>
 <col style="width: 33%;">
@@ -547,6 +575,11 @@ table.CodeRay td.code>pre{padding:0}
 </thead>
 <tbody>
 <tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.apache.tamaya.ext:tamaya-builder</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Provides a fluent-style builder for configurations</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="mod_builder.html">Documentation</a></p></td>
+</tr>
+<tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.apache.tamaya.ext:tamaya-resources</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Provides ant-style resource path resolution</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="mod_resources.html">Documentation</a></p></td>
@@ -571,6 +604,11 @@ table.CodeRay td.code>pre{padding:0}
 <td class="tableblock halign-left valign-top"><p class="tableblock">Provides configuration injection services and congiruation template support.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="mod_injection.html">Documentation</a></p></td>
 </tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.apache.tamaya.ext:tamaya-json</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Provides format support for JSON based configuration.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="mode_json.html">Documentation</a></p></td>
+</tr>
 </tbody>
 </table>
 </div>
@@ -579,15 +617,37 @@ table.CodeRay td.code>pre{padding:0}
 <h2 id="_extensions_in_experimental_stage">3. Extensions in Experimental Stage</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>tbd</p>
+<p>Extensions in <em>experimental mode</em> 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 <em>draft</em> state.</p>
 </div>
+<table class="tableblock frame-1 grid-all spread">
+<colgroup>
+<col style="width: 33%;">
+<col style="width: 33%;">
+<col style="width: 33%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top"><em>Artifact</em></th>
+<th class="tableblock halign-left valign-top"><em>Description</em></th>
+<th class="tableblock halign-left valign-top"><em>Links</em></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.apache.tamaya.ext:tamaya-jodatime</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Provides support for JodaTime.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="mod_jodatime.html">Documentation</a></p></td>
+</tr>
+</tbody>
+</table>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
-Version 0.1-SNAPSHOT<br>
-Last updated 2015-03-03 17:53:33 MEZ
+Version 0.1-incubating<br>
+Last updated 2015-08-06 07:37:59 MESZ
 </div>
 </div>
 </body>



Mime
View raw message