Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@tamaya.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: anatole@apache.org
To: commits@tamaya.incubator.apache.org
Date: Sun, 26 Feb 2017 23:04:48 -0000
Message-Id: <e550c31e90d6439e8f7216deffc04972@git.apache.org>
Subject: [1/4] incubator-tamaya-site git commit: Improved/updated docs.
archived-at: Sun, 26 Feb 2017 23:05:35 -0000

Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master 4de2484de -> 98574522d


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

Branch: refs/heads/master
Commit: 91a1b450065bf12cc2314b181e5475ab8519c469
Parents: 2762668
Author: anatole <anatole@apache.org>
Authored: Tue Feb 14 23:45:19 2017 +0100
Committer: anatole <anatole@apache.org>
Committed: Tue Feb 14 23:45:19 2017 +0100

----------------------------------------------------------------------
 .../documentation/extensions/mod_features.adoc  | 87 +++++++++++++++++
 content/documentation/extensions/mod_jndi.adoc  | 65 +++++++++++++
 .../extensions/mod_mutable_config.adoc          | 98 +++++++-------------
 .../documentation/extensions/mod_optional.adoc  | 22 +++--
 content/documentation/extensions/mod_osgi.adoc  | 18 ++--
 .../documentation/extensions/mod_remote.adoc    | 35 +++----
 .../documentation/extensions/mod_resolver.adoc  | 14 ++-
 .../documentation/extensions/mod_resources.adoc | 21 ++++-
 .../documentation/extensions/mod_server.adoc    | 21 +++--
 .../extensions/mod_spi-support.adoc             |  3 +-
 .../documentation/extensions/mod_spring.adoc    |  6 +-
 .../extensions/mod_usagetracker.adoc            |  8 +-
 .../extensions/mod_validation.adoc              |  6 +-
 content/documentation/extensions/mod_yaml.adoc  |  7 +-
 14 files changed, 286 insertions(+), 125 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_features.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_features.adoc b/content/documentation/extensions/mod_features.adoc
new file mode 100644
index 0000000..d97da3a
--- /dev/null
+++ b/content/documentation/extensions/mod_features.adoc
@@ -0,0 +1,87 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Features Check
+
+toc::[]
+
+
+[[Features]]
+== Tamaya Features Check (Extension Module)
+Tamaya _Features_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
+
+=== What functionality this module provides ?
+
+Tamaya _Features_ provides a simple +Features+ singleton that allows to check
+which Tamaya Extensions are currently on the classpath.
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To use Tamaya _Features_ you only must add the corresponding dependency to
+your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+  <groupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-features</artifactId>
+  <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Functionality Provided
+
+Main artifact is the +Features+ singleton, which provides various static methods
+to check, which Tamaya extensions are currently loaded.
+
+[source, java]
+-----------------------------------------------
+public final class Features {
+
+    private Features(){}
+
+    public static boolean eventsAvailable();
+    public static boolean formatsAvailable();
+    public static boolean tamayaCoreAvailable();
+    public static boolean injectionAvailable();
+    public static boolean injectionCDIAvailable();
+    public static boolean mutableConfigAvailable();
+    public static boolean optionalAvailable();
+    public static boolean resolverAvailable();
+    public static boolean resourcesAvailable();
+    public static boolean spiSupportAvailable();
+    public static boolean filterSupportAvailable();
+    public static boolean springAvailable();
+    public static boolean jndiAvailable();
+
+    public static boolean extSpringCoreAvailable();
+    public static boolean extJndiAvailable();
+    public static boolean extOSGIAvailable();
+
+    public static boolean checkClassIsLoadable(String classname);
+}
+-----------------------------------------------
+
+* +eventsAvailable();+ checks for the link:mod_events.html[_tamaya_events_] module.
+* +formatsAvailable();+ checks for the link:mod_formats.html[_tamaya_formats_] module.
+* +tamayaCoreAvailable();+ checks if the link:core.html[_Tamaya core_] implementation is loaded.
+* +injectionAvailable();+ checks for the link:mod_injection.html[_tamaya_injection_] SE module.
+* +injectionCDIAvailable();+ checks for the link:mod_cdi.html[_tamaya CDI_] modules.
+* +mutableConfigAvailable();+ checks for the link:mod_mutableconfig.html[_tamaya_mutableconfig_] module.
+* +optionalAvailable();+ checks for the link:mod_optional.html[_tamaya_optional_] module.
+* +resolverAvailable();+ checks for the link:mod_resolver.html[_tamaya_resolver_] module.
+* +resourcesAvailable();+ checks for the link:mod_reources.html[_tamaya_resources_] module.
+* +spiSupportAvailable();+ checks for the link:mod_spisupport.html[_tamaya_spisupport_] module.
+* +filterSupportAvailable();+ checks for the link:mod_filter.html[_tamaya_filter_] module.
+* +springAvailable();+ checks for the link:mod_spring.html[_tamaya_spring_] module.
+* +jndiAvailable();+ checks for the link:mod_jndi.html[_tamaya_jndi_] module.
+* +extJndiAvailable();+ checks if creation of a new `InitialContext` is successful.
+* +extSpringCoreAvailable();+ checks if Spring Core is on the classpath.
+* +extOSGIAvailable();+ checks the OSGI framework is on the classpath.
+* Finally +checkClassIsLoaded(String)+ tries to load a class. If it fails, `false` is returned.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_jndi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_jndi.adoc b/content/documentation/extensions/mod_jndi.adoc
new file mode 100644
index 0000000..0bba306
--- /dev/null
+++ b/content/documentation/extensions/mod_jndi.adoc
@@ -0,0 +1,65 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Integration with JNDI
+
+toc::[]
+
+
+[[JNDI]]
+== Integration with JNDI (Extension Module)
+Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
+
+=== What functionality this module provides ?
+
+Tamaya _JNDI_ provides a simple +PropertySource+ that reads values from a
+JNDI context.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To use _jndi_ as a configuration backend you only must add the corresponding dependency to
+your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+  <groupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-jndi</artifactId>
+  <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Functionality Provided
+
+Main artifact is the +JNDIPropertySource+ class, which implements a
+property source based on a JNDI context:
+
+[source, java]
+-----------------------------------------------
+public class JNDIPropertySource extends BasePropertySource {
+
+    public JNDIPropertySource(String name, Context context);
+    public JNDIPropertySource(String name) throws NamingException;
+    public JNDIPropertySource() throws NamingException;
+
+    public void setScannable(boolean scannable);
+
+    [...]
+}
+-----------------------------------------------
+
+By default the property source is _non scannable_, so a call the `getProperties()`
+will return an empty map instance. After calling `setScannable(true);` a call to
+`getProperties()` will return a String representation of the JNDI tree. Hereby
+leaves of the tree are converted using `String.valueOf(leaveObject)`.
+
+You can extend this class or manually instantiate it, e.g. as part of a
++PropertySourceProvider+. If no `Context` is passed explicitly, a new
++InitialContext+ is created, without any environment parameters set.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_mutable_config.adoc b/content/documentation/extensions/mod_mutable_config.adoc
index 6e596ca..e8a932b 100644
--- a/content/documentation/extensions/mod_mutable_config.adoc
+++ b/content/documentation/extensions/mod_mutable_config.adoc
@@ -11,16 +11,19 @@ toc::[]
 
 Tamaya _Mutable Configuration_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
 Tamaya +Configuration+ by default is read-only, which covers must of the use cases. But there are many legit scenarios
-where configuration should be written back to some backend systems or the local file system. This module adds this
+where configuration should be written back to backend systems or the local file system. This module adds this
 functionality.
 
+
 === Compatibility
 
 The module is based on Java 7, so it can be used with Java 7 and beyond.
 
+
 === Installation
 
 To benefit from configuration mutability support you only must add the corresponding dependency to your module:
@@ -34,19 +37,21 @@ To benefit from configuration mutability support you only must add the correspon
 </dependency>
 -----------------------------------------------
 
+
 === Core Architecture
 
 ==== Accessing MutableConfiguration
 
 The core of the module is the +MutableConfigurationProvider+ singleton, which provides access to +MutableConfiguration+
 instance, which extends +Configuration+. This interface adds additional methods to add/update or remove property values.
-Hereby changes applied are managed in a transaction like context, called +ConfigChangeContext+. Each context defines
+Hereby each +MutableConfiguration+ manages a transaction like context, which includes
 a UUID that identifes a change.
-Backends for writing changes applied are of type +MutablePropertySource+, similarly extending the +PropertySource+
-SPI with methods for writing changes back. Registrations and ordering policies are like with ordinary property sources,
-with one important difference. Mutable property source can be targeted by write operations.
+Backends for writing changes applied umst implement +MutablePropertySource+, which extends +PropertySource+.
+Registrations and ordering policies are exact the same as with ordinary property sources, but
+mutable property sources can be targeted by config write operations.
 
-The example below shows how a +MutableConfiguration+ can be obtained the simplest way:
+The example below shows how a +MutableConfiguration+ can be obtained ,values added, removed and
+finally changes written back to the backend:
 
 [source,java]
 .Accessing and changing configuration
@@ -59,7 +64,7 @@ config.put("newKey", "newValue")
       .store();
 --------------------------------------------
 
-In the above scenario we use the overall system's configuration as the backend to be used.
+In the above scenario we use the system's _default_ configuration as the backend to be used.
 We can also pass any +Configuration+ to render it into a mutable instance, e.g.
 
 [source,java]
@@ -71,11 +76,12 @@ MutableConfiguration config = MutableConfigurationProvider
 --------------------------------------------
 
 NOTE: If a configuration does not contain any +MutablePropertySource+ instances,
-      a +MutableConfiguration+ built from it will not be able to accept any changes.
+      a +ConfigurationException+ is thrown since it would not be able to accept
+      any changes.
 
 
-Following you see the options how to create a +MutableConfiguration+ using the
-+MutableConfigurationProvider+ singleton:
+Following we show the possible methods you can use to create a +MutableConfiguration+.
+We will show in the following sections more details on the options provided...
 
 [source, java]
 ---------------------------------------------
@@ -95,7 +101,7 @@ public final class MutableConfigurationProvider {
 }
 ---------------------------------------------
 
-Hereby +MutableConfiguration+ is defined as follows:
+As we have not yet shown it, +MutableConfiguration+ is defined as follows:
 
 [source, java]
 ---------------------------------------------
@@ -115,18 +121,18 @@ public interface MutableConfiguration extends Configuration {
 ---------------------------------------------
 
 
-==== Targeting the right MutablePropertySources
+===== Targeting specific MutablePropertySources
 
-A +Configuration+ may have multiple +MutablePropertySource+ instances present. These are members of Tamaya's oredered list of
+A +Configuration+ may have multiple +MutablePropertySource+ instances present. These are members of Tamaya's ordered list of
 +PropertySources+ to evaluate the configuration. Nevertheless writing back changes requires additional aspects to
 be considered:
-* Should changes being written back to all mutable property sources? Or should a key that could be added or removed
-  on a more significant instance not be written/removed on less significant property source instances?
-* Should a change be applied only to a specific mutable property source, regardless its position in the
+* Should changes written target all mutable property sources? Or should a change only
+  target the most significant instance (hereby not writing the change to less significant property sources)?
+* Or should a change be applied only to specific mutable property source(s), regardless its position in the
   processing chain?
 
-Therefore a +ChangePropagationPolicy+ can be set on a +MutableConfiguration+ instance, which allows to control
-this aspect:
+Therefore a _default_ +ChangePropagationPolicy+ can be applied on a +MutableConfiguration+ instance, which allows to
+control this aspect:
 
 [source,java]
 .Explicitly passing the backing configuration
@@ -134,7 +140,7 @@ this aspect:
 public interface ChangePropagationPolicy {
     /**
      * Method being called when a multiple key/value pairs are added or updated.
-     * @param propertySources the property sources, including readable property sources of the current configuration,
+     * @param propertySources all property sources, including read-only property sources, of the current configuration,
      *                        never null.
      * @param configChange the configuration change, not null.
      */
@@ -142,10 +148,11 @@ public interface ChangePropagationPolicy {
 }
 --------------------------------------------
 
-By default, changes are applied to all registered +MutablePropertySources+ similarly.
-
+By default, changes are applied to all registered +MutablePropertySource+ instances
+similarly.
 
-Also the +MutableConfigurationProvider+ provides access to the most commonly used change propagation policies:
+The +MutableConfigurationProvider+ singleton also provides the most common
+change propagation policy implementations:
 
 [source, java]
 ---------------------------------------------
@@ -177,17 +184,7 @@ be sometimes a bit tricky to be predicted, since it depends on several aspects:
 . can the changes applied be committed at all?
 
 So it is part of your application configuration design to clearly define, which property sources may be read-only, which
-may be mutable, how overriding should work and to which backends finally any changes should be written back. Nevertheless
-changing or adding value is very easy:
-
-[source,java]
-.Changing a configuration
---------------------------------------------
-MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
-config.put("newKey", "newValue");
-config.remove("mycluster.myapp.myKey");
-config.store();
---------------------------------------------
+may be mutable, how overriding should work and to which backends finally any changes should be written back.
 
 
 === Configuration Changes
@@ -203,8 +200,8 @@ several ways, e.g. by:
 
 === Supported Backends
 
-Multiple backends are supported. E.g. the _etcd_ integration module of Tamaya also registers
-corresponding SPI implementations/backends. By default this module comes with
+Multiple backends are supported. E.g. _tamaya-etcd_ also registers
+corresponding SPI implementations/backends. This module comes with
 the following +MutablePropertySource+ implementations:
 
 * +MutablePropertySource+ resources, targeting local +.properties+ files, using the +java.util.Properties+
@@ -212,37 +209,6 @@ the following +MutablePropertySource+ implementations:
 * +MutableXmlPropertySource+ resources, targeting local +.xml+ property files, using the +java.util.Properties+
   XML format.
 
-==== Refreshable Property Sources
-
-Somehow similar to configuration changes applied explicitly is the case, where values of underlying
-configuration backends change and must be reflected in the new configuration tree. Examples are:
-
-* Configuration files being edited, added or removed.
-* Changes on remote servers like etcd, consul
-* etc.
-
-For having a common API for refreshable items a +Refreshable+ interface is defined:
-
-[source,java]
-.Refreshable interface
---------------------------------------------
-/**
- * Interface to be implemented by items that can be refreshed. By default
- * these are property sources, but more types may be supported at a later
- * point in time.
- */
-public interface Refreshable {
-
-    /**
-     * Refreshes the item by reloading its internal state.
-     */
-    void refresh();
-
-}
---------------------------------------------
-
-
-==== Refreshable Property Sources
 
 === SPIs
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_optional.adoc b/content/documentation/extensions/mod_optional.adoc
index f7fcbbd..1dd6065 100644
--- a/content/documentation/extensions/mod_optional.adoc
+++ b/content/documentation/extensions/mod_optional.adoc
@@ -13,12 +13,13 @@ Tamaya _Optional_ is an extension module. Refer to the link:../extensions.html[e
 
 === What functionality this module provides ?
 
-Tamaya _Optional_ provides contains three types only. It is for projects that want to benefit from Tamaya
-configuration optionally only. E.g. doing an OSS project you can declare to support configuration with Tamaya as
-an optional extension. This module can be added as a hard dependency to your code, hereby adding only three artofacts.
-It automatically checks the availability of Tamaya on the classpath and only if available tries to access it for
-configuration evaluation. Additionally an EvaluationPolicy lets you define the precedence of configured values
-(yours, or Tamaya ones if present).
+Tamaya _Optional_  is for projects that want to benefit from Tamaya configuration optionally only.
+E.g. doing an OSS project you can declare to support configuration with Tamaya as
+an optional extension. This module can be added as a hard dependency to your code, hereby adding only
+three artifacts. The _optional_ module automatically checks the availability of Tamaya on the
+classpath and only if available it tries to access it for configuration evaluation.
+Additionally an +EvaluationPolicy+ lets you define the precedence of configured values
+(yours, or Tamaya ones, if present).
 
 
 === Compatibility
@@ -28,7 +29,7 @@ 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:
+To use Tamaya _optional_ you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -42,8 +43,11 @@ To benefit from configuration builder support you only must add the correspondin
 
 === Reading configuration using the Tamaya Optional Module
 
-Tamaya _Optional_ allows reading configuration with a small subset of functionality only. For extended of full
-featured config please consider using the Apache Tamaya as a full configuration backend.
+Tamaya _Optional_ allows reading configuration with a small subset of functionality only. For more
+ advanced use cases consider using the Apache Tamaya as your main configuration API. When
+ creating your +OptionalConfiguration+ instance you also pass the logic to access a value
+ with your own configuration logic. Tamaya Optional will delegate to your logic as needed
+ (depending on the `EvaluationPolicy`).
 
 [source, java]
 -----------------------------------------------

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_osgi.adoc b/content/documentation/extensions/mod_osgi.adoc
index aa8ebfe..34c30bc 100644
--- a/content/documentation/extensions/mod_osgi.adoc
+++ b/content/documentation/extensions/mod_osgi.adoc
@@ -11,26 +11,28 @@ toc::[]
 
 Tamaya _OSGI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
-Tamaya _OSGI_ provides also support for integration with OSGI. Hereby Tamaya implements the OSGI +ConfigAdmin+ service,
+Tamaya _OSGI_ provides support for integration with OSGI. Hereby Tamaya implements the OSGI +ConfigAdmin+ service,
 which is the OSGI basic component providing configuration. Tamaya by default overrides the OSGI default configuration
-but can also be configured to extend it.
+but can also be configured to extend it instead.
+
 
 === Compatibility
 
 All module described are based on Java 7, so it will run on Java 7 and beyond.
-The modules are built against OSGI Compendium version 5.0. Tamaya OSGI support is tested against the following OSGI
-runtimes:
+The modules are built against *OSGI Compendium version 5.0*. Tamaya OSGI support
+is tested against the following OSGI runtimes:
 
-* Apache Karaf, version 4.0.7
-* Apache Felix, version 5.6.1.
+* Apache Karaf, version 4.0.7 (tbc)
+* Apache Felix, version 5.6.1
 * tbd: Eclipse Equinox, version x.x.x.
 
 === Installation
 
-To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime
-environment:
+To benefit from Tamaya in an OSGI context you must deploy at least the following modules to
+your OSGI runtime environment:
 
 [source, listing]
 -----------------------------------------------

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_remote.adoc b/content/documentation/extensions/mod_remote.adoc
index 53e4c49..e539935 100644
--- a/content/documentation/extensions/mod_remote.adoc
+++ b/content/documentation/extensions/mod_remote.adoc
@@ -11,19 +11,22 @@ toc::[]
 
 Tamaya _Remote_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
 Tamaya _Remote_ provides support for reading configuration from remote resources. It provides
-especially out-of-the-box support for reading scoped configuration from a configuration server as
-provided with the _Tamaya server module_ .
+out-of-the-box support for reading scoped configuration from a Tamaya configuration server as
+provided with the Tamaya _server_ module .
+
 
 === 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:
+To use remote support you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -37,7 +40,7 @@ To benefit from configuration builder support you only must add the correspondin
 
 === Reading Remote configuration from a Tamaya Configuration Server
 
-The remote module allows reading JSON formatted configuration as provided by the _Tamaya server extension_ . The JSON
+The remote module allows reading JSON formatted configuration as provided by the Tamaya _server_ extension . The JSON
 format used looks as follows:
 
 [source, json]
@@ -64,35 +67,27 @@ format used looks as follows:
   "sun.jnu.encoding": "Cp1252",
   "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
   "sun.os.patch.level": "",
-  "{meta}class": "org.apache.tamaya.functions.FilteredConfiguration",
-  "{meta}info.filter": "java.v,sun",
-  "{meta}info.format": "application/json",
-  "{meta}info.timestamp": "1441463200571",
-  "{meta}timestamp": "1441463200571",
-  "{meta}type": "Configuration"
+  "_class": "org.apache.tamaya.functions.FilteredConfiguration",
+  "_info.filter": "java.v,sun",
+  "_info.format": "application/json",
+  "_info.timestamp": "1441463200571",
+  "_timestamp": "1441463200571",
+  "_type": "Configuration"
 }
 -----------------------------------------------
 
 Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with
-+{xxx}+ to identify meta-data entries, but this is not a required precondition.
++'_'+ to identify meta-data entries, but this is not a required precondition.
 
 Finally such a remote configuration can be easily integrated by inheriting from the provided base
 class. Hereby a default ordinal must be defined and the +protected Collection<URL> getAccessURLs()+
 method must be implemented to define the URL from where the configuration should be accessible. Hereby
 multiple URLs can be provided, which are accesed in order as provided by the collection's iterator. The
-first URL that is successfully accessed determines the configuration read and imported into the
-+PropertySource+.
+first accessible URL determines the configuration read.
 
 [source, java]
 -----------------------------------------------
 public class RemotePropertySource extends BaseRemotePropertySource{
-    /** Current remote property source default ordinal. */
-    private static final int REMOTE_ORDINAL = 15000;
-
-    @Override
-    public int getDefaultOrdinal(){
-        return REMOTE_ORDINAL;
-    }
 
     @Override
     protected Collection<URL> getAccessURLs() {

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_resolver.adoc b/content/documentation/extensions/mod_resolver.adoc
index f66e3b6..a3db1bc 100644
--- a/content/documentation/extensions/mod_resolver.adoc
+++ b/content/documentation/extensions/mod_resolver.adoc
@@ -8,20 +8,22 @@
 
 Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
-Tamaya _Resolver_ is an extension module. Refer to the
-link:../extensions.html[extensions documentation]
+Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation]
 for further details about modules.
 
 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.
 
+
 === Compatibility
 
 The module is based on Java 7, so it can be used with Java 7 and beyond.
 
+
 === Installation
 
 To benefit from dynamic value resolution you only must add the corresponding dependency to your module:
@@ -38,9 +40,10 @@ To benefit from dynamic value resolution you only must add the corresponding dep
 The module automatically registers an according +PropertyFilter+ that is automatically called, whenever a value
 is accessed.
 
+
 === Available Resolvers
 
-Currently the module defined the following resolvers:
+Currently the module defines the following resolvers:
 
 .Available Resolvers
 [cols="<.1,<.2,<.1"]
@@ -67,9 +70,10 @@ Currently the module defined the following resolvers:
 
 |=======
 
+
 === SPI: Implementing your own Resolvers
 
-The module also provides an easy but powerful SPI for adding your own resolver implementations. Basically the
+The module also provides a small but powerful SPI for adding your own resolver implementations. Basically the
 first and most important thing to do is implementing the +ExpressionResolver+ interface:
 
 .Implementing a Custom Resolver
@@ -123,5 +127,5 @@ public interface ExpressionEvaluator {
 }
 -----------------------------------------------
 
-Implementing and registering this interface gives you full control, but in most cases yhou should be fine with
+Implementing and registering this interface gives you full control, but in most cases you should be fine with
 the default implementation in place.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_resources.adoc b/content/documentation/extensions/mod_resources.adoc
index 3468246..6c26cdd 100644
--- a/content/documentation/extensions/mod_resources.adoc
+++ b/content/documentation/extensions/mod_resources.adoc
@@ -8,10 +8,21 @@
 
 Tamaya _Resources_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
-Tamaya _Resources_ defines some additional tools to locate resources in your classpath or file system based on descriptive
-ant-styled resource patterns. To use this module add the following dependency:
+Tamaya _Resources_ defines some additional tools to locate resources in your classpath or file system based on
+descriptive ant-styled resource patterns.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+
+=== Installation
+
+To use this module add the following dependency:
 
 [source, listing, subs="verbatim,attributes"]
 -----------------------------------------------
@@ -22,6 +33,9 @@ ant-styled resource patterns. To use this module add the following dependency:
 </dependency>
 -----------------------------------------------
 
+
+=== Usage
+
 The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class
 provides access to a +ResourceResolver+ instance:
 
@@ -50,7 +64,8 @@ So by default resources can be looked up
 * from the classpath
 * optionally ant-styled expressions can be used.
 
-=== Valid Expression Examples
+
+=== Examples
 
 There are numerous ways how a resource pattern can be defined. Following the most important variants
 are listed:

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_server.adoc b/content/documentation/extensions/mod_server.adoc
index 7f1c8e8..4c15704 100644
--- a/content/documentation/extensions/mod_server.adoc
+++ b/content/documentation/extensions/mod_server.adoc
@@ -11,6 +11,7 @@ toc::[]
 
 Tamaya _Server_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
 The Tamaya _Server_ module provides support for providing scoped configuration using a http server serving JSON formatted
@@ -21,6 +22,7 @@ configuration properties.
 
 The module is based on Java 7, so it will not run on Java 7 and beyond.
 
+
 === Installation
 
 To benefit from configuration server support you only must add the corresponding dependency to your module:
@@ -34,6 +36,7 @@ To benefit from configuration server support you only must add the corresponding
 </dependency>
 -----------------------------------------------
 
+
 === Providing configuration using the Tamaya Built-in Configuration Server
 
 THe most simple way for providing onfiguration ist to start the internal server:
@@ -101,6 +104,7 @@ where
   params          = the optional parameters (scope, scopeId and format)
 ----------------------------------------------------------
 
+
 ==== Formatting used by Default
 
 The server module formats the configuration returned by default in thw following variants:
@@ -244,12 +248,12 @@ Configuration:
   sun.jnu.encoding: Cp1252,
   sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
   sun.os.patch.level: ,
-  {meta}class: org.apache.tamaya.functions.FilteredConfiguration,
-  {meta}info.filter: java.v,sun,
-  {meta}info.format: text/html,
-  {meta}info.timestamp: 1441463459653,
-  {meta}timestamp: 1441463459654,
-  {meta}type: Configuration
+  _class: org.apache.tamaya.functions.FilteredConfiguration,
+  _info.filter: java.v,sun,
+  _info.format: text/html,
+  _info.timestamp: 1441463459653,
+  _timestamp: 1441463459654,
+  _type: Configuration
 
 </pre>
 </body>
@@ -294,9 +298,10 @@ have to add the following to +META-INF/services/org.apache.tamaya.server.spi.Sco
 my.full.packagename.ClientScopeProvider
 -----------------------------------------------
 
+
 ==== Adapting the Way Configuration is Derived
 
-Finally the effective readong and configuration handling logic can also be replaced or improved. This can be
+Finally the effective reading and configuration handling logic can also be replaced or improved. This can be
 done by registering your own implementation of the interface +ConfigProviderService+:
 
 [source, java]
@@ -336,6 +341,7 @@ public interface Server {
 }
 -----------------------------------------------
 
+
 ==== The ScopeManager Singleton
 
 Finally whe implementing your own server, you might also benefit from the +ScopeManager+ singleton. Basically this
@@ -364,3 +370,4 @@ public final class ScopeManager {
 
 }
 -----------------------------------------------
+

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_spi-support.adoc b/content/documentation/extensions/mod_spi-support.adoc
index 105ca84..e43bab9 100644
--- a/content/documentation/extensions/mod_spi-support.adoc
+++ b/content/documentation/extensions/mod_spi-support.adoc
@@ -11,6 +11,7 @@ toc::[]
 
 Tamaya _SPI Support_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
 Tamaya _SPI Support_ provides a few helpful base classes that can be used to implement some of the often
@@ -44,7 +45,7 @@ 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:
+To use Tamaya's _spisupport_ you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_spring.adoc b/content/documentation/extensions/mod_spring.adoc
index 420b49f..9c7c5d8 100644
--- a/content/documentation/extensions/mod_spring.adoc
+++ b/content/documentation/extensions/mod_spring.adoc
@@ -11,6 +11,7 @@ toc::[]
 
 Tamaya _Spring_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
 Tamaya _Spring_ currently provides two implementations also full integration for Spring:
@@ -76,6 +77,7 @@ following lines somewhere into one of your application context configuration fil
 <bean id="tamayaConfigProvider" name="tamayaConfigProvider" class="org.apache.tamaya.integration.spring.TamayaSpringConfig"/>
 --------------------------------------------------------
 
+
 === Configuring your Context
 
 Done so enables you to use Tamaya as a backend for property resolution, e.g. +propertyValue+ as illustrated below
@@ -88,6 +90,7 @@ is resolved from the current Tamaya configuration.
 </bean>
 --------------------------------------------------------
 
+
 === Configuring your Beans
 
 Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans:
@@ -134,4 +137,5 @@ public class ConfiguredSpringBean {
 }
 --------------------------------------------------------
 
-Summarizing you get all the nice features of Tamaya out of the box running with your Spring code.
+Summarizing you get all the nice features of Tamaya out of the box running
+with your Spring code.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_usagetracker.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_usagetracker.adoc b/content/documentation/extensions/mod_usagetracker.adoc
index 6a444f6..7408509 100644
--- a/content/documentation/extensions/mod_usagetracker.adoc
+++ b/content/documentation/extensions/mod_usagetracker.adoc
@@ -11,18 +11,21 @@ toc::[]
 
 Tamaya _UsageTracker_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === What functionality this module provides ?
 
 Tamaya _UsageTracker_ allows to record and count the configuration access and consumer locations in your local
 VM.
 
+
 === Compatibility
 
 The module is based on Java 7, so it can be used with Java 7 and beyond.
 
+
 === Installation
 
-To benefit from configuration mutability support you only must add the corresponding dependency to your module:
+To use Tamaya _usagetracker_ you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -103,7 +106,8 @@ public final class ConfigUsageStats{
 }
 -----------------------------------------------------------
 
-==== Customizing the Stacktrage for Usage Reporting
+
+==== Customizing the Stacktrace for Usage Reporting
 
 The stacktrace tracked by the system can be customized in several ways:
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_validation.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_validation.adoc b/content/documentation/extensions/mod_validation.adoc
index 8a6c547..35c193a 100644
--- a/content/documentation/extensions/mod_validation.adoc
+++ b/content/documentation/extensions/mod_validation.adoc
@@ -11,11 +11,13 @@ toc::[]
 
 Tamaya _Validation_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === Overview
 
 Tamaya _Validation_ adds support to validate a configuration against a set of rules
 defined in a Tamaya Metaconfiguration XML file.
 
+
 === Compatibility
 
 The module is based on Java 7, so it will run on Java 7 and beyond.
@@ -23,7 +25,7 @@ The module is based on Java 7, so it will run on Java 7 and beyond.
 
 === Installation
 
-To benefit from Tamaya Metamodel feature you only must add the corresponding dependency to your module:
+To activate configuration _validation_ you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -50,6 +52,7 @@ are supported:
 META-INF/tamaya-validation-*.xml  // classpath (multiple entries-possible)
 -----------------------------------------------
 
+
 === The Validation XML Format
 
 The configuration validation is defined by simple configuration meta-data entries.
@@ -79,6 +82,7 @@ The configuration validation is defined by simple configuration meta-data entrie
 </configuration-validation>
 -----------------------------------------------
 
+
 ==== The Example Explained
 
 * The *provider* entry is used for generating validation message, when a validation fails.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/91a1b450/content/documentation/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_yaml.adoc b/content/documentation/extensions/mod_yaml.adoc
index 82b0f33..9c80260 100644
--- a/content/documentation/extensions/mod_yaml.adoc
+++ b/content/documentation/extensions/mod_yaml.adoc
@@ -11,6 +11,7 @@ toc::[]
 
 Tamaya _YAML_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
 
+
 === Overview
 
 Tamaya _YAML_ provides support for reading configuration using the YAML format (yaml.org). YAML hereby
@@ -24,7 +25,7 @@ The YAML 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 YAML as configuration format you must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -37,16 +38,18 @@ To benefit from configuration builder support you only must add the correspondin
 
 This extension also transitively requires the +tamaya.formats+ module.
 
+
 === Reading configuration in YAML
 
 For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided:
 
 [source, java]
 -----------------------------------------------
-ConfigurationData dataRead = ConfigurationFormats.readConfig(
+PropertySource ps = ConfigurationFormats.createPropertySource(
     getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat()));
 -----------------------------------------------
 
+
 === Examples
 
 The YAML module adds instances of +ConfigurationFormat+ so YAML configuration can be read and mapped to the