You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by po...@apache.org on 2016/10/31 21:34:42 UTC
[1/5] incubator-tamaya-site git commit: TAMAYA-186: Add existing
pages.
Repository: incubator-tamaya-site
Updated Branches:
refs/heads/master 90f34d22f -> 3d91bad59
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/usecases.adoc
----------------------------------------------------------------------
diff --git a/content/usecases.adoc b/content/usecases.adoc
new file mode 100644
index 0000000..19bbca6
--- /dev/null
+++ b/content/usecases.adoc
@@ -0,0 +1,506 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Use Cases and Requirements
+
+toc::[]
+
+== Use Cases
+
+=== Simple Access
+
+Users want to be able to access configuration in a unified way both in SE and EE. EE may provide additional
+mechanism, such as injection, but the SE mechanisms should work as well, so any code written in SE is fully
+portable to EE as well.
+This can only be achieved by providing a static accessor, e.g.
+
+[source,java]
+------------------------------------------------------------
+Configuration config = Configuration.current();
+------------------------------------------------------------
+
+The call above should work exactly the same in EE. To enable this the static call must be delegated in the
+internals of the singleton, depending on the runtime. In EE the executing component can behave contextually,
+or even be loaded within the CDI environment (at least for post loading, application runtime aspects, but not earlier).
+
+Additionally in EE it should also be possible to inject Configuration, which gives you the same results as the call
+above:
+
+[source,java]
+------------------------------------------------------------
+@Inject
+private Configuration cfg;
+------------------------------------------------------------
+
+
+=== Simple Lookup of Properties
+
+Users just want to create a configuration ad hoc, from given property files. The
+files could be locally in the file system, on the classpath.
+
+Tamaya should provide a simple Java API for accessing key/value based configuration. Hereby users want to access
+properties as simple String values.
+
+Hereby returning Java 8 Optional values must be considered as well, instead of returning +null+.
+
+
+=== Value Placeholders
+
+Users just want to to be able to add placeholders to the values of configuration (not the keys). The mechanisms for
+resolving the placeholders hereby should be not constraint to one single lanmguage like EL. Instead of different
+replacement strategies should be selectable, e.g. by prefixing an expression with the name of the resolver that
+should do the work (eg +"blabla ${env:HOME} using Java version ${sys:java.version}."+.
+This allows resolution mechanism to be isolated easily and also allows to use simpler mechanisms, if no more complex
+ones like EL are required. This is especially useful to deal with low resource environment like ME.
+
+
+=== Type Safe Properties
+
+Users just want to access properties not only as Strings, but let Tamaya do the conversion to the required
+or the configred target type. By defauklt all java.ui.lang wrapper and primitive types should be supported, but also
+other common types like date/time types, math numeric types and more.
+
+It must be possible that users can register their own custom types.
+
+Finally users also want to be able to dynamically provide or override type adaption (conversion), when reading a value,
+for a certain key/value pair.
+
+
+=== Configuration Templates
+
+Users want to be able to let Tamaya implement an interface template based on configuration.
+This use case is pretty similar to the injection use case. Basically the values are not injected,
+but cached within the template proxy returned, e.g. as +DynamicValue+.
+Similarly it could even be possible to define callback methods (default methods)
+or register listeners to DynamicValue instances returned.
+
+Templates hereby can easily be managed, but provide a excellent mechanism to provide type-safe configuration
+to clients in a very transparent way. Details can be controlled by using the same annotations as for
+normal configuration injection.
+
+
+=== Java 8 Functional Support
+
+Users want to be able to benefit from the new programming styles introduced with Java 8. Configuration
+should provide extension points for different aspects, where additional code can be hooked in easily.
+In short: were possible functional interfaces should be modelled.
+
+Examples:
+
+* code that converts a configuration to another kind of configuration: +UnaryOperator<Configuration>+
+* code that creates any kind of result based on a configuration: +Function<Configuration,T>+
+* Adapters for type conversion are defined as +Function<String,T>+
+* Key, value filters ccan be modelled as +BiFunction<String,String,String>+
+* etc.
+
+
+=== Configuration Locations
+
+Users want to be able to
+
+* read configuration from different locations.
+* By default classpath and file resources are
+ supported. But similarly remote access using a JSON ReST call should be possible.
+* Tamaya should define a JSON and XML format for configuration.
+* Configuration locations should be scannable using ant-styled resource patterns, if possible.
+* Scanning and reading logic can be modularized by using a +ConfigReader+ interface.
+
+
+=== Configuration Formats
+
+Users want to be able to use the format they prefer.
+
+* properties, xml-properties and ini-format should be supported by default
+* Other/custom formats should be easily addable by registering or providing the format on configuration evaluation (read).
+* When possible Tamaya should figure out which format to be used and how the InputStream should be correctly
+ interpreted.
+
+
+=== Multiple Configurations
+
+When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional
+aspects to be considered by a configuration system.
+
+* Different code modules, libraries, plugins or products want to have their "own" separated configuration.
+* Similar it should be possible to add fully specific additional configurations.
+
+The default configuration hereby should always be present, whereas additional configurations are optional.
+Users want to be able to check the availability of such an additional configuration.
+
+Of course, additional configuration must be identifiable. The best way to do is to be discussed, nevertheless the
+mechanism must not depend on Java EE and the identifying keys must be serializable easily.
+Basically simple names are sufficient and woukld provide exact this required functionality.
+
+
+=== External Configuration
+
+Users want to be able to replace, override, extend or adapt any parts or all of an existing configuration from
+external sources.
+This also must be the case for multi-context environments, where the context identifiers are
+the only way to link to the correct remote configuration.
+
+
+=== Context Dependent Configuration
+
+In multi tenancy setups or complex systems a hierarchical/graph model of contexts for configurations is required, or different runtime contexts are executed in parallel
+within the same VN. What sounds normal for EE also may be the case for pure SE environments:
+
+* Users want to be able to model different layers of runtime context
+* Users want to identiofy the current layer, so configuration used may be adapted.
+
+
+
+=== Dynamic Provisioning (UC8)
+
+In Cloud Computing, especially the PaaS and SaaS areas a typical use case would be that an application (or server)
+is deployed, configured and started dynamically. Typically things are controlled by some "active controller components",
+which are capable of
+
+* creating new nodes (using IaaS services)
+* deploying and starting the required runtime platform , e.g. as part of a PaaS solution.
+* deploying and starting the application modules.
+
+All these steps require some kind of configuration. As of today required files are often created on the target node
+before the systems are started, using proprietary formats and mechanism. Similarly accessing the configuration in place
+may require examining the file system or using again proprietary management functions. Of course, a configuration
+solution should not try to solve that, but it can provide a significant bunch of functionality useful in such scenarios:
+
+* provide remote capabilities for configuration
+* allow configuration to be updated remotely.
+* allow client code to listen for configuration changes and react as needed.
+
+
+=== Minimal Property Source SPI
+
+Users expect that implementing an additional configuration property source is as easy as possible.
+So there should be an SPI defined that allows any kind of data source to be used for providing configuration data.
+The interface to be implemented is expected to be minimal to reduce the implementation burden. Default
+methods should be used where possible, so only a few methods are expected to be required to implement.
+
+
+=== Scannable Properties
+
+If possible configuration should be scannable, meaning it should be possible to evaluate the keys available.
+The corresponding capabilities should be accessible by a +isScannable()+ method.
+
+
+=== Combine Configurations
+
+Users want to be able to combine different configurations to a new configuration instance.
+Hereby the resulting configuration can be
+
+* a union of both, ignoring duplicates (and optionally log them)
+* a union of both, duplicates are ignored
+* a union of both, conflicts are thrown as ConfigException
+* an intersection of both, containing only keys present and equal in both configurations
+* an arbitrary mapping or filter, modelled by an +CombinationPolicy+, which basically can be modelled
+ as +BiFunction<String, String, String>+, hereby
+ ** a result of +null+ will remove the key
+ ** any other result will use the value returned as final value of the combination.
+
+
+=== MX/ReST Management
+
+Users want to be have comprehensive management support, which should allow
+
+* to change configuration
+* to remove configuration
+* to view configuration and its provider details
+
+
+=== Adaptable Service Context
+
+Tamaya should support an adaptable +ServiceContext+ to resolve any kind of implememntation services, both API services as core
+framework services. The +ServiceContext+ should be dynamically replecable by configuring an alternate instance of
+using the Java *ServiceContet+.
+
+This decouples component usage from its load and management part and als greatly simplifies integration with
+new/alternate runtime environments.
+The service context is exptected to provide
+
+* single singleton instances: these service can be cached.
+* access to multiple instances which implement some commons SPI interface.
+* as useful priorization of components is done by the model itself.
+
+
+=== Configuration Injection
+
+Users want to be able to polulate configured items by injecting configured values. Hereby
+
+* the lifecycle of the instances is not managed by Tamaya
+* all references to items configured are managed as weak references, to prevent memoryleaks.
+* Injection should if possible evaluate the properties by defaults. Even properties without
+ any annotations are possible.
+* Users expect to exclude certain properties from calculation
+* Beside injection of properties it is also possible to call setter methods with one parameter similarly.
+* Basically injection is performed, when the instance is passed to the Tamaya configuration system. It should also
+ be possible to inject/provide final values, especially Strings. Changes on configured values should be
+ reflected in the current value. Setters methods similarly can be called again, with the new values, on changes.
+* Users expect to control dynamic values and recall of setter methods, basically the following strategies should be
+ supported:
+ ** inject only once and ignore further changes.
+ ** reinject/reinitialize on each change
+
+* Dynamic Values can easily be modeled as +ConfiguredValue+ instances, which should have the following functionality:
+ ** access the current value
+ ** access the new value
+ ** access the latest value access time in ms
+ ** access the latest value update time in ms
+ ** evaluate easily if the value has changed since the last access
+ ** accept the change
+ *** as a shortcut it should be possible to accept the change on access of the value implicitly, hereby always accessing
+ the latest valid value.
+ ** ignore the change
+ ** register +Consumer<DynamicValue>+ liasteners to listen on the changes (ans also removing them later again).
+
+All observing functionality can be done completely asynchronously and in parallel.
+
+
+[[Requirements]]
+== Requirements
+=== Core Configuration Requirements
+==== General
+
+Tamaya must provide a Java SE API for accessing key/value based configuration. Hereby
+
+* +Configuration+ is modelled by an interface
+* +Configuration+ is organized as key/value pairs, using a subset of functionality present on +Map<String,String>+ as
+ follows:
+ ** access a value by key (+get+)
+ ** check if a value is present (+containsKey+)
+ ** get a set of all defined keys (+keySet+)
+ ** a configuration must be convertible to a +Map+, by calling +toMap()+
+ ** a configuration must provide access to its meta information.
+* +Configuration+ value access methods must never return null.
+* The API must support undefined values.
+* The API must support passing default values, to be returned if a value is undefined.
+* The API must allow to throw exceptions, when a value is undefined. Customized exceptions hereby should be supported.
+* Properties can be stored in the classpath, on a file or accessible by URL.
+* Properties can be stored minimally in properties, xml-properties or ini-format.
+
+
+==== Minimalistic Property Source
+
+For enabling easy integration of custom built configuration sources a minimalistic API/SPI must be defined, that
+
+* is modelled by an interface
+* is a minimal subset of +Configuration+ necessary to implement a configuration.
+* must be convertible to a "Configuration+.
+
+==== Extension Points
+
+For supporting more complex scenarios, +Configuration+
+
+* must implement the composite pattern, meaning new +Configuration+ instances can be created by combining existing
+ configurations.
+* must be adaptable, by creating a new configuration by applying a +UnaryOperator<COnfiguration>+ to it.
+* must be queryable, by passing a +ConfigQuery+ to an +Configuration+ instance.
+
+
+==== Type Safety
+
+Besides Strings +Configuration+ should also support the following types:
+
+* Primitive types
+* Wrapper types
+* All other types (by using a +PropertyAdapter+
+
+Hereby type conversion should be done as follows:
+
+. Check if for the given target type an explicit adapter is registered, if so, use the registered adapter.
+. If no adapter is present, check if the target type T has static methods called +T of(String), T getInstance(String), T valueOf(String), T from(String)+. If so
+use this method to create the non value of T.
+. Check if the target type has a constructor T(String). If so, try to instantiate an instance using the constructor.
+. Give up, throw a IllegalArgument exception.
+
+=== Configuration Fomats
+
+By default Tamaya support the following configuration formats:
+
+* .properties
+* .xml properties
+* .ini files
+
+It must be possible to add additional formats by registering them with the current +ServiceContext+.
+
+=== Mutability
+
+* Configurations can be mutable, mutability can be accessed as a property.
+* Configuration can be changed by collecting the changes into a +ConfigCHangeSet+ and apply this set to the
+ given +Configuration+ instance.
+* Besides the points above, +Configuration+ is immutable.
+
+=== Serializability and Immutability of Configuration
+
+* Configuration is modelled as a service. Therefore serialization may not work. This can be mitigated by adding
+ a freeze feature, where the know key/value pairs are extracted into an immutable and serializable form.
+
+=== Configuration Combination Requirements
+
+At least the following composition policies must be supported:
+
+* override: subsequent entries override existing ones.
+* aggregate-exception: key/values were added, in case of conflicts a +ConfigException+ must be thrown.
+* aggregate-ignore-duplicates: similar to union, whereas duplicates are ignored (leaving the initial value loaded).
+* aggregate-combine: conflicting entries were resolved by adding them both to the target configuration by
+ redefining partial keys.
+* custom: any function determining the key/values to be kept must be possible
+
+When combining configuration it must also be possible to override (file/classpath) configuration by
+
+* system properties.
+* command line arguments.
+
+
+=== Configuration Injection
+
+As metnioned configuration can be injected by passing a unconfigured instance of an annotated class to the
++Configuration.configure+ static method:
+
+[source, java]
+.Configuring a POJO
+----------------------------------------------------
+MyPojo instance = new MyPojo();
+Configuration.configure(instance);
+----------------------------------------------------
+
+Hereby
+* It must be possible to define default values to be used, if no valid value is present.
+* It must be possible to define dynamic expressions, at least for default values.
+* The values configured can be reinjected, if the underlying configuration changes. This should also be the case
+ for final classes, such as Strings.
+* Reinjection should be controllable by an loading policy.
+* It must be possible to evaluate multiple keys, e.g. current keys, and as a backup deprecated keys
+ from former application releases.
+* It must be possible to evaluate multiple configurations.
+* The type conversion of the properties injected must be configurable, by defining a +PropertyAdapter+.
+* The value evaluated for a property (before type conversion) must be adaptable as well.
+* It must be possible to observe configuration changes.
+
+The following annotations must be present at least:
+
+* *@ConfiguredProperty* defining the key of the property to be evaluated. It takes an optional value, defining the
+ property name. It must be possible to add multiple annotations of this kind to define an order of evaluation
+ of possible keys.
+* *@DefaultValue* (optional) defines a default String value, to be used, when no other key is present.
+* *@WithConfig* (optional) defines the name of the configuration to be used. Similar to +@ConfiguredProperty+ multiple
+ configuration can be defined for lookup.
+* *@WithConfigOperator* allows to adapt the String value evaluated, *before* it is passed as input to injection or
+ type conversion.
+* *@WithPropertyAdapter* allows to adapt the conversion to the required target type, hereby overriding any default
+ conversion in place.
+* *@WithLoadPolicy* allows to define the policy for (re)injection of configured values.
+* *@ObservesConfigChange* allows to annotate methods that should be called on configuration changes.
+* *@DefaultAreas" allows to define a key prefix key to be used for the configured key, if no absolute key
+ is defined.
+
+=== Configuration Templates
+
+For type safe configuration clients should be able to define an interface and let it implement by the
+configuration system based on +Configuration+ available:
+
+* Clients define an interface and annotate it as required (similar to above)
+* The interface methods must not take any arguments
+* The configuration system can be called to return such an interface implementation.
+* The configuration system returns a proxy hereby providing type-safe access the values required.
+* Similar to configured types also templates support multiple values and custom adapters.
+* It is possible to listen on configuration changes for templates, so users of the templates
+ may react on configuration changes.
+
+The following snippet illustrates the requirements:
+
+[source, java]
+.Type Safe Configuration Template Example
+----------------------------------------------------
+public interface MyConfig {
+
+ @ConfiguredProperty("myCurrency")
+ @DefaultValue("CHF")
+ String getCurrency();
+
+ @ConfiguredProperty("myCurrencyRate")
+ Long getCurrencyRate();
+
+ @ConfigChange
+ default configChanged(ConfigChange event){
+ ...
+ }
+
+}
+----------------------------------------------------
+
+Templates can be accessed by calling the +Configuration.current(Class)+ method:
+
+[source, java]
+.Accessing a type safe Configuration Template
+----------------------------------------------------
+MyConfig config = Configuration.current(MyConfig.class);
+----------------------------------------------------
+
+[[RequirementsServer]]
+=== Server Configuration Requirements
+
+* Ensure Configuration can be transferred over the network easily.
+* Beside serializability text based formats for serialization in +XML+ and +JSON+ must be defined.
+* A management API must be defined, which allows to inspect the configuration in place, e.g. using
+ JMX or REST services.
+
+[[RequirementsJavaEE]]
+
+Java EE leads to the following requirements:
+
+* Configuration must be contextual, depending on the current runtime context (e.g. boot level, ear, war, ...).
+* Hereby contextual aspects can even exceed the levels described above, e.g. for SaaS scenarios.
+* Resources can be unloaded, e.g. wars, ears can be restarted.
+* The different contextual levels can also be used for overriding, e.g. application specific configuration
+may override ear or system configuration.
+* Configuration may be read from different sources (different classloaders, files, databases, remote locations).
+* Configuration may be read in different formats (deployment descriptors, +ServiceLoader+ configuration, alt-DD feature, ...)
+* JSF also knows the concept of stages.
+* Many SPI's of Java EE require the implementation of some well defined Java interface, so it would be useful if the
+ configuration solution supports easy implementation of such instances.
+* In general it would be useful to model the +Environment+ explicitly.
+* Configuration used as preferences is writable as well. This requires mutability to be modelled in way, without the
+ need of synchronization.
+* JNDI can be used for configuration as well.
+
+[[RequirementsMultitenancy]]
+
+Configurations made in the tenant or user layer override the default app configuration etc., so
+
+* It must be possible to structure Configuration in layers that can override/extend each other.
+* The current environment must be capable of mapping tenant, user and other aspects, so a corresponding configuration
+ (or layer) can be derived.
+
+[[RequirementsExtensions]]
+=== Extensions Requirements
+
+It must be possible to easily add additional functionality by implementing external functional interfaces operating
+on +Configuration+.
+
+* +UnaryOperator<Configuration>+ for converting into other version of +Configuration+.
+* +ConfigQuery<T>+ extending +Function<T, Configuration>+.
+
+[[RequirementsNonFunctional]]
+=== Non Functional Requirements
+THe following non-functional requirements must be met:
+
+* tbd
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/jbake.properties
----------------------------------------------------------------------
diff --git a/jbake.properties b/jbake.properties
index bebb298..ee53714 100644
--- a/jbake.properties
+++ b/jbake.properties
@@ -1,4 +1,4 @@
-site.host=https://tamaya.incubator.apache.org/
+site.host=https://tamaya.incubator.apache.org
render.tags=false
render.sitemap=true
template.masterindex.file=index.thyme
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/templates/menu.thyme
----------------------------------------------------------------------
diff --git a/templates/menu.thyme b/templates/menu.thyme
index c4191c1..036d68c 100644
--- a/templates/menu.thyme
+++ b/templates/menu.thyme
@@ -19,11 +19,13 @@
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Home</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'quickstart.html'">Quickstart</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Documentation</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'/apidocs/index.html'">API</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Development</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Releases</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'about.html'">About</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'about.html'">About</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'sitemap.xml'">Sitemap</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+${config.feed_file}">Subscribe</a></li>
<!--
<li class="dropdown">
@@ -38,7 +40,7 @@
<li><a href="#">One more separated link</a></li>
</ul>
</li>
--->
+-->
</ul>
</div><!--/.nav-collapse -->
</div>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/templates/post.thyme
----------------------------------------------------------------------
diff --git a/templates/post.thyme b/templates/post.thyme
index 986aa11..9752ff2 100644
--- a/templates/post.thyme
+++ b/templates/post.thyme
@@ -16,7 +16,6 @@
<p th:utext='${content.body}'>body</p>
<hr />
-
</div>
</div>
<div th:replace="footer.thyme::footer"></div>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/templates/sitemap.thyme
----------------------------------------------------------------------
diff --git a/templates/sitemap.thyme b/templates/sitemap.thyme
index 5180df9..dafdb93 100644
--- a/templates/sitemap.thyme
+++ b/templates/sitemap.thyme
@@ -4,4 +4,4 @@
<loc th:text="${config.site_host+'/'+content.uri}">loc</loc>
<lastmod th:text='${#dates.format(content.date,"yyyy-MM-dd")}'>lastmod</lastmod>
</url>
-</urlset>
\ No newline at end of file
+</urlset>
[4/5] incubator-tamaya-site git commit: TAMAYA-186: Add existing
pages.
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_cdi.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_cdi.adoc b/content/extensions/mod_cdi.adoc
new file mode 100644
index 0000000..db86633
--- /dev/null
+++ b/content/extensions/mod_cdi.adoc
@@ -0,0 +1,233 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya CDI Integration (Extension Modules)
+=== Overview
+
+Apache Tamaya currently provides two implementations for integration with CDI extensions implementing similar
+functionality as described in this document:
+
+* Loading of CDI managed SPI components as configuration extensions such as +PropertySources, PropertySourceProviders,
+ PropertyFilters, etc+. This also includes SPI defined by any Tamaya submodules.
+* Implement and enable Tamaya's configuration injection services with CDI.
+
+Hereby there are two implementations provided:
+
+* +tamaya-cdi-ee+ implements injection by using CDI's injection mechanism to inject configuration values into the
+ beans managed by the CDI systems.
+* +tamaya-cdi-se+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used
+ for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas
+ beans and injection control overall are still managed by CDI.
+* One difference, of course, is that +tamaya-se+ also provides an SE compatible API (+ConfigurationInjection,
+ ConfigurationInjector+), which is not available, when using the purely Java EE based variant.
+
+The annotations used for all injection functionality in Tamaya is defined as a separate module. This allows you to
+code against the injection API without dependency on the concrete injection implementation. As a consequence your
+components will be compatible regardless if deployed in a pure SE, a Java EE (CDI) or OSGI or Spring environment:
+
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection-api</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Compatibility
+
+Both modules are based on Java 7, so they will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya CDI integration you only must one of the following dependencies to your module. Ensure that
+you never have installed both CDI extensions at the same time because this may be lead to unforseen side-effects.
+
+.CDI Pure Application Configuration
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-cdi-ee</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+.CDI enhanced with Tamaya SE Application Configuration
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-cdi-se</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they
+register CDI extensions that implement Configuration injection as described before.
+
+IMPORTANT: Never install Tamaya's +tamaya-cdi-se+ and +tamaya-cdi-ee+ on the same system, since unpredictable side
+ effects could occur.
+
+=== Registering CDI managed components into the Application's ConfigurationContext
+
+As mentioned both modules allow to provide Tamaya SPI extensions modules as ordinary CDI managed beans. By default
+extensions should be registered using +@Singleton+ or +@ApplicationScoped+ scope annotations. So you can define/deploy
+additional application specific +PropertySources+ and other artifacts simply by defining a CDI managed bean implementing
+the required SPI interface:
+
+[source, java]
+--------------------------------------------------------
+@Singleton
+public class TestPropertySource implements PropertySource{
+
+ final Map<String,String> config = new HashMap<>();
+
+ public TestPropertySource(){
+ config.put("a.b.c.key1", "keys current a.b.c.key1");
+ config.put("a.b.c.key2", "keys current a.b.c.key2");
+ config.put("{"+getName()+"}source", getClass().getName());
+ }
+
+ @Override
+ public int getOrdinal() {
+ return 10;
+ }
+
+ @Override
+ public String getName() {
+ return getClass().getName();
+ }
+
+ @Override
+ public String get(String key) {
+ return config.get(key);
+ }
+
+ @Override
+ public Map<String, String> getProperties() {
+ return config;
+ }
+
+ @Override
+ public boolean isScannable() {
+ return true;
+ }
+}
+--------------------------------------------------------
+
+Note that for many SPI's there is a priority mechanism using +@Priority+ annotations in place.
+The +ServiceContext+ implementation combines the components registered with the ones loaded from the +ServiceLoader+
+mechanism hereby considering classloaser hierarchies.
+
+
+=== Annotating your Classes
+
+Basically annotating your classes is stright forward. +@Config+ defines an additional CDI qualifier that is, depending
+on the module deployed, handled by a CDI producer (+tamaya-cdi-ee+) or the Tamaya SE injection mechanism $
+(+tamaya-cdi-se+). All types injected by this module are injected using _dependent scope_.
+
+
+[source, java]
+--------------------------------------------------------
+@RequestScoped
+public class ConfiguredClass{
+
+ @Config
+ private String testProperty;
+
+ @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"})
+ @ConfigDefault("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
+ String value1;
+
+ @Config({"foo","a.b.c.key2"})
+ private String value2;
+
+ @Config
+ @ConfigDefault("N/A")
+ private String runtimeVersion;
+
+ @Config
+ @ConfigDefault("${sys:java.version}")
+ private String javaVersion2;
+
+ @Config
+ @ConfigDefault("5")
+ private Integer int1;
+
+ ...
+
+}
+--------------------------------------------------------
+
+=== Advanced Use Cases
+
+Beside basic configuration Tamaya also covers additional requirements:
+
+* _Reading multiple keys, where the first successful one is determining the value of the configuration, is
+ simply possible, by adding multiple keys to the +@Configy+ annotation.
+ E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Config({"a.b", "new.b"}
+private String value;
+--------------------------------------------------------------------------------------
+
+* When you must apply a +ConfigOperator+ to your config, before reading the configuration, you can
+ configure one as follows:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Config({"a.b", "new.b"}
+@WithConfigOperator(MyOperator.class)
+private String value;
+--------------------------------------------------------------------------------------
+
+* When you must apply a some special conversion, or you use a type that is not registered
+ for conversion, you can configure a custom converter to be applied as follows:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Config({"a.b", "new.b"}
+@WithPropertyConverter(MyConverter.class)
+private MySpecialFooType value;
+--------------------------------------------------------------------------------------
+
+* Often multiple keys in a class belong to the same root section. So instead of copying this to
+ every entry you can define the most common root sections in the type's header:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@ConfigDefaultSections({"aaaa", "new"});
+public class MyType{
+
+@Config({"b", "[legacy.bKey]"} // lookups: "aaaa.b", "new.b", legacy.bKey
+private String value;
+--------------------------------------------------------------------------------------
+
+In the example above +legacy.bKey+ defines an absolute key, which is not combined with any defined
+default section parts.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_classloader_support.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_classloader_support.adoc b/content/extensions/mod_classloader_support.adoc
new file mode 100644
index 0000000..7b93a4b
--- /dev/null
+++ b/content/extensions/mod_classloader_support.adoc
@@ -0,0 +1,91 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+[[Remote]]
+== Tamaya Classloader Aware ServiceContext (Extension Module)
+=== Overview
+
+The Tamaya classloader support provides an alternative implementation of +java.util.ServiceLoader+, which is aware
+of classloaders, hereby preventing multiple loading of components within a classloader hierarchy.
+
+
+=== Compatibility
+
+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:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-classloader-support</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+The component will auto.register its components and override the default +ServicceContext+ in use by default
+with an instance of type +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+. This implementation returns
+a priority of +10+.
+
+=== How it Works
+
+Basically the component manages a +Map+ of all classloaders encountered. When services are accessed, the component
+will evaluate the services as follows:
+
+* the component walks up the class loader hierarchy.
+* in a next step the hierarchy is traversed down from the parent to the current classloader. Hereby it is checked
+ if the service list for the required type has been loaded already. If not the service configuration files are
+ evaluated.
+* This configuration file evaluation will ignore all resources already loaded by any of the already traversed parent
+ classloaders.
+* For each configuration file newly visible to the classloader currently traversed, the corresponding services are
+ loaded unleyy, the same service class already has been loaded by one its parent classloaders or another file
+ loaded with this classloader.
+* Finally all services found are returned as the full collection of services valid for the given context (classloader).
+
+This ensures no service is loaded multiple times, even when it is referenced multiple times in several service
+configurations. Additionally every service is loaded on the classloader where it is also declared the first time.
+
+
+=== Control Logging
+
+The service component by default only logs errors. But it is possible to change this by reconfiguring the logging
+levels on the following logging names/path: +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+
+
+* _INFO_ logs additional info on the services accessed.
+* _FINEST_ logs additional info on the services scanned and selected.
+
+
+=== Classloader Aware Configuration
+
+The mechanism above is used to provide a classloader aware implementation of +ConfigurationContext+
+(+org.apache.tamaya.clsupport.internal.CLAwareConfigurationContext+). Similarly to the service variants
+this class provides a context implementation that manages the core configuration aspects considering classloading
+hierarchies:
+
+* +PropertySource+, +PropertySourceProviders+
+* +PropertyFilters+, +PropertyCombinationPolicy+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_collections.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_collections.adoc b/content/extensions/mod_collections.adoc
new file mode 100644
index 0000000..61e5553
--- /dev/null
+++ b/content/extensions/mod_collections.adoc
@@ -0,0 +1,248 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Collection Support
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+[[Optional]]
+== Tamaya Collection Support (Extension Module)
+=== Overview
+
+All configuration in Tamaya is expressed as simple key, value pairs. Nevertheless this concept allows similarly
+the modelling of collection typed values such as lists, sets, maps or simple collections of things. The Tamaya
+Collections extension adds this functionality to the Tamaya eco-system.
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To use Tamaya collection support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-collections</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Overview
+
+Tamaya Collections adds +PropertyConverter+ implementations that are able to access configuration data
+as lists, maps or sets. By default this works out of the box as easy as accessing any other type of
+configuration data, e.g.
+
+[source, java]
+-----------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+
+// Without any content specification, a list of String is returned.
+List<String> simpleList = config.get("my.list.config.entry", List.class);
+
+// Using a TypeLiteral allows to use every convertible sub type supported by the system.
+List<Integer> intList = config.get("my.list.config.entry", new TypeLiteral<List<Integer>>(){});
+-----------------------------------------------
+
+Configuration in that case, by default, is a simple comma-separated list of entries, e.g.
+
+[source, properties]
+-----------------------------------------------
+my.list.config.entry=1,34454,23,344545,3445
+-----------------------------------------------
+
+Additionally the module allows adding additional meta-entries, which allows to tweak some of the
+inner-workings, e.g.
+
+* using your own +PropertyConverter+ implementation for parsing entries.
+* specifying a custom separator String to be used to split the items (default is {{','}}.
+* specifying a custom separator String to be used to split key/value paris when parsing map entries.
+* specifying the implementation type of the collection instance to be returned.
+* specifying if the resulting collection should be returned as a modifiable collection.
+
+=== Supported Types
+
+This module supports the following types:
+
+* +java.util.Collection+
+* +java.util.List+
+* +java.util.ArrayList+
+* +java.util.LinkedList+
+* +java.util.Set+
+* +java.util.SortedSet+
+* +java.util.TreeSet+
+* +java.util.HashSet+
+* +java.util.Map+
+* +java.util.SortedMap+
+* +java.util.HashMap+
+* +java.util.TreeMap+
+
+Hereby the type is determined primarly by the parameter type accessed, e.g.
++config.get("mylist", ArrayList.class)+ will always return an +ArrayList+
+as result.
+
+==== Configuring the target implementation type
+
+Tamaya Collections allows you to configure the target collection type by adding the
+following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+
+can be ommitted:
+
+[ source, properties]
+-----------------------------------------------
+mylist=a,b,c
+_mylist.collection-type=LinkedList
+-----------------------------------------------
+
+When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still
+get an +ArrayList+ as a result. However when you call +config.get("mylist", List.class)+ you will
+get a +LinkedList+ as implementation type.
+
+This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation
+type returned when accessing +List+, +Map+ or +Collection+.
+
+
+=== Collecting Configuration Entries instead of Overriding
+
+By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for
+the most significant configuration entry is used. In case of collections (and maybe also other use cases),
+overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your
+configuration to be *combined* to a new entry containing all values provided by any property sources.
+
+Therefore Tamaya Collections also provides a more sophistiated +CombinationPolicy+ (automatically configured)
+that allows to adapt the way how configuration entries are combined. All you must do is declaring
+the mechanism to be applied by an according meta-configuration parameter, e.g. for +my.list+ your config may
+look as follows:
+
+[source, properties]
+-----------------------------------------------
+# from PropertSource 1
+my.list=1,2,3
+
+# from PropertSource 2
+my.list=4,5,6
+
+# without any additional meta-info these entries would be combined to
+my.list=4,5,6
+-----------------------------------------------
+
+With Tamaya Collections you can now configure the combination policy as follows:
+
+[source, properties]
+-----------------------------------------------
+# use one of the default policies: override / collect
+_my.list.combination-policy=collect
+
+# use an custom CombinationPolicy to combine the values
+_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy
+-----------------------------------------------
+
+So declaring the +collect+ policy the resulting raw output of the entry looks as follows:
+
+[source, properties]
+-----------------------------------------------
+# result when applying the collect policy:
+my.list=1,2,3,4,5,6
+-----------------------------------------------
+
+The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration
+parameter explained later in this document.
+
+
+=== Format of Collection Configuration
+
+By default collections are modelled as simple String values, that are tokenized into individual parts using a
+defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3".
+If the target context type is something different than String the smae conversion logic is used as when mapping
+configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed
+within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types,
+with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+.
+The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas
+for values the same logic is applied as for non-map collection types.
+
+[source, properties]
+-----------------------------------------------
+# a list, using the default format
+list=1,2,3,4,5,6
+
+# a map, using the default format
+map=a::b, c::d
+-----------------------------------------------
+
+==== Trimming of entries
+
+By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is
+also the case for key/value entries. So the following configuration results in the identical values for
++list1,list2+ and +map1,map2+:
+
+[source, properties]
+-----------------------------------------------
+# a list, using the default format
+list1=1,2,3,4,5,6
+list2=1, 2, 3, 4, 5, 6
+
+# a map, using the default format
+map1=a::b, c::d
+map2=a :: b, c :: d
+-----------------------------------------------
+
+Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
+space character as value:
+
+[source, properties]
+-----------------------------------------------
+# a list, with a ' ' value at the end
+list3=1, 2, 3, 4, 5, [ ]
+
+# a map, with a ' ' value for key '0'
+map3=1 :: a, 2 :: b, 0::[ ]
+-----------------------------------------------
+
+Hereby +\[+ escapes the sequence.
+
+
+==== Customizing the format
+
+The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data
+entries as follows, resulting in the same values as in the prevoius listing:
+
+[source, properties]
+-----------------------------------------------
+# a list, with a ' ' value at the end
+list3=1__2__3__ 4__ 5__[ ]
+_list3.item-separator=__
+
+# a map, with a ' ' value for key '0'
+map3=1->a, 2->b, 0->[ ]
+_map3.map-entry-separator=->
+-----------------------------------------------
+
+Of course these settings also can be combined:
+
+[source, properties]
+-----------------------------------------------
+# a reformatted map
+redefined-map=0==none | 1==single | 2==any
+_redefined-map.map-entry-separator===
+_redefined-map.item-separator=|
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_consul.adoc b/content/extensions/mod_consul.adoc
new file mode 100644
index 0000000..f29a2e1
--- /dev/null
+++ b/content/extensions/mod_consul.adoc
@@ -0,0 +1,75 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Integration with consul (Hashicorp)
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== Integration with consul (Extension Module)
+=== Overview
+
+The Tamaya consul integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with consul. Basically the module supports read-only integration (as a +ConsulPropertySource+ as well
+as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension 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:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-consul</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Consul integration comes basically with 2 artifacts:
+
+* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
+ 'consul', which is automatically registered.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
+ by accessing a +MutableConfiguration+ using the URI +config:consul+.
+
+
+=== The ConsulPropertySource
+
+The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This
+enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
+in microservice containers to connect with the according consul cluster:
+
+* The property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible etcd servers
+ (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
+ configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
+ server can be established a warning will be logged, but deployment will not fail.
+* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed
+ context. This can be activated by setting the +-Dtamaya.consul.prefix=<PREFIX>+ system property. E.g. when the prefix is
+ set to +cluster-config.+ a consul key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_environment.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_environment.adoc b/content/extensions/mod_environment.adoc
new file mode 100644
index 0000000..df889ed
--- /dev/null
+++ b/content/extensions/mod_environment.adoc
@@ -0,0 +1,58 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Environment Model (Extension Module)
+=== Overview
+
+The Tamaya Environment extension adds a simple PropertySourceProvider that evaluates a List of environment context and
+combines them in the given order into an (optional) root context within the system's configuration.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya Environment Model you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-envionment</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== How it Works
+
+tbd
+
+=== Reusable Base Classes
+
+tbd
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_etcd.adoc b/content/extensions/mod_etcd.adoc
new file mode 100644
index 0000000..4bad2a0
--- /dev/null
+++ b/content/extensions/mod_etcd.adoc
@@ -0,0 +1,205 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Integration with etcd (Core OS)
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== Integration with etcd (Extension Module)
+=== Overview
+
+The Tamaya etcd integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with etcd. Basically the module supports read-only integration (as a +EtcdPropertySource+ as well
+as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension 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:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-etcd</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+ETcd integration comes basically with 2 artifacts:
+
+* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint root.
+ (+org.apache.tamaya.etcd.EtcdAccessor+). The accessor basically provides a simple Java API for communicating
+ with etcd server. The accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
+ atomic write methods are implemented.
+* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
+ 'etcd', which is automatically registered.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster,
+ by accessing a +MutableConfiguration+ using the URI +config:etcd+.
+
+=== The EtcdAccessor
+
+The accessor mentioned implements the basic read and write API for communicating with an etcd configuration cluster.
+Hereby the accessor also provides etcd specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
+returned. Hereby the concept of etcd is used where keys starting with an '_' will be hidden from the overall
+properties map, being only directly/explicitly accessible:
+
+[source, java]
+-----------------------------------------------
+public class EtcdAccessor {
+
+ /**
+ * Creates a new instance with the basic access url.
+ * @param server server url, e.g. {@code http://127.0.0.1:4001}.
+ * @throws MalformedURLException
+ */
+ public EtcdAccessor(String server) throws MalformedURLException;
+
+ /**
+ * Get the etcd server version.
+ * @return the etcd server version, never null.
+ */
+ public String getVersion();
+
+ /**
+ * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.ttl=300 // optional
+ * _key.expiration=... // optional
+ * </pre>
+ * @param key the requested key
+ * @return the mapped result, including meta-entries.
+ */
+ public Map<String,String> get(String key);
+
+ /**
+ * Creates/updates an entry in etcd without any ttl set.
+ * The response is as follows:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * </pre>
+ * @param key the property key, not null
+ * @param value the value to be set
+ * @return the result map as described above.
+ */
+ public Map<String,String> set(String key, String value);
+
+ /**
+ * Creates/updates an entry in etcd. The response is as follows:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.ttl=300 // optional
+ * _key.expiry=... // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * _key.prevNode.ttl=300 // optional
+ * _key.prevNode.expiration=... // optional
+ * </pre>
+ * @param key the property key, not null
+ * @param value the value to be set
+ * @param ttlSeconds the ttl in seconds (optional)
+ * @return the result map as described above.
+ */
+ public Map<String,String> set(String key, String value, Integer ttlSeconds);
+
+
+ /**
+ * Deletes a given key. The response is as follows:
+ * <pre>
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34
+ * _key.ttl=300 // optional
+ * _key.expiry=... // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * _key.prevNode.ttl=300 // optional
+ * _key.prevNode.expiration=... // optional
+ * _key.prevNode.value=... // optional
+ * </pre>
+ * @param key the key to be deleted.
+ * @return the response mpas as described above.
+ */
+ public Map<String,String> delete(String key);
+
+
+ /**
+ * Access regular Tamaya properties map as follows:
+ * <pre>
+ * key1=myvalue
+ * _key1.source=[etcd]http://127.0.0.1:4001
+ * _key1.createdIndex=12
+ * _key1.modifiedIndex=34 // optional
+ * _key1.ttl=300 // optional
+ * _key1.expiration=... // optional
+ *
+ * key2=myvaluexxx
+ * _key2.source=[etcd]http://127.0.0.1:4001
+ * _key2.createdIndex=12
+ *
+ * key3=val3
+ * _key3.source=[etcd]http://127.0.0.1:4001
+ * _key3.createdIndex=12
+ * _key3.modifiedIndex=2
+ * </pre>
+ */
+ public Map<String,String> getProperties(String directory, boolean recursive);
+
+}
+-----------------------------------------------
+
+
+=== The EtcdPropertySource
+
+The +EtcdPropertySource+ is automatically registered and allows to configure the etcd servers to be used. This
+enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
+in microservice containers to connect with the according etcd cluster:
+
+* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers
+ (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
+ configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
+ server can be established a warning will be logged, but deployment will not fail.
+* Additinoally also the
+ accessor allows to configure the socket/connection timeouts by setting +tamaya.etcd.timeout+ in seconds either as
+ system or environment property.
+* The +EtcdPropertySource+ finally also allows the values read from the etcd cluster to be mapped to prefixed
+ context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
+ set to +cluster-config.+ a etcd key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_events.adoc b/content/extensions/mod_events.adoc
new file mode 100644
index 0000000..30da423
--- /dev/null
+++ b/content/extensions/mod_events.adoc
@@ -0,0 +1,372 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Events
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Events (Extension Module)
+=== Overview
+
+Tamaya Events is an extension module. Refer to the link:modules.html[extensions documentation] for further details
+about modules.
+
+Tamaya Events provides an abstraction for events like change events, when configuration has bee changed.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+To benefit from configuration event support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-events</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+=== Core Architecture
+
+The core of the module are the +ConfigEventListener+ interface and the +ConfigEvent+ class, which defines an abstraction
+for event handling and observation:
+
+[source,java]
+.ConfigEvent
+--------------------------------------------
+public final interface ConfigEvent<T> {
+
+ Class<T> getResourceType();
+ T getResource();
+ String getVersion();
+ long getTimestamp();
+}
+
+// @FunctionalInterface
+public interface ConfigEventListener {
+
+ void onConfigEvent(ConfigEvent<?> event);
+
+}
+--------------------------------------------
+
+This mechanism can now be used to propagate configuration changes to all interested stakeholders. Hereby the payloed
+can be basically arbitrary as long as it implements the +ConfigEvent+ interface. The next sections
+give more details on the the provided event implementations and abstractions that are used to implement such
+features.
+
+
+=== Modelling Configuration Changes
+
+This module provides a serializable and thread-safe abstraction modlling a configuration change. A change hereby may
+be
+
+* additional configuration entries
+* removed configuration entries
+* changes on entries
+
+This is also reflected in the +ChangeType+ enum
+
+[source,java]
+-------------------------------------------------------
+public enum ChangeType {
+ NEW,
+ DELETED,
+ UPDATED,
+}
+-------------------------------------------------------
+
+This enum type is used within the +ConfigurationChange+ class, which implements the event sent for a changed
++Configuration+:
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{
+
+ public static ConfigurationChange emptyChangeSet(Configuration configuration);
+
+ @Override
+ public Configuration getResource();
+ @Override
+ public Class<Configuration> getResourceType();
+ @Override
+ public String getVersion();
+ @Override
+ public long getTimestamp();
+ @Override
+ public long getTimestamp();
+
+ // Event specific methods
+
+ public Collection<PropertyChangeEvent> getChanges();
+ public int getRemovedSize();
+ public int getAddedSize();
+ public int getUpdatedSize();
+
+ public boolean isKeyAffected(String key);
+ public boolean isRemoved(String key);
+ public boolean isAdded(String key);
+ public boolean isUpdated(String key);
+ public boolean containsKey(String key);
+ public boolean isEmpty();
+}
+
+-------------------------------------------------------
+
+New instances of this class hereby are created using a fluent builder:
+
+[source,java]
+-------------------------------------------------------
+Configuration config = ...;
+ConfigurationChange change = ConfigurationChangeBuilder.of(config)
+ .addChange("MyKey", "newValue")
+ .removeKeys("myRemovedKey").build();
+-------------------------------------------------------
+
+Also it is possible to directly compare 2 instances of configurations to create a matching +ConfigurationChange+
+instance:
+
+[source,java]
+Comparing 2 configurations
+-------------------------------------------------------
+Configuration config = ...;
+Configuration changedConfig = ...;
+ConfigurationChange change = ConfigurationChangeBuilder.of(config)
+ .addChanges(changedConfig).build();
+-------------------------------------------------------
+
+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+:
+
+[source,java]
+.Implementing a ConfigChangeListener
+-------------------------------------------------------
+public final class MyConfigChangeListener implements ConfigChangeListener<ConfigurationChange>{
+
+ private Configuration config = ConfigurationProvider.getConfiguration();
+
+ public void onConfigEvent(ConfigEvent<?> event){
+ if(event.getResourceTspe()==Configuration.class){
+ if(event.getConfiguration()==config){
+ // do something
+ }
+ }
+ }
+
+}
+-------------------------------------------------------
+
+You can *register* your implementation in 2 ways:
+
+. Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+
+. Automatically by registering your listener using the +ServiceLoader+ under
+ +META-INF/services/org.apache.tamaya.events.ConfigEventListener+
+
+
+=== Modelling PropertySource Changes
+
+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 a +ConfigurationChange+ reflected by the classes +PropertySourceChange,
+PropertySourceChangeBuilder+.
+
+
+=== Modelling Configuration Context Changes
+
+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:
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigurationContextChange implements ConfigEvent<ConfigurationContext>, Serializable{
+
+ public static ConfigurationContextChange emptyChangeSet();
+
+ @Override
+ public ConfigurationContext getResource();
+ @Override
+ public Class<ConfigurationContext> getResourceType();
+ @Override
+ public String getVersion();
+ @Override
+ public long getTimestamp();
+
+ // specific methods
+ public Collection<PropertySourceChange> getPropertySourceChanges();
+ public Collection<PropertySourceChange> getPropertySourceUpdates();
+ public Collection<PropertySource> getRemovedPropertySources();
+ public Collection<PropertySource> getAddedPropertySources();
+ public Collection<PropertySource> getUpdatedPropertySources();
+ public boolean isAffected(PropertySource propertySource);
+ public boolean isEmpty();
+}
+-------------------------------------------------------
+
+Similar to the +ConfigurationChange+ class you also must use a +ConfigurationContextChangeBuilder+ to create instances
+of +ConfigurationContextChange+.
+
+=== The ConfigEventManager Singleton
+
+Main entry point of the events module is the +ConfigEventManager+ singleton class, which provides static accessor
+methods to the extension's functionality:
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigEventManager {
+
+ private ConfigEventManager() {}
+
+ public static void addListener(ConfigEventListener l);
+ public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
+ public static void removeListener(ConfigEventListener l);
+ public static <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
+ public static <T extends ConfigEvent>
+ Collection<? extends ConfigEventListener> getListeners();
+ public static <T extends ConfigEvent>
+ Collection<? extends ConfigEventListener> getListeners(Class<T> type);
+
+ public static <T> void fireEvent(ConfigEvent<?> event);
+ public static <T> void fireEventAsynch(ConfigEvent<?> event);
+
+ public static void enableChangeMonitoring(boolean enable);
+ public static boolean isChangeMonitoring();
+ public long getChangeMonitoringPeriod();
+ public void setChangeMonitoringPeriod(long millis);
+
+}
+-------------------------------------------------------
+
+Looking at the methods listed above you see that there is more functionality worth to be mentioned:
+
+* +ConfigCHangeListeners+ can be registered either _globally_ or for a certain _event type_ only.
+* +ConfigEvents+ can be published within the same thread, or asynchronously.
+
+
+==== Monitoring of configuration changes
+
+The +ConfigEventManager+ also supports active monitoring of the current configuration to trigger corresponding change
+events to listeners registered. This feature is activated by default, but can be deactivated optionally. Nevertheless
+this feature is quite handy, since regularly polling your local +Configuration+ for any kind of changes is much
+more simpler than implementing change management on the +PropertySource+ level. With this feature you can easily
+implement also remote property source, which can deliver different configuration based on any changes done remotedly
+on another node in your system. If such a change happened Tamaya identifies it and triggers corresponding
++ConfigurationChange" events automatically. Similarly changes in a configuration tree, can actively identified and
+broadcasted to the targeting nodes automatically.
+
+
+=== Freezing Configurations and PropertySources
+
++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 *freeze* instances of these types. Freezing hereby means
+
+* all key/values are read-out by calling the +getProperties()+ method.
+* a meta data entry is added of the form +[meta]frozenAt=223273777652325677+, whichdefines the UTC timestamp in
+ milliseconds when this instance was frozen.
+
+In code this is done easily as follows:
+
+[source,java]
+.Freezing the current Configuration
+--------------------------------------------------
+Configuration frozenConfig = FrozenConfiguration.of(ConfigurationProvider.getConfiguration());
+--------------------------------------------------
+
+... and similarly for a +PropertySource+:
+
+[source,java]
+.Freezing the current Configuration
+--------------------------------------------------
+PropertySource frozenSource = FrozenPropertySource.of(ConfigurationProvider.getConfiguration());
+--------------------------------------------------
+
+
+=== Modelling of an observing PropertySourceProvider.
+
+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+, which produces one +PropertySource+ (at least) per
+file detected. The events module provides a base provider implementation that
+
+* observes all changes in a +Path+
+* tries to reevaluate corresponding resources based on the +ConfigurationFormats+ supported.
+* it creates an instance of +ConfigurationContextChange+ reflecting the changed +ConfigurationContext+ and triggers
+ this event by calling +ConfigEventManager.fireEvent(contextChange);+.
+
+Additionally this module registers an instance of +ConfigEventListener<ConfigurationContextChange+>+, which listenes to
+these events. If such an event is triggered the listener tries to apply the changes by
+
+. accessing the current +Configuration+ and its +ConfigurationContext+
+. checking if the event is affecting the current +ConfigurationContext+.
+. in the case the current context is affected, based on the current +ConfigurationContext+ a new context is created,
+ whereas
+ .. all +PropertySources+ provided by this provider implementation type are removed.
+ .. the new +PropertySources+ loaded are added.
+. Finally the listener tries to apply the new +ConfigurationContext+ by calling the corresponding API methods of the
+ +ConfigurationProvider+:
+
+[source,java]
+--------------------------------------------------
+try {
+ ConfigurationProvider.setConfigurationContext(newContext);
+} catch (Exception e) {
+ LOG.log(Level.INFO, "Failed to update the current ConfigurationContext due to config model changes", e);
+}
+--------------------------------------------------
+
+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.
+
+
+=== SPIs
+
+This component also defines an additional SPI, which allows to adapt the implementation of the main +ConfigEventManager+
+singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided
+simple SE based implementation. As normal, implementation mus be registered using the current +ServiceContext+
+active, by default using the Java +ServiceLoader+ mechanism.
+
+[source,java]
+.SPI: ConfigEventSpi
+--------------------------------------------------
+public interface ConfigEventManagerSpi {
+
+ <T> void addListener(ConfigEventListener l);
+ <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
+ void removeListener(ConfigEventListener l);
+ <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
+ Collection<? extends ConfigEventListener> getListeners();
+ Collection<? extends ConfigEventListener> getListeners(Class<? extends ConfigEvent> eventType);
+
+ void fireEvent(ConfigEvent<?> event);
+ void fireEventAsynch(ConfigEvent<?> event);
+
+ long getChangeMonitoringPeriod();
+ void setChangeMonitoringPeriod(long millis);
+ boolean isChangeMonitorActive();
+ void enableChangeMonitor(boolean enable);
+}
+--------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_filter.adoc b/content/extensions/mod_filter.adoc
new file mode 100644
index 0000000..30c950d
--- /dev/null
+++ b/content/extensions/mod_filter.adoc
@@ -0,0 +1,135 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Integration with etcd (Core OS)
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== COnfiguration Filtering (Extension Module)
+=== Overview
+
+The Tamaya filter module provides a simple singleton accessor that allows to explicitly add +PropertyFilter+ instances
+active on the current thread only. This can be very useful in many scenarios. Additionally this module adds
+standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed
+explcitily no filtering is applied and everything is visible.
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-filter</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Tamaya Filter comes basically with 1 artifact:
+
+* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +PropertyFilter+
+instances on the current thread.
+* The +org.apache.tamaya.filter.DefaultMetdataFilter+ is a +PropertyFilter+ with hides all entries starting with
+ an underscore ('_'), when a full property map is accessed.
+
+
+=== The ConfigurationFilter
+
+The accessor mentioned implements the API for for adding 1PropertyFilters+ to the current thread (as thread local):
+
+[source, java]
+-----------------------------------------------
+public final class ConfigurationFilter implements PropertyFilter{
+
+ ...
+
+ /**
+ * Seactivates metadata filtering also on global map access for this thread.
+ * @see #clearFilters()
+ * @param active true,to enable metadata filtering (default).
+ */
+ public static void setMetadataFilter(boolean active);
+
+ /**
+ * Access the filtering configuration that is used for filtering single property values accessed.
+ * @return the filtering config, never null.
+ */
+ public static ProgrammableFilter getSingleFilters();
+
+ /**
+ * Access the filtering configuration that is used for filtering configuration properties accessed as full
+ * map.
+ * @return the filtering config, never null.
+ */
+ public static ProgrammableFilter getMapFilters();
+
+ /**
+ * Removes all programmable filters active on the current thread.
+ */
+ public static void clearFilters();
+
+ ...
+
+}
+-----------------------------------------------
+
+For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+
+is part of this module, So you can add a customized filter as follows:
+
+[source, java]
+-----------------------------------------------
+try{
+ ConfigurationFilter.getMapFilters().addFilter(new RegexPropertyFilter("\\_.*"));
+
+ // do your code with filtering active
+}
+finally{
+ // cleanup
+ ConfigurationFilter.clearFilters();
+}
+-----------------------------------------------
+
+The +ProgrammableFilter+ is a simple structure just providing some handy accessors to the dynamic thread-local
+managed filters:
+
+[source, java]
+-----------------------------------------------
+public final class ProgrammableFilter implements PropertyFilter{
+
+ public void addFilter(PropertyFilter filter);
+ public void addFilter(int pos, PropertyFilter filter);
+ public PropertyFilter removeFilter(int pos);
+ public void clearFilters();
+ public void setFilters(PropertyFilter... filters);
+ public void setFilters(Collection<PropertyFilter> filters);
+ public List<PropertyFilter> getFilters();
+
+}
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_formats.adoc b/content/extensions/mod_formats.adoc
new file mode 100644
index 0000000..1cd1679
--- /dev/null
+++ b/content/extensions/mod_formats.adoc
@@ -0,0 +1,243 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Formats
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Formats (Extension Module)
+=== Overview
+
+Tamaya Formats is an extension module. Refer to the link:modules.html[extensions documentation] for further details.
+
+Tamaya Formats provides an abstraction for configuration formats provding the following benefits:
+
+* Parsing of resources in can be implemented separately from interpreting the different aspects/parts parsed. As an
+ example a file format can define different sections. Depending on the company specific semantics of the sections
+ a different set of +PropertySource+ instances must be created.
+* Similarly the configuration abstraction can also be used as an interface for integrating Tamaya with alternate
+ frameworks that provide logic for reading configuration files, such as Apache commons.configuration.
+
+=== 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:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-formats</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+The module automatically registers an according +PropertyFilter+ that is automatically called, whenever a value
+is accessed.
+
+=== The Idea
+
+Formats should be reusable, meaning you should have to write a format parser only once and then be able to map the data read into whatever
+data structure (in our cases: property sources).
+
+==== ConfigurationData
+
+Configuration formats can be very different. Some are simpley key/value pairs, whereas other also consist of multiple sections (e.g. ini-files) or
+hierarchical data (e.g. yaml, xml). This is solved in Tamaya by mapping the configuration read into a normalized intermediary format called
++ConfigurationData+:
+
+[source,java]
+.ConfigurationData
+-------------------------------------------------------
+public final class ConfigurationData {
+
+ public ConfigurationFormat getFormat();
+ public String getResource();
+
+ public Set<String> getSectionNames();
+ public Map<String,String> getSection(String name);
+ public Map<String,Map<String,String>> getSections();
+
+ public boolean hasDefaultProperties();
+ public Map<String,String> getDefaultProperties();
+
+ public Map<String,String> getCombinedProperties();
+ public boolean hasCombinedProperties();
+
+ public boolean isEmpty();
+}
+-------------------------------------------------------
+
+In detail the data read from a file is organized into _sections_ as follows:
+
+* with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed.
+* properties can be owned by
+ ** named sections
+ ** an (unnamed) default section
+* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple
+ named sections, depending on the configuration format.
+* The method +getSectionNames()+ returns a set of all section names.
+* With +getSection(String name)+ a named section can be accessed.
+* With +getDefaultSection()+ the default section can be accessed.
+* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of
+ ** all entries from the default section, without any changes.
+ ** all entries from named sections, where the key for each entry is prefix with the section name and a dot separator.
+* The configuration format used determines the mapping of configuration data read into this structure. The format
+ implementation can as well provide alternate implementations of how the data read should be mapped into the
+ combined properties map.
+
+Now for the conversion of +ConfigurationData+ into a +PropertySource+ different default approaches are used:
+
+. The +ConfigurationFormat+ that read the data can provide the (combined) properties accessible from
+ +getProperties()+ explcitly, which can be used to initialize a single +PropertySource+ containing the data read.
+. If the format did not set the final properties, but only a default section is present this default section
+ can be directly returned as combined properties.
+. In all other cases a properties can be uniquely mapped into one single properties Map, by prefixing all keys of each
+ section present with the (unique) section name and a '.' separator.
+
+Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
+resulting +PropertySource+ can have different semnatics, especially for the +PropertySources+ ordinal. Also section
+names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats
+with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no useful default mapping
+can be defined. In such cases this functionality must be implemented in a _mapData_ method, which converts
+the normalized +ConfigData+ read to the appropriate collection of +PropertySource+ instances:
+
+
+==== ConfigurationFormat
+
+A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and
+creates a corresponding +ConfigurationData+ instance.
+
+[source,java]
+-------------------------------------------------------
+public interface ConfigurationFormat {
+
+ public String getName();
+ boolean accepts(URL url);
+ ConfigurationData readConfiguration(String resource, InputStream inputStream);
+}
+-------------------------------------------------------
+
+
+Normally you need to map the resulting +ConfigurationData+ to one or multiple +PropertySources+. In case, where the
+properties provided match exactly the extected properties a +FlattenedDefaultPropertySource+ is provided out-of-the-box.
+If the exact mapping must be overridden, you can simply override the property source's initialize method to adapt the
+mapping:
+
+[source,java]
+-------------------------------------------------------
+ConfigurationData data = ...;
+FlattenedDefaultPropertySource ps = new FlattenedDefaultPropertySource(data){
+ protected Map<String, String> populateData(ConfigurationData data) {
+ ...
+ }
+};
+-------------------------------------------------------
+
+
+=== How to tranform ConfigurationData into a PropertySource
+
+The Tamaya main building block for configuration properties is the +PropertySource+ interface. You have several
+options to implement this tranformation:
+
+. You can simply map the properties returned by +getCombinedProperties()+ and use them as properties returned by a
+ wrapping property source. Since this use case is common for all kind of non hierarchic configuration formats it
+ is directly supported by the +FlattenedDefaultPropertySource+ class.
+. When the +ConfigurationFormat+ is more complex, multiple 'sections' are common. What a section exactly is depends on
+ the concrete format only. The +ConfigurationFormat+ should provide detailed information how the data read is
+ mapped to default properties and sections and how it is assembled into the +combinedProperties+ map. Also here
+ the +FlattenedDefaultPropertySource+ class can help you with its default mapping. Nevertheless in some cases it is
+ necessary to write an explicit mapping, e.g. when
+ . different sections must be mapped to multiple +PropertySources+, with optionally fixed ordinals.
+ . sections must be cross-checked and combined into new properties, or into several +PropertySources+.
+ . other complex mapping requirements apply.
+
+=== Examples
+
+==== Mapping ini-Files
+
+Consider the following ini-file:
+
+[source,listing]
+.Example.ini
+-------------------------------------------------------
+a=valA
+a.b=valB
+
+[section1]
+aa=sectionValA
+aa.b.c=SectionValC
+
+[section2]
+a=val2Section2
+-------------------------------------------------------
+
+This file content coud be mapped to the following structure:
+
+[source,listing]
+.Mapping of Example.ini
+-------------------------------------------------------
+a=valA
+a.b=valB
+section1.valA=sectionValA
+section1.a.b.c=SectionValC
+section2.a=val2Section2
+-------------------------------------------------------
+
+Nevertheless from the +ConfigurationData+ instance a more complex algorithm can access all the different parts:
+
+* the_default_ properties (a, a.b)
+* the section +section1+, with properties +aa, aa.b.c+
+* the section +section2+, qith properties +a+
+
+
+==== Mapping xml-Files
+
+The same concept can also be applied to xml-files. Consider the following configuration file:
+
+[source,xml]
+.Example.conf
+-------------------------------------------------------
+<config>
+ <default>
+ <a>valA</a>
+ <a.b>valB</a.B>
+ </default>
+
+ <section id="section1">
+ <param id="aa">sectionValA</aa>
+ <param id="aa.b.c">SectionValC</aa.b.c>
+ </section>
+ <section id="section2">
+ <param id="a">val2Section2</aa>
+ </section>
+</config>
+-------------------------------------------------------
+
+This file basically describes the same configuration as the ini-based version we have seen before. The formats
+module hereby ships with 3 format classes:
+
+* +PropertiesFormat+ providing support for .properties files.
+* +PropertiesXmlFormat+ providing support for xml.property files.
+* +IniConfiguratonFormat+ providing support for xml.property files.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_functions.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_functions.adoc b/content/extensions/mod_functions.adoc
new file mode 100644
index 0000000..a7e891c
--- /dev/null
+++ b/content/extensions/mod_functions.adoc
@@ -0,0 +1,124 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Functions
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+[[Core]]
+== Tamaya Functions (Extension Module)
+=== Overview
+
+Tamaya Functions is an extension module. Refer to the link:modules.html[extensions documentation] for further details.
+
+Tamaya Functions provides several functional extensions using the +ConfigOperator,ConfigQuery+ extension points. Most
+functional extension are accessible from the +ConfigurationFunction+ singleton. When importing its methods statically
+one can use the methods to achieve some interesting effects, e.g.
+
+[source,java]
+-------------------------------------------------------------------
+import static org.apache.tamaya.functions.ConfigurationFunctions.*;
+
+Set<String> sections = ConfigurationProvider.getConfiguration().with(areas("a", false).with(transitiveAreas());
+-------------------------------------------------------------------
+
+The expression above returns all fully qualified section names that are child sections of the root section 'a'.
+So given the entries +a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4+ the reult would be +a, a.a, a.b, a.b.c+.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+For using the functionality shown in this document you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-functions</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Provided Functions
+
+==== Functions on +ConfigurationFunctions+
+
+The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton.
+
+* *ConfigOperator filter(PropertyMatcher matcher)* creates a +ConfigOperator+ that creates a +Configuration+
+ containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only
+ the _key_, but also the _value_.
+* *ConfigOperator map(KeyMapper keyMapper)* creates a +ConfigOperator+ that maps the keys as defined
+ by the given _keyMapper_.
+* *ConfigOperator section(String section)* creates a +ConfigOperator+ that creates a +Configuration+ containing only
+ entries that are direct or indirect members of the given section.
+* *ConfigOperator section(String areaKey, boolean stripKeys)* creates a +ConfigOperator+ that creates a +Configuration+
+ containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine
+ if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.
+* *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member
+ of a given section.
+* *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given
+ _key_ is a direct or indirect member of at least one of the given _sectionKeys_.
+* *ConfigQuery<Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
+ also have parameters present).
+* *ConfigQuery<Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
+ including the transitive closure of sections.
+* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
+ qualified section names that are selected by the given _predicate_.
+* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
+ qualified section names that are selected by the given _predicate_, including the transitive closure of sections
+ identified.
+* *ConfigOperator sectionsRecursive(String... sectionKeys)* provides a +ConfigOperator+ that filters all sections identified
+ by the given _sectionKeys_ and its child sections.
+* *ConfigOperator sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +ConfigOperator+
+ that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to
+ determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or
+ absolute (filtering only).
+* *ConfigQuery<String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
+ representation.
+
+
+==== Functions on +PropertySourceFunctions+
+
+The following sections explain the provided functions defined by +PropertySourceFunctions+ singleton.
+
+* *PropertySource addMetaData(PropertySource propertySource, Map<String,String> metaData)* Creates a new +PropertySource+
+ with the given metadata added.
+* *boolean isKeyInSection(String key, String sectionKey)* Checks if the given _key_ is a direct or indirect member of
+ one of the given _sectionKey_.
+* *boolean isKeyInSections(String key, String... sectionKeys)* Checks if the given _key_ is a direct or indirect member of
+ one of one of the given _sectionKeys_.
+* *Set<String> sections(Map<String, String> properties)* Extracts the sections from the given properties.
+* *Set<String> transitiveSections(Map<String, String> properties)* Extracts the transitive sections from the given
+ properties.
+* *Set<String> sections(Map<String, String> properties, final Predicate<String> predicate)* Extracts the sections
+ from the given properties, also filtering with the given predicate.
+* *Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate)* Extracts the transitive
+ sections from the given properties, also filtering with the given predicate.
+* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +PropertySource+
+ only containing the sections that a direct or indirect children of the given _sectionKeys_.
+* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +PropertySource+
+ only containing the sections that a direct or indirect children of the given _sectionKeys_. With _stripKeys_ one can
+ select of the returned values should be relative to its selection of be fully qualified.
+* *String stripSectionKeys(String key, String... sectionKeys)* This function strips away the matching section key as given
+ in _sectionKeys_ from a given _key_.
[3/5] incubator-tamaya-site git commit: TAMAYA-186: Add existing
pages.
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_injection.adoc b/content/extensions/mod_injection.adoc
new file mode 100644
index 0000000..dc68626
--- /dev/null
+++ b/content/extensions/mod_injection.adoc
@@ -0,0 +1,445 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Injection
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Injection (Extension Module)
+=== Overview
+
+Tamaya Injection is an extension module. Refer to the link:modules.html[extensions documentation] for further details
+about modules.
+
+Tamaya Injection provides functionality for injecting configured values into beans, or creating configuration
+template instances.
+
+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.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+Basically Tamaya's injection API is deployed as API artifact:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection-api</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+To use injection with Java SE you must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+Similarly there are other injection implementations available, targetig platforms such as
+
+* Spring, Spring Boot
+* Java EE/CDI
+* OSGI, Apache Felix/Apache Karaf
+
+
+=== Core Concepts
+
+Basically you annotate fields or methods in your beans with +@Config+ to enable configuration injection. Tamaya
+additionally defines further annotations that allo you to define additional aspects such as default values, custom
+converters etc. The following example illustrates the basic functionality:
+code snippet:
+
+[source,java]
+.Annotated Example Class
+--------------------------------------------
+package foo.bar;
+
+public class ConfiguredClass{
+
+ // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
+ private String testProperty;
+
+ // Trying to resolve mutiple keys, with a default value, if none could be resolved
+ @Config({"a.b.c.key1","a.b.legacyKey",area1.key2"}, defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
+ String value1;
+
+ // Typical case
+ @Config("a.b.c.key2")
+ private int value2;
+
+ // resolved by default as foo.bar.ConfiguredClass.accessUrl
+ // Using a (default) String -> URL converter
+ @Config(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
+ private URL accessUrl;
+
+ // Config injection disabled for this property
+ @NoConfig
+ private Integer int1;
+
+ // Overriding the String -> BigDecimal converter with a custom implementation.
+ @Config("BD")
+ @WithPropertyConverter(MyBigDecimalRoundingAdapter.class)
+ private BigDecimal bigNumber;
+
+ ...
+}
+--------------------------------------------
+
+
+When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
+this feature a class must be annotated with +@ConfigAutoInject+:
+
+[source, java]
+. An autoinjected bean class
+--------------------------------------------
+package a.b;
+
+@ConfigAutoInject
+public final class Tenant{
+ private int id;
+ private String name;
+ private String description;
+ @NoConfig // prevents auto injection for this field
+ private String id2;
+
+ public int getId(){
+ return id;
+ }
+ public String getName(){
+ return name;
+ }
+ public String getDescription(){
+ return description;
+ }
+}
+--------------------------------------------
+
+These examples do not show all possibilities provided. Configuring instance of these
+class using Tamaya is very simple: Just pass the instance to Tamaya to let
+Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible):
+
+[source,java]
+.Configuring the +ConfiguredClass+ Instance
+--------------------------------------------
+ConfiguredClass classInstance = new ConfiguredClass();
+ConfigurationInjector.configure(configuredClass);
+
+Tenant tenant = new Tenant();
+ConfigurationInjector.configure(tenant);
+--------------------------------------------
+
+NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
+with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
+documentation.
+
+
+=== The Annotations in detail
+==== The ConfigurationInjector
+
+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
+hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
+tries to determine configuration for each property of an instance passed, using the following resolution policy:
+
+Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
+[source, listing]
+--------------------------------------------
+a.b.MyClass.myField
+a.b.MyClass.my-field
+MyClass.myField
+MyClass.my-field
+myField
+my-field
+--------------------------------------------
+
+So given the following properties:
+
+[source, properties]
+--------------------------------------------
+a.b.Tenant.id=1234
+Tenant.description=Any kind of tenant.
+name=<unnamed>
+--------------------------------------------
+
+
+==== Accessing ConfiguredItemSupplier instances
+
+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+:
+
+[source, java]
+--------------------------------------------
+ConfiguredItemSupplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
+ new ConfiguredItemSupplier<Tenant>(){
+ public Tenant get(){
+ return new Tenant();
+ }
+});
+--------------------------------------------
+
+With Java 8 it's even more simpler:
+
+[source, java]
+--------------------------------------------
+ConfiguredItemSupplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
+ Tenant::new);
+--------------------------------------------
+
+Hereby this annotation can be used in multiple ways and combined with other annotations such as +@DefaultValue+,
++@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+.
+
+==== Minimal Example
+
+To illustrate the mechanism below the most simple variant of a configured class is given:
+
+[source,java]
+.Most simple configured class
+--------------------------------------------
+pubic class ConfiguredItem{
+ @Config
+ private String aValue;
+}
+--------------------------------------------
+
+When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
+the following is happening:
+
+* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
+* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
+ keys are possible).
+* if not successful, an error is thrown (+ConfigException+)
+* On success, since no type conversion is involved, the value is injected.
+
+==== Using @DefaultValue
+
+In the next example we explicitly define the property value:
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
+
+ @Config({"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
+ private String aValue;
+}
+--------------------------------------------
+
+==== Inject a DynamicValue Property
+
+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.
+
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
+
+ @Config({"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
+ private DynamicValue aValue;
+}
+--------------------------------------------
+
+The +DynamicValue+ provides you the following functionality:
+
+[source,java]
+--------------------------------------------
+public interface DynamicValue<T> {
+
+ enum UpdatePolicy{
+ IMMEDIATE,
+ EXPLCIT,
+ NEVER,
+ LOG_AND_DISCARD
+ }
+
+ T get();
+ T getNewValue();
+ T evaluateValue();
+ T commitAndGet();
+ void commit();
+ void discard();
+ boolean updateValue();
+
+ void setUpdatePolicy(UpdatePolicy updatePolicy);
+ UpdatePolicy getUpdatePolicy();
+ void addListener(PropertyChangeListener l);
+ void removeListener(PropertyChangeListener l);
+
+ boolean isPresent();
+ T orElse(T other);
+ T orElseGet(ConfiguredItemSupplier<? extends T> other);
+ <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
+
+}
+--------------------------------------------
+
+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+:
+
+* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
+ is automatically applied without any further notice.
+* +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()+.
+* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
+* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
+
+Summarizing a +DynamicValue+ allows you
+
+* to reload actively updates of configured values.
+* update implicitly or explicitly all changes on the value.
+* add listeners that observe changes of a certain value.
+
+Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+. Hereby the value of the
+instance is not changed.
+
+
+==== Ommitting Injection using @NoConfig
+
+Adding the @NoConfig annotation prevents a field or method to be auto-injected from
+configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with auto-confiuration
+turned on as follows:
+
+[source,java]
+--------------------------------------------
+@ConfigAutoInject
+pubic class ConfiguredItem{
+
+ @NoConfig
+ private transient int sum;
+
+ private String a;
+ private String b;
+ Private String c;
+}
+--------------------------------------------
+
+In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
+configuration.
+
+==== Adding custom operators using @WithConfigOperator
+
+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.
+
+[source,java]
+--------------------------------------------
+
+@WithConfigOperator(MyConfigView.class)
+pubic class ConfiguredItem{
+
+ @Config
+ private String a;
+
+}
+--------------------------------------------
+
+
+==== Adding custom property converters using @WithPropertyConverter
+
+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, config models, decryption.
+
+[source,java]
+--------------------------------------------
+
+pubic class ConfiguredItem{
+
+ @WithPropertyConverter(MyPropertyConverter.class)
+ @Config
+ private String a;
+
+}
+--------------------------------------------
+
+
+==== Defining the loading policy to be applied to configured values using @WithLoadPolicy
+
+The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The +LoadPolicy+
+enum hereby defines the various loading modes.
+
+[source,java]
+--------------------------------------------
+
+@WithLoadPolicy(LoadPolicy.NEVER)
+pubic class BootTimeStableConfig{
+
+ @WithPropertyConverter(MyPropertyConverter.class)
+ @Config
+ private String a;
+
+}
+--------------------------------------------
+
+
+=== Configuration Events
+
+Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
+event backend in use, if and how events are published:
+
+* when you have the CDI extension active events are published using the default CDI event mechanism.
+* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
+* if no event delegation is available no events are published.
+
+The event published is very simple:
+
+[source,java]
+--------------------------------------------
+public interface ConfiguredType {
+ Class getType();
+ String getName();
+ public Collection<ConfiguredField> getConfiguredFields();
+ Collection<ConfiguredMethod> getConfiguredMethods();
+ void configure(Object instance, Configuration config);
+}
+
+
+public interface ConfiguredField {
+ Class<?> getType();
+ Collection<String> getConfiguredKeys();
+ String getName();
+ String getSignature();
+ Field getAnnotatedField();
+ void configure(Object instance, Configuration config);
+}
+
+public interface ConfiguredMethod {
+ Collection<String> getConfiguredKeys();
+ Class<?>[] getParameterTypes();
+ Method getAnnotatedMethod();
+ String getName();
+ String getSignature();
+ void configure(Object instance, Configuration config);
+}
+----------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_jodatime.adoc b/content/extensions/mod_jodatime.adoc
new file mode 100644
index 0000000..e806af6
--- /dev/null
+++ b/content/extensions/mod_jodatime.adoc
@@ -0,0 +1,64 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: JodaTime
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+[[Core]]
+== Tamaya JodaTime (Extension Module)
+
+=== Overview
+
+Tamaya JodaTime is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time]
+in conjunction with Tamaya. Tamaya JodaTime defines some additional property
+converters to retrieve Joda-Time types from a given configuration.
+
+Refer to the link:modules.html[extensions documentation] for further details
+about modules.
+
+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:
+
+[source, listing]
+-----------------------------------------------
+<dependency>
+ <grooupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-jodatime</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+After adding this dependency to your project you can retrieve
+Joda-Time based values directly from a given configuration.
+
+[source,java]
+-----------------------------------------------
+Configuration configuration = ConfigurationProvider.getConfiguration();
+
+DateTime pit = configuration.get("pointInTime", DateTime.class)
+-----------------------------------------------
+
+=== Specifying date and time values
+
+To be written.
+
+=== Specifing periods and durations
+
+To be written.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_json.adoc b/content/extensions/mod_json.adoc
new file mode 100644
index 0000000..77c5b7d
--- /dev/null
+++ b/content/extensions/mod_json.adoc
@@ -0,0 +1,77 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Builder
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[BuilderCore]]
+== Tamaya JSON (Extension Module)
+=== Overview
+
+The Tamaya json module provides support for reading configuration using the JSON format:
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-json</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Reading configuration in JSON
+
+For reading JSON based onfiguration most easily a +JSONFormat+ can be provided:
+
+[source, java]
+-----------------------------------------------
+ConfigurationData dataRead = ConfigurationFormats.readConfig(
+ getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
+-----------------------------------------------
+
+=== Examples
+
+The JSON module adds instances of +ConfigurationFormat+ so JSON configuration can be read and mapped to the
+according property maps. E.g. the following file is a simple and correct JSON configuration:
+
+[source,listing]
+----------------------------------------------------------------
+{
+ "a" : "A",
+ "b" : "B",
+ "c" : "C",
+ "d" : {
+ "o" : "O",
+ "p" : "P"
+ }
+}
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_management.adoc b/content/extensions/mod_management.adoc
new file mode 100644
index 0000000..f8050ec
--- /dev/null
+++ b/content/extensions/mod_management.adoc
@@ -0,0 +1,108 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: JMX Management Access
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[ExtModel]]
+== Tamaya Management (JMX Support) (Extension Module)
+=== Overview
+
+The Tamaya management module provides support for registering a JMX management bean for accessing configuration.
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-management</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The ManagedConfigMBean bean
+
+The management model defines the MBean of type +ManagedConfigMBean+ as follows:
+
+
+[source,java]
+-----------------------------------------------------------------------------
+public interface ManagedConfigMBean {
+ String getJsonConfigurationInfo();
+ String getXmlConfigurationInfo();
+ Map<String, String> getConfiguration();
+ Map<String, String> getSection(String area, boolean recursive);
+ Set<String> getSections();
+ Set<String> getTransitiveSections();
+ boolean isSectionExisting(String area);
+ default boolean isSectionEmpty(String area);
+}
+-----------------------------------------------------------------------------
+
+* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the
+current configuration.
+* +getConfiguration+ access the current configuration properties.
+* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query
+ will not only return direct children, but also recursively walk down all subsection of the
+ given section key.
+* +getSections+ returns all current known section names.
+* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single
+ entries to the set as well.
+* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
+ section keys.
+
+=== Registering the ManagedConfigMBean
+
+For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the
+following static methods are available:
+
+[source,java]
+-----------------------------------------------------------------------------
+public final class ConfigManagementSupport{
+
+ private JMXSupport(){}
+
+ public static ObjectName registerMBean();
+ public static ObjectName registerMBean(String context);
+ public static ObjectName unregisterMBean();
+ public static ObjectName unregisterMBean(String context);
+}
+-----------------------------------------------------------------------------
+
+* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+
+ and registers it. Optionally an additional _context_ parameter can be passed, which allows
+ to register the management bean for different classloaders, e.g. for different
+ ears.
+* +unregisterMBean+ does the oppsite than registering obviously.
+
+NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the
+ +ServiceContextManager+. So you can replace the bean implementation by registering your
+ overriding implementation using the current +ServiceContext+ (by default using
+ +java.util.ServiceLoader+ and +@Priority+ annotation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_metamodel-staged.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_metamodel-staged.adoc b/content/extensions/mod_metamodel-staged.adoc
new file mode 100644
index 0000000..7482d1a
--- /dev/null
+++ b/content/extensions/mod_metamodel-staged.adoc
@@ -0,0 +1,74 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Staged PropertySources
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Metamodel: Staged PropertySources (Extension Module)
+=== Overview
+
+The Tamaya Staged PropertySources extension provides a base class and default implementation for loading
+multistaged configuration easily from a common configuration location.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext.metamodels</groupId>
+ <artifactId>tamaya-metamodel.staged</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+The component will not register any components. The component basically provides the following options:
+
+* Use it as default configuration extension. Hereby you should define your stages in use by setting the
+ +env.STAGE+ system property with the stages to be loaded in order of precedence (most significant last),
+ e.g. +sys-env,DEFAULTS,TEST,DEVELOPMENT. _Additionally_ you must register
+ +org.apache.tamaya.staged.StagedConfigPropertiesProvider+ as in
+
+--------------------------------------------------------------
+META-INF
+|_service
+ |_org.apache.tamaya.spi.PropertySourceProvider
+--------------------------------------------------------------
+
+Tamaya will then load .properties files from +System.getenv(),
+classpath:DEFAULTS.properties, classpath:TEST.properties+ and
++classpath:DEVELOPMENT.properties+
+
+* For more advanced requirements, such as alternate locations, patterns or formats, you can also extend one of the
+ provided classes (+org.apache.tamaya.staged.StagedConfigPropertiesProvider+,
+ ** +BaseStagedPropertySourceProvider+). Extending provides features such as:
+
+ ** Defining a prefix for all entries provided/loaded.
+ ** Using alternate locations or formats.
+ ** Defining the ordinals used.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_model.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_model.adoc b/content/extensions/mod_model.adoc
new file mode 100644
index 0000000..2b05026
--- /dev/null
+++ b/content/extensions/mod_model.adoc
@@ -0,0 +1,467 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Model Documentation and Validation
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[ExtModel]]
+== Tamaya Model Documentation and Validation (Extension Module)
+=== Overview
+
+The Tamaya model module provides support for documenting configuration and validating configuration read and processed
+against this model. Documentation and config models can be provided in different ways:
+
+* as separate meta-model documents
+* by providers that check classes/packages for configuration annotations (planned)
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-model</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Describing the Configuration Meta-Model
+
+Basically configuration is modelled using key, value-pairs. Looking at a keys
++a.b.c.param1+ and +a.b.c.param2+ the following concepts can be used to defined/describe
+configuration:
+
+. the _configuration section:_ In our case this equals to +a.b.c+, which itself also includes the
+ transitive entries +a.b+ and +a+.
+. the _configuration parameter:_ Basically parameters are adressed using their fully qualified names,
+ which equals to the containing section name and the relative parameter name, separated by the dor separator.
+ In the above example +a.b.c.param1+ and +a.b.c.param2+ are the fully qualified parameter names.
+
+Now with only these 2 concepts a simple configuration meta-model can be defined as
+
+* a meta-model's name, used just for grouping different meta-models and entries to better separate
+ descriptions, e.g. in a management console or generated configuration documentation site.
+* a set of sections.
+* a set of parameters.
+* Both, sections (+.model.target=Section+) as well as parameter models (+.model.target=Parameter+)
+ ** can be modelled by a meta-data entry, by default +_my.config.key.model+.
+ ** may be required, or optional (+.model.required=true|false+)
+ ** may have an optional description
+* Parameters additionally have
+ ** a _type_ (+.model.type=Classname+), described by the fully qualified class name, into which any configured (String)
+ value must be convertable into. If no type is configured +java.ui.lang.String+ is assumed as default.
+ ** an optional regular expression that can be used to validate the +String+ values returned from a
+ configuration (+.model.expression=regexpression+).
+
+Given these concepts a configuration can be fully described. Entries that are not contained in one of the given
+sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of
+a section), are called _undefined_. Undefined parameters should be grouped with its parent section. Each section, as
+well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and
+only if
+
+. the section itself is (directly) _undefined_
+. the section is not a _super section_ of a defined section.
+
+As en example the section definition of +a.b.c+ also implicitly includes the sections +a.b+ and +a+ to be defined
+sections, despite the fact that section properties, such as description and custom configModels are not inherited to
+its parent, or child section.
+
+
+=== Defining Meta-Configuration Model
+
+The configuration meta-model is defined by simple configuration meta-data entries. The section for all model
+configuration by default is called +model+, which results in entries such as +_my.config.key.model.target=Section+.
+Within this section fully qualified configuration keys defines
+which part of the configuration is targeted by certain entries.
+
+==== Defining Sections
+
+First we start to define some configuration sections, the example below starts with the most important
+variants supported:
+
+[source,listing]
+-------------------------------------------------------------------------------
+# Metamodel information
+_model.provider=ConfigModel Extension
+
+# org.mycompany.root (optional section)
+_org.mycompany.root.model.target=Section
+_org.mycompany.root.model.description=Root section defining my company configuration.
+
+# org.mycompany.security (required section)
+_org.mycompany.security.model.target=Section
+_org.mycompany.security.model.required=true
+_org.mycompany.security.model.description=Security related settings.\
+ refer for further details to XXX.
+
+# minmal section
+_minimal.model.target=Section
+
+# custom validated section
+_validated.model.target=Section
+_validated.model.validator=org.apache.tamaya.model.TestValidator
+-------------------------------------------------------------------------------
+
+Above +org.mycompany.root+ transitively defines 3 sections:
+
+* org
+* org.mycompany
+* org.mycompany.root
+
+All sections are optional. Additionally the model above also defines a required section +org.mycompany.security+.
+Required sections are checked so the section is not empty. It is not checked for any specific parameter hereby,
+only the existance of any child parameter is validated.
+
+The _class_ attribute has to be defined for any section definition, because if not set a model entry is, by default,
+defined to be a parameter configModel entry. Given above the entry for the section +minimal+ shows such a minimal
+entry.
+
++validated+ defines a section, which is validated through a customizable validator. Hereby an ordered list of validators
+can be provided, separated by commas.
+
+
+==== Defining Parameters
+
+Similarly parameters also can be defined:
+
+[source,listing]
+-------------------------------------------------------------------------------
+# org.mycompany.root.name (required parameter)
+_org.mycompany.root.name.model.target=Parameter
+_org.mycompany.root.name.model.required=true
+_org.mycompany.root.name.model.description=The company's name, also used in the application's main header.
+
+# org.mycompany.security (required parameters)
+_org.mycompany.security.uid.model.required=true
+_org.mycompany.security.uid.model.description=The user id.
+_org.mycompany.security.realm.model.required=true
+_org.mycompany.security.realm.model.validator=org.apache.tamaya.model.RealmValidator
+_org.mycompany.security.realm.model.description=The security realm required.
+_org.mycompany.security.tokenid.model.description=The token id, if the token service is used (optional).
+
+# A minmal parameter
+_minimalClass.model.target=Class
+-------------------------------------------------------------------------------
+
+Similarly as when defining section also parameter entries define transitively its containing sections. E.g.
+the entry above for +org.mycompany.security.realm+ also defines the following sections (as optional).
+
+* org
+* org.mycompany
+* org.mycompany.security
+
+Additional entries for section, e.g. configModels to be done, can be added as described in the previous section,
+but are optional.
+
+Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it's
+parameter type to be defined. In the example above we define a parameter +minimalClass+ of type +Class+.
+Types hereby are fully qualified class names, whereas as 'java.ui.lang' for built-in language types can be
+ommitted.
+
+==== Model Locations
+
+By default the configuration model can be defined at the following locations:
+
+* +classpath*:META-INF/configmodel.properties+, separate to the current +Configuration+. This functionality is enabled
+ by default, but can be disabled by adding +org.apache.tamaya.model.default.enabled=false+ to your current
+ +Configuration+.
+* +implicitly as part of the current +Configuration+. THis can be disabled by setting
+ the +org.apache.tamaya.model.integrated.enabled+ configuration poarameter to +false+.
+* customized by configuring the +org.apache.tamaya.model.resources+ in the current +Configuration+. This
+ parameter allows to define the locations from where the model extension is trying to read the
+ model configuration. If the _resources extension_ is available in your system it is used to
+ evaluate the locations. If not the default +Classloader.getResources+ command is issued. Also it
+ is required that the _formats extension_ is available, since this is used to effectively read the
+ data. This extension also allows you to use alternate representation formats such as +ini, xml, yml, json+.
+
+
+=== Tracking Configuration Access
+
+The model module also allows tracking which code accesses configuration properties or configuration parameters.
+It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly
+ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length.
+The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+
+instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage
+statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+.
+
+Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+.
++ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status.
+
+The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing:
+
+* the access point (+fqn.ClassName#method(line: xxx)+).
+* the number of accesses
+* the first an last access
+* the values read
+* the access stacktrace (filtered by ignored packages).
+
+[source,java]
+-----------------------------------------------------------
+public final class Usage {
+ [...]
+ public String getKey();
+ public void clearMetrics();
+ public int getReferenceCount();
+ public int getUsageCount();
+ public Collection<AccessDetail> getAccessDetails(Class type);
+ public Collection<AccessDetail> getAccessDetails(Package pack);
+ public Collection<AccessDetail> getAccessDetails(String lookupExpression);
+ public Collection<AccessDetail> getAccessDetails();
+ public void trackUsage(String value);
+ public void trackUsage(String value, int maxTraceLength);
+
+
+ public static final class AccessDetail {
+ [...]
+ public void clearStats();
+ public long trackAccess(String value);
+ public long getAccessCount();
+ public String getAccessPoint();
+ public long getFirstAccessTS();
+ public long getLastAccessTS();
+ public String[] getStackTrace();
+ public Map<Long, String> getTrackedValues();
+ }
+
+}
+-----------------------------------------------------------
+
+With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main
+singleton for configuration statistics is defined as follows:
+
+[source,java]
+-----------------------------------------------------------
+public final class ConfigUsageStats{
+ public static Set<String> getIgnoredUsagePackages();
+ public static void addIgnoredUsagePackages(String... packageName);
+ public static void enableUsageTracking(boolean enabled);
+ public static Usage getUsage(String key);
+ public static Collection<Usage> getUsages();
+ public static void clearUsageStats();
+ public static Usage getUsageAllProperties();
+ public static boolean isUsageTrackingEnabled();
+ public static String getUsageInfo();
+}
+-----------------------------------------------------------
+
+==== Customizing the Stacktrage for Usage Reporting
+
+The stacktrace tracked by the system can be customized in several ways:
+
+* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names.
+* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a
+ negative value will disable stacktrace logging completelely.
+
+
+=== Accessing Usage Statistics
+
+Bascially usage statistics are available in two forms:
+
+* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+
+ singleton.
+* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics
+ can be obtained, as illustrated below (a snipped from the current test output):
+
+[source,listing]
+-----------------------------------------------------------
+Apache Tamaya Configuration Usage Metrics
+=========================================
+DATE: Sat Apr 30 21:51:09 CEST 2016
+
+220 <<all>>:
+ - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+3 java.version:
+ - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+ - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+
+-----------------------------------------------------------
+
+
+==== Programmatic API
+
+Basically the configModel module provides a simple API to access the defined +ConfigModel+ instances and
+validating the current +Configuration+ against the models as follows:
+
+[source,java]
+-----------------------------------------------------------
+public final class ConfigModelManager {
+
+ private ConfigModelManager() {}
+
+ public static Collection<ConfigModel> getModels();
+ public static Collection<ConfigModel> findModels(ModelType type, String namePattern);
+ public static <T extends ConfigModel> T getModel(String name, Class<T> modelType);
+ public static Collection<ConfigModel> findModels(String namePattern);
+
+ public static Collection<ValidationResult> validate();
+ public static Collection<ValidationResult> validate(boolean showUndefined);
+ public static Collection<ValidationResult> validate(Configuration config);
+ public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined);
+
+ public static void registerMBean();
+ public static void registerMBean(String context);
+
+}
+-----------------------------------------------------------
+
+This singleton allows to validate the current or any +Configuration+ instance. All the ConfigModels read also are
+available from the +getModels+ method. This models can be used to provide documentation, e.g. as part of a CLI interface
+or shown on a documentation web server.
+
+A +ConfigModel+ hereby is defined as one single part of configuration, typically corresponding to a specific concern
+of your system. As an example you can define different models for different modules or products plugged together.
+With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a
+single configuration source (e.g. for configuring the machine's IP address and subnet settings only once.
+
+[source,java]
+-----------------------------------------------------------
+public interface ConfigModel {
+
+ ModelTarget getType();
+ String getName();
+ String getProvider();
+ boolean isRequired();
+ String getDescription();
+ Collection<ValidationResult> validate(Configuration config);
+}
+-----------------------------------------------------------
+
+
+Hereby +ModelTarget+ defines more details on the kind of model:
+
+[source,java]
+-----------------------------------------------------------
+public enum ModelTarget {
+ /**
+ * A configuration section.
+ */
+ Section,
+ /**
+ * A configuration paramter.
+ */
+ Parameter,
+ /**
+ * ConfigModel that is a container of other validations.
+ */
+ Group
+}
+-----------------------------------------------------------
+
+A +ValidationResult+ models one validation executed by a +ConfigModel+ on a certain +Configuration+ instance:
+
+[source,java]
+-----------------------------------------------------------
+public final class ValidationResult {
+
+ public static ValidationResult ofValid(ConfigModel configModel);
+ public static ValidationResult ofMissing(ConfigModel configModel);
+ public static ValidationResult ofMissing(ConfigModel configModel, String message);
+ public static ValidationResult ofError(ConfigModel configModel, String error);
+ public static ValidationResult ofWarning(ConfigModel configModel, String warning);
+ public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage);
+ public static ValidationResult ofDeprecated(ConfigModel configModel);
+ public static ValidationResult ofUndefined(final String key);
+ public static ValidationResult of(ConfigModel configModel, ValidationState result, String message);
+
+ public ConfigModel getConfigModel();
+ public ValidationState getResult();
+ public String getMessage(),
+}
+-----------------------------------------------------------
+
+The result of a complete validation on a concrete +Configuration+ instance finally is mapped as a
++Collection<ValidationResult>+, refer to the methods on +ConfigModelManager+.
+
+
+=== Auto-Documentation of Classes with Configuration Injection
+
+A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
+(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
+models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
+time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
+behaviour. Nevertheless this means that after your system has been started you should have access to a complete
+set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
+(through injection).
+
+
+== Model SPI
+=== Registering Configuration Models
+
+The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is
+the +ModelProviderSpi+ interface, which allows any kind of additional config models to be added to the system:
+
+[source,java]
+-----------------------------------------------------------
+public interface ModelProviderSpi {
+
+ Collection<ConfigModel> getConfigModels();
+
+}
+-----------------------------------------------------------
+
+New instances implementing this interface must be registered into the current +ServiceContext+, by default the
++ServiceLoader+ is used.
+
+
+=== The ConfigUsageStatsSpi
+
+The methods for managing and tracking of configuration changes are similarly delegated to an
+implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI.
+By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking
+logic can be adapted or replaced.
+
+=== Other Utility Classes
+
+The module also provides further utility classes that may be useful for implementing models or testing:
+
+* +AbstractModel+ provides a base class that can be extended, when implementing +ConfigModel+.
+* +AreaConfigModel+ provides a +ConfigModel+ implementation (with a corresponding +Builder+) to model the
+ requirement of certain configuration sections being present, or opionally present, in the model.
+* +ParameterModel+ provides an implementation base class for validating parameters on existence and compliance
+ with a regular expression.
+* +ConfigDocumentationMBean+ is the MBean registered that models similar functionality as +ConfigModelManager+.
+* +ConfigModelGroup+ provides a +ConfigModel+ that groups several child models.
+* +ConfigModelReader+ allows to read +ConfigModels+ from properties files as described at the beginning of this
+ document.
+
+
+=== Switches to enable/disable functionality
+
+The model module provides different switches that can be used to activate or deactivate features:
+
+* +tamaya.model.integrated.enabled+ allows to deactivate reading inline metaconfiguration delivered with
+ the normal Tamaya Configuration. By default inline entries (+_.abcd.model.*+) are evaluated.
+* +tamaya.model.default.enabled+ allows to deactivate reading metamodel information from
+ +classpath:META-INF/configmodel.properties+. By default it is active.
+* +tamaya.model.resources+ allows to define additional resources (loaded through the resources extension),
+ that can be used to read metamodel information in any format using Tamaya's format module.
+* the system property +tamaya.model.autoModelEvents+ allows to activate/deactivate the automatic
+ documentation of classes configured and published by Tamaya +ConfiguredType+ event instances (e.g. published by
+ Tamaya's injection modules).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_mutable_config.adoc b/content/extensions/mod_mutable_config.adoc
new file mode 100644
index 0000000..2c15e9b
--- /dev/null
+++ b/content/extensions/mod_mutable_config.adoc
@@ -0,0 +1,258 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Mutable Configuration
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Mutable Configuration (Extension Module)
+=== Overview
+
+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
+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:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-mutable-config</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+=== Core Architecture
+
+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
+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.
+
+Summarizing a +MutableConfiguration+ can be obtained as follows:
+
+[source,java]
+.Accessing and changing a configuration
+--------------------------------------------
+MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
+config.set("newKey", "newValue")
+ .set("anotherKey", "updatedValue")
+ .remove("valueNotValid")
+ .commit();
+--------------------------------------------
+
+In the above scenario we use the overall system's configuration as the backend to be used.
+We can also pass any +Configuration+ to render it into a mutable instance, e.g.
+
+[source,java]
+.Explicitly passing the backing configuration
+--------------------------------------------
+Configuration config = ...;
+MutableConfiguration config =
+ MutableConfigurationProvider.createMutableConfiguration(config);
+--------------------------------------------
+
+NOTE: If a configuration does not contain any +MutablePropertySource+ instances, a +MutableConfiguration+ built
+ from it will not be able to accept any changes.
+
+
+Following is the complete listing of the +MutableConfigurationProvider+ accessor:
+
+[source, java]
+---------------------------------------------
+public final class MutableConfigurationProvider {
+
+ private MutableConfigurationProvider(){}
+
+ public static MutableConfiguration getMutableConfiguration();
+ public static MutableConfiguration getMutableConfiguration(Configuration configuration);
+
+ [...]
+}
+---------------------------------------------
+
+Hereby +MutableConfiguration+ is defined as follows:
+
+[source, java]
+---------------------------------------------
+public interface MutableConfiguration extends Configuration {
+
+ UUID startTransaction();
+ void commitTransaction();
+ void rollbackTransaction();
+ UUID getTransactionId();
+ boolean getAutoCommit();
+ void setAutoCommit(boolean autoCommit);
+
+ void setChangePropagationPolicy(ChangePropagationPolicy changePropagationPolicy);
+ ChangePropagationPolicy getChangePropagationPolicy();
+
+ boolean isWritable(String keyExpression);
+ boolean isRemovable(String keyExpression);
+ boolean isExisting(String keyExpression);
+ List<MutablePropertySource> getMutablePropertySources();
+ List<MutablePropertySource> getPropertySourcesThatCanWrite(String keyExpression);
+ List<MutablePropertySource> getPropertySourcesThatCanRemove(String keyExpression);
+ List<MutablePropertySource> getPropertySourcesThatKnow(String keyExpression);
+
+ MutableConfiguration put(String key, String value);
+ MutableConfiguration putAll(Map<String, String> properties);
+ MutableConfiguration remove(Collection<String> keys);
+ MutableConfiguration remove(String... keys);
+
+}
+---------------------------------------------
+
+
+==== Targeting the right MutablePropertySources
+
+A +Configuration+ may have multiple +MutablePropertySource+ present. These are members of Tamaya's oredered 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
+ processing chain?
+
+Therefore a +ChangePropagationPolicy+ can be set on a +MutableConfiguration+ instance, which allows to control
+this aspect:
+
+[source,java]
+.Explicitly passing the backing configuration
+--------------------------------------------
+public interface ChangePropagationPolicy {
+ void applyChanges(Collection<PropertySource> propertySources, UUID transactionID, Map<String,String> changes);
+ void applyChange(Collection<PropertySource> propertySources, UUID transactionID, String key, String value);
+ void applyRemove(Collection<PropertySource> propertySources, UUID transactionID, String... keys);
+
+}
+--------------------------------------------
+
+By default, changes are applied to all registered +MutablePropertySources+ similarly.
+
+
+Also the +MutableConfigurationProvider+ provides access to the most commonly used change propagation policies:
+
+[source, java]
+---------------------------------------------
+public final class MutableConfigurationProvider {
+
+ private MutableConfigurationProvider(){}
+
+ public static MutableConfiguration getMutableConfiguration();
+ public static MutableConfiguration getMutableConfiguration(Configuration configuration);
+
+ public static ChangePropagationPolicy getApplyAllChangePolicy();
+ public static ChangePropagationPolicy getApplyMostSignificantOnlyChangePolicy();
+ public static ChangePropagationPolicy getApplySelectiveChangePolicy(String... propertySourceNames);
+ public static ChangePropagationPolicy getApplyNonePolicy();
+}
+---------------------------------------------
+
+
+==== Some Aspects to consider
+
+Due to Tamaya's design the effective effect of your changes to the overall configuration, cannot
+be easily predicted, since it depends on several aspects:
+
+. is the corresponding configuration resource configured as part of the current system's configuration?
+. what is the +PropertySource's+ ordinal? Is it overriding or overridden by other sources?
+. is the change directly visible to the configuration system? E.g. injected values are normally not updated,
+ whereas injecting a +DynamicValue<T>+ instance allows to detect and react single value changes. Also the
+ +PropertySources+ implementation must be able to detect any configuration changes and adapt its values returned
+ accordingly.
+. Is configuration cached, or written/collected directly on access?
+. 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. To
+support such fine granular scenarios a +MutableConfiguration+ also offers methods to determine if a key
+is writable at all or can be removed or updated:
+
+[source,java]
+.Checking for mutability
+--------------------------------------------
+MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
+
+if(config,isWritable("mycluster.shared.appKey")){
+ config.set("newKey", "newValue");
+}
+if(config,isRemovable("mycluster.myapp.myKey")){
+ config.remove("mycluster.myapp.myKey");
+}
+config.commit();
+--------------------------------------------
+
+
+=== Configuration Changes
+
+This module does not handle detection of changes to the overall system's +Configuration+. This can be done in
+several ways, e.g. by:
+
+* using the _tamaya-events_ extension, which can be used to observe the system's configuration and
+ publishing events when things have been changed.
+* The SPI implementing the +MutableConfigurationBackendSpi+ may inform/update any affected +PropertySource,
+ PropertySourceProvider+ instances about the changes applied.
+
+
+=== 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
+the following +MutablePropertySource+ implementations:
+
+* +MutablePropertySource+ resources, targeting local .properties files, following the +java.util.Properties+
+ format.
+* +MutableXmlPropertySource+ resources, targeting local .xml property files, following the +java.util.Properties+
+ XML format.
+
+
+=== SPIs
+
+The module defines +MutableConfigurationProviderSpi+, that is used as a delegate by the +MutableConfigurationProvider+
+singleton accessor:
+
+[source,java]
+.SPI: MutableConfigurationProviderSpi
+--------------------------------------------------
+public interface MutableConfigurationProviderSpi {
+ MutableConfiguration createMutableConfiguration(Configuration configuration);
+}
+--------------------------------------------------
+
+Implementations are registered with the current +ServiceContext+, by default as a
+ +java.util.ServiceLoader+ service.
+
+
+As convenience the following base classes are provided:
+
+* +org.apache.tamaya.mutableconfig.propertysource.AbstractMutablePropertySource+ simplifying implementation of
+ +MutablePropertySource+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_optional.adoc b/content/extensions/mod_optional.adoc
new file mode 100644
index 0000000..f97e052
--- /dev/null
+++ b/content/extensions/mod_optional.adoc
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Optional Tamaya Configuration
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== Tamaya Optional Configuration (Extension Module)
+=== Overview
+
+The Tamaya optional module 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).
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-optional</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Reading configuration using the Tamaya Optional Module
+
+The optional module 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.
+
+[source, java]
+-----------------------------------------------
+BigDecimal interestRate =
+ OptionalConfiguration.of(
+ EvaluationPolicy.TAMAYA_OVERRIDES_OTHER,
+ (k) -> MyConfigMechanism.get(k) // String get(String key);
+ )
+ .get("com.mycomp.ratecalculator.rate", BigDecimal.class))
+ .orElse(BigDecimal.of(0.05d));
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_osgi.adoc b/content/extensions/mod_osgi.adoc
new file mode 100644
index 0000000..9a46fd0
--- /dev/null
+++ b/content/extensions/mod_osgi.adoc
@@ -0,0 +1,132 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extensions: OSGI Integrations
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== Tamaya OSGI Support
+=== Overview
+
+Tamaya provides also support for integration with OSGI. Hereby several options are available how Tamaya can be used in
+an OSGI context:
+
+. All Tamaya modules, its API and core library are actually valid OSGI bundles. So adding them into your OSGI modules
+ and using Tamaya is basically directly supported. Nevertheless OSGI works rather differently from a class- and
+ resource loading perspective. As long as you rely on Tamaya's mechanisms for resource loading things should work
+ out of the box. In the back Tamaya's core module actually comes with implicit OSGI support, which is automatically
+ activated, if Tamaya is running in an OSGI context. This support actually
+ ** Listens on deployed bundles and actively reads all resources configured as +java.util.ServiceLoader+ services and
+ registers them as OSGI services. Hereby integration is complete meaning you can also register Tamaya services
+ as normal OSGI services, e.g. your own +PropertySource+ instances.
+ ** Uses the OSGI bundle to resolve for resources, because accessing them from the classloader directly
+ typically fails in an OSGI context.
+. Adding Tamaya's OSGI integration module replaces the existing OSGI +ConfigAdmin+ service with an istance based on
+ Tamaya. Hereby several aspects can be configured using system properties:
+ ** +org.tamaya.integration.osgi.cm.ranking+ (int) allows to configure the OSGI service ranking used by the Tamaya
+ BundleActivator to register Tamaya's +ConfigAdmin+ service. In OSGI higher ranking precede lower rankings. By default
+ Tamaya's OSGI extending service registration mechanism is reusing any annotated +@Priority+ priority values as
+ corresponsing rankings.
+ ** +org.tamaya.integration.osgi.cm.override+ (boolean) allows to configure if Tamaya is overriding any existing
+ values from the default +ConfigAdmin+ instance, or only extending them. In other words this setting allows you to
+ define, which configuration subsystem has precedence for evaluating the final values, either Tamaya based
+ configuration (default) or the configuration mechanisms provided by default from your OSGI container (when this flag
+ is set to +false+).
+ ** +org.tamaya.integration.osgi.cm.inject+ allows you to deactivate injection of configuration values into your
+ OSGI services (by default injection is enabled). In all cases accessing the OSGI +ConfigAdmin+ service to
+ read your configuration is working as usual. But Tamaya adds additional injection functionality, which allows
+ to inject typed configuration as described by the Tamaya injection api.
+
+It is also possible to combine things, e.g. when you only define a low ranking for Tamaya's configuration service and
+the same time allow injection to be active, you will have Tamaya's injection support based on your default
+OSGI configuration.
+
+
+=== 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.
+
+
+=== Installation
+
+To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime
+environment:
+
+[source, listing]
+-----------------------------------------------
+# API and core
+org.apache.tamaya:tamaya-api:{tamayaVersion}
+org.apache.tamaya:tamaya-core:{tamayaVersion}
+org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0-alpha-1
+# injection API. SE injection module and dependencies
+org.apache.tamaya.ext:tamaya-injection-api:{tamayaVersion}
+org.apache.tamaya.ext:tamaya-injection:{tamayaVersion}
+org.apache.geronimo.specs:geronimo-atinject_1.0_spec:1.0
+org.apache.geronimo.specs:geronimo-el_2.2_spec:1.0.4
+org.apache.geronimo.specs:geronimo-interceptor_1.1_spec:1.0
+org.apache.geronimo.specs:geronimo-jcdi_1.1_spec:1.0
+# OSGI integration and dependencies
+org.apache.tamaya.ext:tamaya-osgi:{tamayaVersion}
+org.apache.tamaya.ext:tamaya-functions:{tamayaVersion}
+-----------------------------------------------
+
+
+=== Usage
+
+As an example, what is possible you can implement an OSGI service as a normal POJO and publish it as an OSGI service.
+Given that configuration can be injected very easily:
+
+[source, java]
+-----------------------------------------------
+public class HelloServiceImpl implements HelloService{
+
+ @Config("example.message")
+ @ConfigDefault("A Tamaya default.")
+ private String message;
+
+ @Override
+ public String sayHello() {
+ System.err.println("HELLO: " + message);
+ return message;
+ }
+}
+-----------------------------------------------
+
+
+=== SPI
+
+By defauklt the OSGI pid or factory pid is mapped to a corresponding root section in Tamaya's configuration. We are
+well aware that this might not always be the desired approach. Therefore there as an SPI service provided that allows
+to determine this mapping:
+
+[source, java]
+.OSGIConfigRootMapper
+-----------------------------------------------
+public interface OSGIConfigRootMapper {
+
+ String getTamayaConfigRoot(String pid, String factoryPid);
+}
+-----------------------------------------------
+
+Registering your own implementation as an OSGI service allows you to redefine the key mapping.
+By default a configuration mapping for +pid/factoryPid==myBundle+ is mapped to +[bundle:myBundle]+.
+This mapping is used as a prefix when collecting the corresponding entries for the OSGI configuration.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_remote.adoc b/content/extensions/mod_remote.adoc
new file mode 100644
index 0000000..4d947e5
--- /dev/null
+++ b/content/extensions/mod_remote.adoc
@@ -0,0 +1,131 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Remote Configuration
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Remote Configuration (Extension Module)
+=== Overview
+
+The Tamaya remote module 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_ .
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-remote</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Reading Remote configuration from a Tamaya Configuration Server
+
+The remote module allows reading JSON formatted onfiguration as provided by the _Tamaya server extension_ . The JSON
+format used looks as follows:
+
+[source, json]
+-----------------------------------------------
+{
+ "java.vendor.url": "http://java.oracle.com/",
+ "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
+ "java.vm.info": "mixed mode",
+ "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
+ "java.vm.specification.name": "Java Virtual Machine Specification",
+ "java.vm.specification.vendor": "Oracle Corporation",
+ "java.vm.specification.version": "1.8",
+ "java.vm.vendor": "Oracle Corporation",
+ "java.vm.version": "25.45-b02",
+ "sun.arch.data.model": "64",
+ "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
+ "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
+ "sun.cpu.endian": "little",
+ "sun.cpu.isalist": "amd64",
+ "sun.desktop": "windows",
+ "sun.io.unicode.encoding": "UnicodeLittle",
+ "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
+ "sun.java.launcher": "SUN_STANDARD",
+ "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"
+}
+-----------------------------------------------
+
+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.
+
+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+.
+
+[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() {
+ try {
+ String configServerUrl = System.getenv("CONFIG_SERVER");
+ if(configServerUrl==null){
+ configServerUrl = System.getProperty("configServer");
+ }
+ if(configServerUrl==null){
+ configServerUrl = "http://localhost:8888/config?scope=CLIENT&scopeId={clientId}&format=application/json";
+ }
+ System.out.println("Reading config from " + configServerUrl.replace("{clientId}", Client.getClientId()));
+ return Arrays.asList(new URL[]{new URL(configServerUrl.replace("{clientId}", Client.getClientId()))});
+ } catch (MalformedURLException e) {
+ Logger.getLogger(getClass().getName()).log(Level.WARNING, "Failed to configure remote config location,", e);
+ return Collections.emptySet();
+ }
+ }
+
+}
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_resolver.adoc b/content/extensions/mod_resolver.adoc
new file mode 100644
index 0000000..6f8f93a
--- /dev/null
+++ b/content/extensions/mod_resolver.adoc
@@ -0,0 +1,144 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Resolver
+
+// include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[Core]]
+== Tamaya Resolver (Extension Module)
+
+=== Overview
+
+Tamaya Resolver is an extension module. Refer to the
+// @todo Fix the link to the modules documentation
+link:modules.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:
+
+[source, xml, subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-resolver</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+-----------------------------------------------
+
+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:
+
+.Available Resolvers
+[cols="<.1,<.2,<.1"]
+|=======
+| _Expression_
+| _Description_
+| _Example_
+
+| +conf:<configKey>+
+| Reads another configKey and replaces the expression with the value found.
+| conf-ref=${conf:anotherConf.entryKey}
+
+| +resource:<resourceRef>+
+| Reads a resource from the current classpath and replaces the expression with the given text content.
+| cp-ref=${resource:Testresource.txt}
+
+| +file:<fileRef>+
+| Reads a resource from the current classpath and replaces the expression with the given text content.
+| file-ref=${file:c:\myFile.txt}
+
+|+url:<url>+
+|Reads an URL and replaces the expression with the given text content.
+| url-ref=${url:http://www.google.com}
+
+|=======
+
+=== SPI: Implementing your own Resolvers
+
+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:
+
+.Implementing a Custom Resolver
+[source, java]
+-----------------------------------------------
+public class PwdDecrypter implements ExpressionResolver {
+
+ @Override
+ public String getResolverPrefix() {
+ return "decrypt:";
+ }
+
+ @Override
+ public String evaluate(String expression) {
+ return decrypt(expression);
+ }
+
+ private String decrypt(String s) {
+ ...
+ }
+}
+-----------------------------------------------
+
+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:
+
+[source,listing]
+-----------------------------------------------
+blabla ${decrypt:myname}
+blabla ${decrypt:myname} foo blabla ${decrypt:myname}
+-----------------------------------------------
+
+Hereby evaluation is repeated 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.
+
+
+Under the hood instances of +ExpressionResolver+ are managed by an implementation of the +ExpressionEvaluator+
+interface:
+
+[source, java]
+-----------------------------------------------
+public interface ExpressionEvaluator {
+ /**
+ * 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.
+ */
+ String evaluateExpression(String key, String value);
+}
+-----------------------------------------------
+
+Implementing and registering this interface gives you full control, but in most cases yhou should be fine with
+the default implementation in place.
[2/5] incubator-tamaya-site git commit: TAMAYA-186: Add existing
pages.
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_resources.adoc b/content/extensions/mod_resources.adoc
new file mode 100644
index 0000000..c5f07f7
--- /dev/null
+++ b/content/extensions/mod_resources.adoc
@@ -0,0 +1,173 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Resources
+
+// include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[Core]]
+== Tamaya Resources (Extension Module)
+=== Overview
+
+Tamaya Resources is an extension module. Refer to the
+// @todo Fix the link to the modules page
+link:modules.html[extensions documentation] for further details
+about modules.
+
+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:
+
+[source, listing, subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <grooupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-resources</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+-----------------------------------------------
+
+
+The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class
+provides access to a +ResourceResolver+ instance:
+
+[source,java]
+-----------------------------------------------
+ResourceResolver resolver = ConfigResources.getResourceResolver();
+-----------------------------------------------
+
+[source,java]
+-----------------------------------------------
+public interface ResourceResolver {
+ Collection<URL> getResources(Collection<String> expressions) {...}
+ Collection<URL> getResources(String... expressions) {...}
+ Collection<URL> getResources(ClassLoader classLoader, String... expressions){...}
+ Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions);
+}
+-----------------------------------------------
+
+Hereby the methods allow to resolve expressions to a collection of URLs. In case the expression is also targeting the
+current classpath the target +ClassLoader+ to be used can be passed additionally.
+
+The default implementation provides resource resolution mechanism similar to the functionality offered by Spring.
+So by default resources can be looked up
+
+* from files
+* from the classpath
+* optionally ant-styled expressions can be used.
+
+=== Valid Expression Examples
+
+There are numerous ways how a resource pattern can be defined. Following the most important variants
+are listed:
+
+[source,listing]
+-----------------------------------------------
+// explicitly searching the file system
+file:myroot/aa?a/*.file
+file:myroot/b*/b?/*.file
+file:myroot/**/*.file
+
+// explicitly searching the classpath
+classpath:myroot/**/*.file
+classpath:javax/annotation/*.class
+classpath:javax/**/sql/*.class
+classpath:javax/annotation/**/R*.class
+classpath:javax/annotation/R?so*.class
+classpath:META-INF/maven/org.apache.geronimo.specs/**/*
+
+// search both classpath and files
+javax/annotation/*.class
+javax/**/sql/*.class
+javax/annotation/**/R*.class
+javax/annotation/R?so*.class
+META-INF/maven/org.apache.geronimo.specs/**/*
+myroot/**/*.file
+myroot/aa?a/*.file
+myroot/b*/b?/*.file
+-----------------------------------------------
+
+Summarizing the resources module provides useful functionality that helps to locate resources on the file system and
+in the classpath. This can be used to implement +PropertySourceProvider+ implementations that are based on
+corresponding resource path patterns instead of concrete files.
+
+
+=== Overall Usage Example
+
+Given the functionality we can easily implement a +PropertySourceProvider+ that reads all files from a classpath
+location, hereby traversing down all folders:
+
+
+[source, java]
+-------------------------------------------------------------
+public class PathBasedPropertySourceProvider implements PropertySourceProvider {
+
+ @Override
+ public Collection<PropertySource> getPropertySources() {
+ List<PropertySource> propertySources = new ArrayList<>();
+ Collection<URL> resources = Resources.getResourceResolver().getResources("META-INF/cfg/**/*.properties");
+ for(URL url:resources){
+ Properties props = new Properties();
+ try(InputStream is = url.openStream()){
+ props.load(is);
+ propertySources.add(new PropertiesBasedPropertySource(url.toString(), props));
+ }
+ catch(Exception e){
+ e.printStackTrace();
+ }
+ }
+
+ return propertySources;
+ }
+
+ private final static class PropertiesBasedPropertySource implements PropertySource {
+ private String name;
+ private Map<String,String> properties = new HashMap<>();
+
+ public PropertiesBasedPropertySource(String name, Properties props) {
+ this.name = name;
+ props.forEach((k,v) -> this.properties.put(k.toString(), v.toString()));
+ }
+
+ @Override
+ public String getName() {
+ return name;
+ }
+
+ @Override
+ public String get(String key) {
+ return properties.get(key);
+ }
+
+ @Override
+ public Map<String, String> getProperties() {
+ return properties;
+ }
+ }
+}
+-------------------------------------------------------------
+
+
+=== SPI
+
+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 implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+.
+
+Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written
+on your own.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_server.adoc b/content/extensions/mod_server.adoc
new file mode 100644
index 0000000..5238aca
--- /dev/null
+++ b/content/extensions/mod_server.adoc
@@ -0,0 +1,382 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Configuration Server
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Configuration Server (Extension Module)
+=== Overview
+
+The Tamaya server module provides support for providing scoped configuration using a http server serving JSON formatted
+configuration properties.
+
+
+=== Compatibility
+
+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:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-server</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Providing configuration using the Tamaya Built-in Configuration Server
+
+THe most simple way for providing onfiguration ist to start the internal server:
+
+[source, java]
+-----------------------------------------------
+Server server = org.apache.tamaya.server.ConfigServer.createServer();
+server.start(port);
+-----------------------------------------------
+
+This will start a simple server instance that serves the following URL patterns:
+
+* +GET /config+ provides access to the full configuration tree.
+* +GET /config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated).
+ E.g. +/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_.
+
+Additionally the server module has the following options implemented, which can be passed as additional, optional
+parameters:
+
+* +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this
+ setting can be explicitly controlled by passing tis parameter explicitly. The value is the expected MIME type to be
+ returned. By default the service supports the following types (refer to the SPI section later in this document for
+ options to adapt this):
+ ** text/html
+ ** text/plain
+ ** application/xml
+ ** text/json
+
+* +scope,scopeId+ allows to use a server-side preconfigured filter/combination policy to be applied for
+ evaluating the entries to be returned. Hereby the +scopeId+ paramter allows to address a certain scope.
+ As an example think of a scope +?scope=CLIENT&scopeId=client1+ to be passed as request parameters. This
+ tells the server module to lookup a configured scope named 'CLIENT' and access a +ConfigOperator+ for the
+ given scopeId 'client1'. The returned operator then can filter and combine any kind of entries to the
+ required client configuration (for client1). Refer to the scopes section for more details.
+
+
+=== Using the Configuration Servlets
+
+Additionally to the fully built-in solution, it is also possible to integrate the Tamaya server module with a standard
+Java EE servlet container. Tamaya provides 2 servlet implementations:
+
+* the servlet +org.apache.tamaya.server.FilteredConfigServlet+ can be used to register access to configurations
+ that also support filtering of the keys. The URL looks like
+
+----------------------------------------------------------
+http(s)://HOST/SERVLET_CONTEXT/PATHS?params
+
+where
+ HOST = host name incl port, e.g. 127.0.0.2:234
+ SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
+ PATHS = A comma separated number of key paths to be filtered for being returned, e.g.
+ java,sun,client
+ params = the optional parameters (scope, scopeId and format)
+----------------------------------------------------------
+
+* the servlet +org.apache.tamaya.server.FullConfigServlet+ can be used to register access to configurations
+ that alwyas returns all items known. The URL looks like
+
+----------------------------------------------------------
+http(s)://HOST/SERVLET_CONTEXT?params
+
+where
+ HOST = host name incl port, e.g. 127.0.0.2:234
+ SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
+ 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:
+
+.Formatting for +text/json+
+
+[source, json]
+-----------------------------------------------
+{
+ "java.vendor.url": "http://java.oracle.com/",
+ "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
+ "java.vm.info": "mixed mode",
+ "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
+ "java.vm.specification.name": "Java Virtual Machine Specification",
+ "java.vm.specification.vendor": "Oracle Corporation",
+ "java.vm.specification.version": "1.8",
+ "java.vm.vendor": "Oracle Corporation",
+ "java.vm.version": "25.45-b02",
+ "sun.arch.data.model": "64",
+ "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
+ "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
+ "sun.cpu.endian": "little",
+ "sun.cpu.isalist": "amd64",
+ "sun.desktop": "windows",
+ "sun.io.unicode.encoding": "UnicodeLittle",
+ "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
+ "sun.java.launcher": "SUN_STANDARD",
+ "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"
+}
+-----------------------------------------------
+
+
+.Formatting for +application/xml+
+
+[source, xml]
+-----------------------------------------------
+<configuration>
+ <entry key="java.vendor.url">http://java.oracle.com/</entry>
+ <entry key="java.vendor.url.bug">http://bugreport.sun.com/bugreport/</entry>
+ <entry key="java.vm.info">mixed mode</entry>
+ <entry key="java.vm.name">Java HotSpot(TM) 64-Bit Server VM</entry>
+ <entry key="java.vm.specification.name">Java Virtual Machine Specification</entry>
+ <entry key="java.vm.specification.vendor">Oracle Corporation</entry>
+ <entry key="java.vm.specification.version">1.8</entry>
+ <entry key="java.vm.vendor">Oracle Corporation</entry>
+ <entry key="java.vm.version">25.45-b02</entry>
+ <entry key="sun.arch.data.model">64</entry>
+ <entry key="sun.boot.class.path">C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes</entry>
+ <entry key="sun.boot.library.path">C:\apps\jdk18\jre\bin</entry>
+ <entry key="sun.cpu.endian">little</entry>
+ <entry key="sun.cpu.isalist">amd64</entry>
+ <entry key="sun.desktop">windows</entry>
+ <entry key="sun.io.unicode.encoding">UnicodeLittle</entry>
+ <entry key="sun.java.command">com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start</entry>
+ <entry key="sun.java.launcher">SUN_STANDARD</entry>
+ <entry key="sun.jnu.encoding">Cp1252</entry>
+ <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry>
+ <entry key="sun.os.patch.level"></entry>
+ <entry key="{meta}class">org.apache.tamaya.functions.FilteredConfiguration</entry>
+ <entry key="{meta}info.filter">java.v,sun</entry>
+ <entry key="{meta}info.format">application/xml</entry>
+ <entry key="{meta}info.timestamp">1441463383687</entry>
+ <entry key="{meta}timestamp">1441463383687</entry>
+ <entry key="{meta}type">Configuration</entry>
+</configuration>
+-----------------------------------------------
+
+
+.Formatting for +text/plain+
+
+[source, text]
+-----------------------------------------------
+
+Configuration:
+ java.vendor.url: http://java.oracle.com/,
+ java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
+ java.vm.info: mixed mode,
+ java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
+ java.vm.specification.name: Java Virtual Machine Specification,
+ java.vm.specification.vendor: Oracle Corporation,
+ java.vm.specification.version: 1.8,
+ java.vm.vendor: Oracle Corporation,
+ java.vm.version: 25.45-b02,
+ sun.arch.data.model: 64,
+ sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
+ sun.boot.library.path: C:\apps\jdk18\jre\bin,
+ sun.cpu.endian: little,
+ sun.cpu.isalist: amd64,
+ sun.desktop: windows,
+ sun.io.unicode.encoding: UnicodeLittle,
+ sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
+ sun.java.launcher: SUN_STANDARD,
+ 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/plain,
+ {meta}info.timestamp: 1441463082020,
+ {meta}timestamp: 1441463082021,
+ {meta}type: Configuration
+-----------------------------------------------
+
+
+.Formatting for +application/html+
+
+[source, html]
+-----------------------------------------------
+<html>
+<head><title>System Configuration</title></head>
+<body>
+<h1>Sysem Configuration</h1>
+<p>This view shows the system configuration of devbox-win at Sat Sep 05 16:30:59 CEST 2015.</p><pre>
+Configuration:
+ java.vendor.url: http://java.oracle.com/,
+ java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
+ java.vm.info: mixed mode,
+ java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
+ java.vm.specification.name: Java Virtual Machine Specification,
+ java.vm.specification.vendor: Oracle Corporation,
+ java.vm.specification.version: 1.8,
+ java.vm.vendor: Oracle Corporation,
+ java.vm.version: 25.45-b02,
+ sun.arch.data.model: 64,
+ sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
+ sun.boot.library.path: C:\apps\jdk18\jre\bin,
+ sun.cpu.endian: little,
+ sun.cpu.isalist: amd64,
+ sun.desktop: windows,
+ sun.io.unicode.encoding: UnicodeLittle,
+ sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
+ sun.java.launcher: SUN_STANDARD,
+ 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
+
+</pre>
+</body>
+</html>
+-----------------------------------------------
+
+=== SPI
+
+==== Scopes
+
+As mentioned earlier in this document scopes can be used to define the exact configuration tree to be returned, e.g.
+as a result of combining multiple sub trees. Following an example of the code to be written to return a configuration
+that combines common client default entries with client specific entries:
+
+[source, java]
+-----------------------------------------------
+public class ClientScopeProvider implements ScopeProvider{
+
+ /**
+ * Access the unique scope name.
+ * @return the unique scope name.
+ */
+ public String getScopeType(){
+ return "CLIENT";
+ }
+
+ @Override
+ public ConfigOperator getScope(String scopeId) {
+ return c ->
+ ConfigurationFunctions.combine("Scoped Config CLIENT="+scopeId,
+ c.with(ConfigurationFunctions.sectionRecursive(true, "client.default")),
+ c.with(ConfigurationFunctions.sectionRecursive(true, "client." + scopeId))
+ );
+ }
+}
+-----------------------------------------------
+
+This class can be registered using the +ServiceContext+ in place. By default the +ServiceLoader+ is used, so you will
+have to add the following to +META-INF/services/org.apache.tamaya.server.spi.ScopeProvider+:
+
+[source, listing]
+-----------------------------------------------
+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
+done by registering your own implementation of the interface +ConfigProviderService+:
+
+[source, java]
+------------------------------------------------
+public interface ConfigProviderService {
+ String getConfigurationWithPath(String path, String format, String scope, String scopeId, HttpServletRequest request);
+ String getConfiguration(String format, String scope, String scopeId, HttpServletRequest request);
+ void updateConfiguration(String payload, HttpServletRequest request);
+ void deleteConfiguration(String paths, HttpServletRequest request);
+}
+------------------------------------------------
+
+By default the +ServiceContextManager+ uses the +java.util.ServiceLoader+ for component loading, so to replace the
+default server code you must register a higher +@Priority+ implementation.
+
+
+==== Replacing the Built-In Server
+
+We have seen earlier that starting a configuration server is pretty easy:
+
+[source, java]
+-----------------------------------------------
+Server server = org.apache.tamaya.server.ConfigServer.createServer();
+server.start(port);
+-----------------------------------------------
+
+Nevertheless one may want to replace the used implementation of +Server+. This can be done easily by simply
+registering an overriding implementation if the corresponding interface:
+
+[source, java]
+-----------------------------------------------
+public interface Server {
+ void start(int port);
+ boolean isStarted();
+ void stop();
+ void destroy();
+}
+-----------------------------------------------
+
+==== The ScopeManager Singleton
+
+Finally whe implementing your own server, you might also benefit from the +ScopeManager+ singleton. Basically this
+class loads all registered +ScopeProvider+ and manages the configured scope instances:
+
+[source, java]
+-----------------------------------------------
+public final class ScopeManager {
+ ...
+
+ private ScopeManager(){}
+
+ /**
+ * Get the scope given its name.
+ * @param scopeId the scope name
+ * @return the scope matching
+ * @throws ConfigException, if nos such scope is defined.
+ */
+ public static ConfigOperator getScope(String scopeId, String target);
+
+ /**
+ * Get the defined scope names.
+ * @return the defined scope names, never null.
+ */
+ public static Set<String> getScopes();
+
+}
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_spi-support.adoc b/content/extensions/mod_spi-support.adoc
new file mode 100644
index 0000000..0e7892f
--- /dev/null
+++ b/content/extensions/mod_spi-support.adoc
@@ -0,0 +1,73 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[SPISupport]]
+== Tamaya SPI Support (Extension Module)
+=== Overview
+
+The Tamaya SPI support module provides a few helpful base classes that can be used to implement some of the often
+used SPI parts in Tamaya:
+
+* +BasePropertySource+ provides an abstract base class for implementation of your own PropertySources.
+* +DefaultConfiguration+ provides you with a simple implementation of the +Configuration+ interface based on a
+ +ConfigurationContext+ provided. This is also very useful for mocking configuration during test execution, but
+ not only constraint to that use case.
+* +DefaultConfigurationContext+ provides you with a working implementation of the +ConfigurationContext+.
+* +EnumConverter+ is a converter implementation that can automatically select the currect enumeration values based
+ on a configured entry.
+* +MapPropertySource+ implements a static property source based on +java.util.Map+.
+* +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations (also handling the
+ case, where no such annotation is present).
+* +PropertiesResourcePropertySource+ is an implementation of a +PropertySource+ based on a +Properties+ instance,
+ lodable from any +URL+.
++ +PropertyConverterManager+ is a service class very useful, when implementing instances of +ConfigurationContext+.
+ It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic.
++ +PropertyFiltering+ provides another helpful class that manages +PropertyFilter+ instances and provides an
+ easy to use high level API.
++ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+
+ values and their class names.
+
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-spisupport</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+The component will not register any components but only providing portable base classes for some common SPI
+implementation tasks. It only depends on the API, so it should be safely reusable also with other implementations
+of the Tamaya API similarly.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_spring.adoc b/content/extensions/mod_spring.adoc
new file mode 100644
index 0000000..17bd96a
--- /dev/null
+++ b/content/extensions/mod_spring.adoc
@@ -0,0 +1,150 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Spring Integration
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Spring Integration (Extension Module)
+=== Overview
+
+Apache Tamaya currently provides two implementations also full integration for Spring:
+
+* A Spring +@Configuration+ implementation that also provides a Tamaya based version of
+ +org.springframework.context.support.PropertySourcesPlaceholderConfigurer+.
+* +org.apache.tamaya.integration.spring.TamayaEnvironment+ is the Tamaya based implementation of the Spring
+ +Environment+ interface.
+* +TamayaSpringPropertySource+ implements an additional Spring +PropertySource+.
+* Finally +org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor+ implements a Bean +PostProcessor+,
+ which adds all the full fledged Tamaya configuration capabilities to Spring.
+
+
+=== Compatibility
+
+Both modules are based on Java 7, so they will not run on Java 7 and beyond. The extension shown here works similarly
+with Spring Framework as well as Spring Boot.
+
+
+=== Installation
+
+To benefit from Tamaya Spring integration you only must one of the following dependencies to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-spring</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Registering Tamaya Spring Configuration
+
+Basically to activate the Tamaya Spring support the most simple thing is to a enable the Tamaya package for being
+scanned for Spring components, e.g.
+
+[source, xml]
+--------------------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:context="http://www.springframework.org/schema/context"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
+
+ <context:annotation-config />
+ <context:component-scan base-package="org.apache.tamaya.integration.spring"/>
+
+ ...
+
+</beans>
+--------------------------------------------------------
+
+NOTE: Of course you can also use the newer +@ComponentScan+ annotation as described by the Spring documentation.
+
+
+Similarly if you dont want to use component scanning you can configure things using plain old XML. Simply add the
+following lines somewhere into one of your application context configuration files.
+
+[source, xml]
+--------------------------------------------------------
+<bean id="tamayaInjectionProcessor" name="tamayaInjectionProcessor" class="org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor"/>
+<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
+is resolved from the current Tamaya configuration.
+
+[source, xml]
+--------------------------------------------------------
+<bean id="configuredBean" name="configuredBean" class="org.apache.tamaya.integration.spring.ConfiguredSpringBean">
+ <property name="message" value="${propertyValue}"/>
+</bean>
+--------------------------------------------------------
+
+=== Configuring your Beans
+
+Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans:
+
+[source, java]
+--------------------------------------------------------
+**
+ * Created by Anatole on 25.09.2015.
+ */
+@ConfigDefaultSections
+public class ConfiguredSpringBean {
+
+ private String message;
+
+ @Autowired
+ private Environment env;
+
+ @Config("java.version")
+ private String javaVersion;
+
+ @Config
+ @ConfigDefault("23")
+ private int testNumber;
+
+ public String getJavaVersion(){
+ return javaVersion;
+ }
+
+ public int getTestNumber(){
+ return testNumber;
+ }
+
+ public Environment getEnv(){
+ return env;
+ }
+
+ public void setMessage(String message){
+ this.message = message;
+ }
+
+ public String getMessage() {
+ return message;
+ }
+}
+--------------------------------------------------------
+
+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/3d91bad5/content/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_yaml.adoc b/content/extensions/mod_yaml.adoc
new file mode 100644
index 0000000..e931129
--- /dev/null
+++ b/content/extensions/mod_yaml.adoc
@@ -0,0 +1,127 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Builder
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[BuilderCore]]
+== Tamaya YAML (Extension Module)
+=== Overview
+
+The Tamaya YAML module provides support for reading configuration using the YAML format (yaml.org). YAML hereby
+use intendation for expressing hierarchy, which makes yaml configuration files very easily readable and compact.
+
+
+=== Compatibility
+
+The YAML module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-yaml</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Reading configuration in YAML
+
+For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided:
+
+[source, java]
+-----------------------------------------------
+ConfigurationData dataRead = ConfigurationFormats.readConfig(
+ getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat()));
+-----------------------------------------------
+
+=== Examples
+
+The YAML module adds instances of +ConfigurationFormat+ so YAML configuration can be read and mapped to the
+according property values. E.g. the following file is a simple and correct YAML configuration:
+
+[source,yaml]
+----------------------------------------------------------------
+invoice: 34843
+date : 2001-01-23
+bill-to: &id001
+ given : Chris
+ family : Dumars
+ address:
+ lines: |
+ 458 Walkman Dr.
+ Suite #292
+ city : Royal Oak
+ state : MI
+ postal : 48046
+ship-to: *id001
+product:
+ - sku : BL394D
+ quantity : 4
+ description : Basketball
+ price : 450.00
+ - sku : BL4438H
+ quantity : 1
+ description : Super Hoop
+ price : 2392.00
+tax : 251.42
+total: 4443.52
+comments:
+ Late afternoon is best.
+ Backup contact is Nancy
+ Billsmer @ 338-4338.
+----------------------------------------------------------------
+
+Hereby the above file, by default is mapped as follows into +Map<String,String>+ typed properties:
+
+[source,listing]
+----------------------------------------------------------------
+invoice -> 34843
+date -> Tue Jan 23 01:00:00 CET 2001
+bill-to.family -> Dumars
+bill-to.given -> Chris
+bill-to.address.state -> MI
+bill-to.address.postal -> 48046
+bill-to.address.city -> Royal Oak
+bill-to.address.lines -> 458 Walkman Dr.
+Suite #292
+
+ship-to.given -> Chris
+ship-to.address.state -> MI
+ship-to.family -> Dumars
+ship-to.address.postal -> 48046
+ship-to.address.city -> Royal Oak
+ship-to.address.lines -> 458 Walkman Dr.
+Suite #292
+
+product -> {sku=BL394D, quantity=4, description=Basketball, price=450.0},{sku=BL4438H, quantity=1, description=Super Hoop, price=2392.0}
+_product.collection-type -> List
+
+tax -> 251.42
+total -> 4443.52
+comments -> Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/highleveldesign.adoc
----------------------------------------------------------------------
diff --git a/content/highleveldesign.adoc b/content/highleveldesign.adoc
new file mode 100644
index 0000000..f58957f
--- /dev/null
+++ b/content/highleveldesign.adoc
@@ -0,0 +1,167 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+
+== The Tamaya High Level Design
+
+Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
+that build the base of all the other mechanisms:
+
+The *API* (package +org.apache.tamaya+) provides
+
+* A simple but complete SE *API* for accessing key/value based _Configuration_:
+ ** +Configuration+ hereby models configuration, the main interface of Tamaya, providing key/value pairs as raw
+ (String-based) key/value pairs, allowing also access to typed values.
+ ** +ConfigurationProvider+ provides the static entry point for accessing configuration.
+
+The *SPI* (package +org.apache.tamaya.spi+) provides:
+ ** A simple minimalistic model for configuration data, called _PropertySource_.
+ ** Several extension points for adding additional configuration property sources or adapting the internal workings
+ of the overall system.
+ ** A +ServiceContext / ServiceContextManager+ that controls the loading of the components in Tamaya. This allows to
+ adapt the behaviour depending on the runtime environment in use, e.g. a Java standalone application, an OSGI
+ container or a Java EE application server.
+
+Tamaya *Modules* finally allow to add additional functionality to customize your configuration solution with the
+functionality you want. E.g. modules are providing features such as
+
+* Configuration _injection_
+* _Dynamic placeholders_ and resolution mechanism for configuration values
+* Abstractions for reusable _configuration formats_
+* Dynamic configuration updates and change events
+* Support for OSGI/Java EE Classloading
+* A configuration server/client
+* and more...
+
+
+== How Tamaya organizes Configuration
+=== Overview
+
+All the mentioned artifacts are used to organize configuration in a higly flexible and extendable way. Hereby the
++PropertySource+ is the key artifact. In general Tamaya organizes Configuration as follows:
+
+image::../images/CoreDesign.png[]
+
+Key abstraction hereby is the +ConfigurationContext+, which basically
+
+* an ordered chain of +PropertySource+ instances. This chain is used to evaluate raw configuration values.
+* a set of +PropertyFilter+ instances that filter the raw values evaluated from the property source chain.
+* a set of +PropertyConverter+ that convert String values into typed values when needed.
+
+In most standalone use cases only one +ConfigurationContext+ will be active at a time. But in more complex scenarios,
+such as Java EE also multiple contexts could be active that are active depending on the current runtime context
+(e.g. attached to the corresponding classloader(s)). These aspects are basically handled by the
++ConfigurationProvider+ and its corresponding SPIs.
+
+=== Loading the current _ConfigurationContext_
+
+The +ConfigurationContext+ is the core of Tamaya. It manages all configuration sources and additional components
+required to evaluate a concrete configuration value:
+
+* Tamaya loads all available +PropertySource+ instances. Hereby +PropertySource+ instances can be
+ ** Directly registered (using the mechanism defined by the current +ServiceContext+ implementation, by default
+ the Java +ServiceLoader+.
+ ** Provided by a registered instance of +PropertySourceProvider+.
+* All loaded property sources are _ordered based on each ordinal_, returned from +PropertySource.getOrdinal()+ as
+ an ordered chain of PropertySources, building up the ordered chain of +PropertySource+ instances used for raw
+ configuration value evaluation.
+* Tamaya loads all available +PropertyFilter+ instances. Hereby +PropertyFilter+ instances can be registered
+ by default using the Java +ServiceLoader+ API. The +PropertyFilter+ instances loaded are ordered based on the
+ +@Priority+ annotations found on each filter. If no priority annotation is present, +0+ is assumed.
+* Tamaya loads all available +PropertyConverter+ instances. Hereby +PropertyConverter+ instances can be registered
+ by default using the Java +ServiceLoader+ API. The +PropertyConverter+ instances loaded are ordered based on the
+ +@Priority+ annotations found on each filter. If no priority annotation is present, +0+ is assumed. It is
+ possible to register multiple converters for the same target type.
+
+=== Evaluating raw property values
+When evaluating a concrete configuration value for a given key, Tamaya iterates through this chain of registered
+PropertySources. Hereby the final value, by default, is determined by the last non-null value returned from a
++PropertySource+.
+
+Since the ladder may not always be appropriate, e.g. when values should be combined instead of overridden, a
+instance of +PropertyValueCombinationPolicy+ can be registered, which allows to add more detailed behaviour how values
+are combined.
+
+Access to the complete configuration +Map+ is performing the same resolution and combination algorithm, but for all
+key/value pairs available.
+
+=== Filtering the raw properties:
+Each raw configuration value evaluated is filtered by the ordered filter chain, as long as there are any changes
+applied by any of the filters called. This ensures that also transitive replacements by filters are possible.
+If, after a configurable number of evaluation loops still values are changes during each loop, the filtering
+process is aborted, since a non-resolvable circular filter issue is assumed.
+
+The output is the final configuration value as type +String+.
+
+=== Applying type conversion:
+Finally, if the required target type, does not match +Java.ui.lang.String+, all registered +PropertyConverter+
+instances targeting the corresponding target type are asked to convert the given (String-based) configuration
+entry to the required (non String) target type.
+
+Hereby the first _non-null_ value returned by a +PropertyConverter+ is used as the final typed configuration value and
+returned to the caller.
+
+=== Advanced Features
+Basically the bahaviour of Tamaya can be customized using the following mechanisms. Basically configuration can be
+provided using the following mechanism:
+
+* Registering additional (default) +PropertySource+ instances. Depending on their _ordinal value_ they
+ will override or extend existing configuration.
+* Registering additional (default) +PropertySourceProvider+ instances.that can provide multiple +PropertySource+
+ instances.
+
+Additionally Tamaya provides hooks for further adapting the internal workings:
+
+* Adapting the way how multiple entries with the same key are combined (+PropertyValueCombinationPolicy+). This
+ may be useful, if overriding is not the way how entries of the same key should be combined. An example, where
+ such an alternate scenario is useful are list entries, that combine all entries encountered to a collecting
+ list entry.
+* Adding additional support for new target types configurable by registering additional +PropertyConverter+
+ instances. This can be used for adding support for new types as well as for adding support for additional
+ formats.
+* Complex extensions may adapt the complete +ConfigurationContext+, using the +ConfigurationContextBuilder+ and
+ reapply the changed instance using +ConfigurationProvider.setConfigurationContext(ConfigurationContext)+.
+ This is one example how to react on dynamic changes detected on configuration files read.
+* Registering additional +PropertyFilter+ instances, that filter the configuration values extracted.
+* Registering an alternate +ServiceContext+ to support alternate runtime containers, e.g. a CDI container.
+* A combination of all above.
+
+Additionally instances of +ConfigOperator, ConfigQuery+ can be provided that provide additional functionality
+that should not be globally visible. It is recommended to provide them from a singleton accessor, hereby hiding
+the effective implementation classes.
+
+== Component Loading
+
+As mentioned the component loading of Tamaya can be adapted. By default the JDK +ServiceLoader+ API is used to determine
+a +ServiceContext+ implementation that should control
+Tamaya's overall component loading. If not found, a default implementation is registered, which relies on the
+Java +hava.util.ServiceLoader+ mechanism. This behaviour can be changed by implementing your own version
+of the +ServiceContext+ interface, annotating it with a +@Priority+ annotation and registering it using the
++java.util.ServiceLoader+ mechanism.
+
+== Compatibility
+
+The Tamaya API is compatible with Java 7 and beyond.
+
+== Further Documentation
+
+Being here we recommend to have a look at the more detailed documentation of Tamaya's link:API.html[API and SPI],
+and of its current available link:extensions.html[modules].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/history.adoc
----------------------------------------------------------------------
diff --git a/content/history.adoc b/content/history.adoc
new file mode 100644
index 0000000..bb09f0b
--- /dev/null
+++ b/content/history.adoc
@@ -0,0 +1,48 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//:source-highlighter: coderay
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+:linkattrs: true
+
+== Apache Tamaya: Release History
+
+Overview off all released versions of Apache Tamaya.
+
+[width="70"]
+[cols="2,3,3,3", options="headers", frame="all"]
+|===
+| Version
+| Release date
+| Release Notes
+| Download
+
+| 0.2-incubating
+| 06.04.2016
+| http://www.apache.org/dist/incubator/tamaya/0.2-incubating/ReleaseNotes-0.2-incubating.html[Release Notes for 0.2 incubating^]
+| http://www.apache.org/dist/incubator/tamaya/0.2-incubating/[Download of 0.2 incubating^]
+
+
+| 0.1-incubating
+| 22.08.2015
+| http://www.apache.org/dist/incubator/tamaya/0.1-incubating/ReleaseNotes-0.1-incubating.html[Release Notes for 0.1 incubating^]
+| http://www.apache.org/dist/incubator/tamaya/0.1-incubating/[Download of 0.1 incubating^]
+
+|===
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/quickstart.adoc
----------------------------------------------------------------------
diff --git a/content/quickstart.adoc b/content/quickstart.adoc
new file mode 100644
index 0000000..4567c7b
--- /dev/null
+++ b/content/quickstart.adoc
@@ -0,0 +1,208 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Quickstart
+
+
+The fastest way to start with Tamaya is just using the _Core_ implementation,
+implementing the **API** in small, minimalistic way. For that add the following
+Maven dependency to your project:
+
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>{tamaya_mvn_group_id}</groupId>
+ <artifactId>tamaya-core</artifactId>
+ <version>{tamaya_version_released}</version>
+</dependency>
+----
+
+Given that you can add your configuration properties to the following locations in your classpath:
+
+[source]
+----
+META-INF/javaconfiguration.properties
+----
+
+Additionally also system properties are taken into account, hereby overriding the default properties. Overall
+Tamaya by default defines the following configuration model per default (most significant first):
+
+. System Properties
+. `META-INF/javaconfiguration.properties`
+
+There many modules that extend the capabilities of Tamaya.
+These modules doe not depend on core, so alternative
+implementations of the Tamaya API should work similarly.
+
+
+=== Multiple configuration files
+
+By default you can provide multiple `javaconfig.properties` files, e.g. as part
+of multiple jars loaded into your system. The system internally creates one
+`PropertySource` for each file found on the classpath. All `PropertySource`
+instances created are ordered by their ordinal value (an int).
+
+Tamaya Core defines the following default ordinals (used, if no custom ordinal is defined):
+
+[width=70]
+[cols="3,1", option="headers"]
+|===
+| Source | Ordinal
+| System Properties | 400
+| Environment Variables | 300
+| Java Configuration Properties | 100
+|===
+
+That means that the value of a configuration variable `x` overhanded via `-Dx=yes` has
+a higher precedence then the entry for configuration variable `x` specified in a `javaconfig.properties`
+as `x=no`.
+
+These ordinal values can be either hardcoded, or be dynamically
+configurable as key within each configuration resource. The ladder can be done by defining a special
+Tamaya ordinal value as follows:
+
+
+[source]
+----
+# override default Tamaya ordinal for property files
+tamaya.ordinal=123
+----
+
+This assigns an ordinal of 123 to each entry in that configuration resource.
+
+=== Using additional features of Tamaya
+
+There many modules that extend the capabilities of
+Tamaya. These modules doe not depend on core, so alternative
+implementations of the Tamaya API should work similarly. Following a
+small extract of most important modules available (or available soon):
+
+==== Dynamic Resolution and Value Placeholders
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <artifactId>org.apache.tamaya.ext</id>
+ <artifactId>tamaya-resolver</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+----
+
+// @todo Auf Modulliste verweisen f�r vollst�ndigen �berblick
+With that it is possible to define values with Unix styled placeholders that are
+resolved on configuration access, e.g.
+`mykey=my${dynamicValue}�. For further details refer to the module documentation.
+This module also provides a `Resolver` singleton:
+
+[source,java]
+----
+String myExpression = ...;
+String resolved = Resolver.evaluateExpression(myExpression);
+----
+
+
+==== Ant-styled Path Resolution of Resources
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <artifactId>org.apache.tamaya.ext</id>
+ <artifactId>tamaya-resolution</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+----
+
+This module provides a `Resolver` singleton that allows to
+resolve configuration resources using a ant-styled resource
+description, e.g.
+
+
+[source,xml,subs="verbatim,attributes"]
+----
+Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties");
+----
+
+For further details refer to the module documentation.
+
+
+==== Configuration Injection
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <artifactId>org.apache.tamaya.ext</id>
+ <artifactId>tamaya-inject</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+----
+
+With this extension you can let Tamaya inject configuration into instances of
+annotated classes or let Tamaya implement a configuration template.
+
+Corresponding configuration:
+
+[source,xml,subs="verbatim,attributes"]
+----
+public class MyType {
+ @ConfiguredProperty("name")
+ private String typeName;
+
+ public String getName() {
+ return name;
+ }
+}
+
+MyType type = new MyType();
+ConfigurationInjector.configure(type);
+----
+
+Or the same as template:
+
+[source,xml,subs="verbatim,attributes"]
+----
+public interface MyTypeTemplate {
+ @ConfiguredProperty("name")
+ public String getName();
+}
+
+MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class);
+----
+
+Currently the following resolvers are available:
+
+[width="60"]
+[cols="1,4"]
+|===
+| Conf
+| Cross-reference to another configuration entry
+
+| URL
+| Referencing a resource addressable by an URL.
+
+| File
+| Reference to a file, replacing the expression with the file's text value.
+
+| Resource
+| Reference to classpath resource, replacing the expression with the resource's text value.
+
+|===
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/release-guide.adoc
----------------------------------------------------------------------
diff --git a/content/release-guide.adoc b/content/release-guide.adoc
new file mode 100644
index 0000000..9c74090
--- /dev/null
+++ b/content/release-guide.adoc
@@ -0,0 +1,276 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+
+= Apache Tamaya: Release Guide
+
+Performing a release requires several steps. This document describes each step, so everybody in the committer's
+team should be able to perform the release procedure.
+
+
+== Tell the others you would proceed with the release procedure
+
+[listing,text]
+----
+first steps for the next release
+
+Hi @ all,
+
+If there are no objections, I'll start with the first steps for
+the next release (review, documentation,...).
+It would be great to start with the release procedure next week.
+
+Best regards,
+[name]
+----
+
+== Check everything is ready
+
+* Check the jenkins builds.
+* Ensure all JIRA-tickets targeting the release are resolved. If not, get in contact with the ticket
+ owner/assignee to check
+ ** if the ticket can be postponed for the next release
+ ** how long it takes to resolve it and if one can help.
+
+
+== Prepare the release
+
+* Create release notes and commit them to `tamaya/readme/` (format `ReleaseNotes-[version].html`)
+* Create a release branch in git and switch to this branch:
+
+
+=== Using the Release Plugin
+
+For performing the release you can use the maven release plugin:
+
+[listing,text]
+----
+$ git checkout -b vote-tamaya-[release version]
+$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
+$ mvn release:prepare -DdryRun=true -DperformRelease=true
+# optionally pass GPG params for signing with: -Darguments="-Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX"
+# copy prepared workspace (to continue faster if an upload fails in the next step)
+----
+
+* If something fails you may switch to the master branch, fix whatever is needed and rebase your release branch to
+ accommodate the latest changes done.
+* On success you can check the release packages from `dist/target`.
+* If everything looks good you can proceed with the release:
+
+[listing,text]
+----
+$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
+$ mvn release:prepare -DperformRelease=true
+$ mvn release:perform -DperformRelease=true
+----
+
+=== Preparing the release without the Release Plugin
+
+The release plugin is great, but in some cases it breaks even, when release:prepare -DdryRun=true was successful.
+Preparing the release vote without the release plugin is stright forward:
+
+* As described checkout a release branch of the current head
+* Then us maven and git commands to prepare the release:
+
+[listing,text]
+----
+$ git checkout -b vote-tamaya-[release version]
+$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
+$ mvn versions:set versions:commit -DnewVersion=[release version] -DperformRelease=true
+# build the release locally and sign it with your certs
+$ mvn clean install -DperformRelease=true -Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX
+----
+
+* Check if everything is in place and correct, when finished you can tag and deploy the release...
+
+[listing,text]
+----
+$ mvn deploy -DperformRelease=true -Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX
+----
+
+* check the created commits including user-name and email
+* login to https://repository.apache.org/[^] and go to "Staging Repositories"
+* check the contents of the newly created tamaya staging repository
+* _close_ the repository to let Nexus do its validations
+* On success:
+* push the release-branch to the git repo
+
+[listing,text]
+----
+$ git add -A
+$ git commit -m "Release Prepare: Set release version."
+$ git tag vote01-[release-version]
+$ git push --tags
+----
+
+Finally open the next development version:
+
+[listing,text]
+----
+# example: newVersion=0.3-incubating-SNAPSHOT
+$ mvn version:set versions:commit -DnewVersion=[development-version]
+$ git add -A
+$ git commit -m "Release Prepare: Open new development version."
+----
+
+
+
+* Add the distribution artifacts to the dev repositories:
+
+[listing,text]
+----
+$ svn co https://dist.apache.org/repos/dist/dev/incubator/tamaya/
+$ mkdir [version]
+$ set RELEASE_HOME='pwd'/[version]
+$ cd PROJECT_ROOT
+$ cp DISCLAIMER $RELEASE_HOME
+$ cp NOTICE $RELEASE_HOME
+$ cp LICENCE $RELEASE_HOME
+$ cp rat.txt $RELEASE_HOME
+# Copy everything from
+# $STAGING_REPO/distribution/0.2-incubating/tamaya-distribution-[version]-distribution-* into $RELEASE_HOME
+$ svn add [version]
+$ svn commit --username <apacheId>
+----
+
+* Check contents on https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]
+
+
+== Start the vote
+
+[listing,text]
+----
+[VOTE] Release of Apache Tamaya [version]
+
+Hi,
+
+I was running the needed tasks to get the [version] release of Apache Tamaya out.
+The artifacts are deployed to Nexus [1] (and [2]) and releases [4].
+
+The tag is available at [3] and will renamed once the vote passed.
+
+Please take a look at the artifacts and vote!
+
+Please note:
+This vote is a "majority approval" with a minimum of three +1 votes (see [5]).
+
+------------------------------------------------
+[ ] +1 for community members who have reviewed the bits
+[ ] +0
+[ ] -1 for fatal flaws that should cause these bits not to be released, and why..............
+------------------------------------------------
+
+Thanks,
+[name]
+
+[1] https://repository.apache.org/content/repositories/...
+[2] https://repository.apache.org/content/repositories/org/apache/tamaya/tamaya-distribution/[version]/tamaya-[version]-source-release.zip
+ https://repository.apache.org/content/repositories/org/apache/tamaya/tamaya-distribution/[version]/tamaya-[version]-bin-release.zip
+[3] https://git1-us-west.apache.org/repos/asf?p=incubator-tamaya.git;a=commit;h=2910da468fce16210e6dd77d8ba23ddbdd434efe
+[4] https://dist.apache.org/repos/dist/dev/incubator/tamaya/[release-version]
+[5] http://www.apache.org/foundation/voting.html#ReleaseVotes
+----
+
+* Announce the Vote
+ ** Create a short link to the release at http://s.apache.org (format Tamaya_[version])
+ ** Tweet about the vote via _@TamayaConf_
+
+* After 72 hours close the vote write a reult email, e.g.
+
+[listing,text]
+----
+[Result] (was: Re: [VOTE] Release of Apache Tamaya [version])
+
+Thank you for voting!
+
+X binding +1 votes (pmc):
+[list]
+
+Y non-binding +1 votes:
+[list]
+
+Z -1 votes
+[list]
+----
+
+* After the vote on the PPMC has been finished and is successful, repeat the voting process on the
+ incubator mailing list.
+
+
+== Perform the release
+
+If the binding majority approved the vote on both lists continue:
+
+* Login to https://repository.apache.org/ and _release_ the repository
+* Rename the vote branch:
+
+[listing,text]
+----
+$ git branch -m vote01-tamaya-[release-version] tamaya-[release-version]
+----
+
+* Add a release tag:
+
+----
+$ git tag -a tamaya-[release-version]
+----
+
+* Merge master with the new prepared version:
+
+[listing,text]
+----
+$ git checkout master
+$ git merge tamaya-[release-version]
+$ git push origin tamaya-[release-version]
+$ git push origin master
+----
+
+* Close the release and corresponding tickets at JIRA
+
+* Wait some minutes and check http://repo2.maven.org/maven2/org/apache/tamaya[^]
+
+* Upload the distribution Artifacts
+
+[listing,text]
+----
+$ svn co https://dist.apache.org/repos/dist/release/incubator/tamaya/
+$ mkdir [version]
+# add and commit the artifacts (*source-release.zip, *bin-release.zip + asc, md5, sha1)
+# use the artifacts from:
+# http://repo1.maven.org/maven2/org/apache/tamaya/tamaya-distribution/[version]/
+----
+
+
+== Updating the Tamaya Project Site
+
+Basically the new site should be directly deployable, just execute
+
+[listing,text]
+----
+$ mvn site site:deploy
+----
+
+
+== Announce the new version
+
+Announce the new version on @TamayaConf and other social media channels.
+Also drop a short mail on the amiling list.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/source.adoc
----------------------------------------------------------------------
diff --git a/content/source.adoc b/content/source.adoc
new file mode 100644
index 0000000..e6334d4
--- /dev/null
+++ b/content/source.adoc
@@ -0,0 +1,41 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+
+= Apache Tamaya: Sources
+
+== Source Code Repositories
+
+The current source code can be found at:
+
+ - http://git-wip-us.apache.org/repos/asf/incubator-tamaya.git (read-only)
+ - https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git
+
+Alternatively there is also a GitHub read-only mirror at
+https://github.com/apache/incubator-tamaya[https://github.com/apache/incubator-tamaya^].
+
+The GitHub mirror also provides the project as downloadable zip archive.
+
+== Contributions
+
+If you like to contribute to Apache Tamaya please also refer also to our
+<<devguide.adoc#contributing-workflow,section on contributing to Apache Tamaya>>.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/start.md
----------------------------------------------------------------------
diff --git a/content/start.md b/content/start.md
new file mode 100644
index 0000000..0909d7f
--- /dev/null
+++ b/content/start.md
@@ -0,0 +1,57 @@
+title = About Apache Tamaya
+type = page
+status = published
+~~~~~~
+
+About Apache Tamaya
+-------------------
+
+Apache Tamaya (incubating) provides a flexible and powerful
+configuration solution
+for Java developers using Java SE as well as for more complex
+usage scenarios like cloud or Java EE. It provides a modern
+type-safe property based Configuration API combined with a
+powerful environment model and a flexible SPI.
+
+Features
+--------
+
+* Unified Configuration API
+* Pluggable Configuration Backends
+* Enforceable Configuration Policies
+* Configuration Validation and Documentation
+* Seemless Enterprise Integration
+
+Documentation
+-------------
+
+* [Use Cases and Requirements](usecases.html)
+* [High Level Design](highleveldesign.html)
+* [API](api.html)
+* [Core](core.html)
+* [Extensions](extensions.html)
+
+---
+
+Quickstart
+----------
+
+Using Apache Tamaya is simple:
+
+1. Add `org.apache.tamaya:tamaya-core:TBDreleased_version` to your dependencies.
+2. Add your config to `META-INF/javaconfiguration.properties`
+3. Access your configuration by `ConfigurationProvider.getConfiguration()` and use it.
+4. Look at the [extension modules](extensions.html) to customize your setup!
+5. Enjoy!
+
+
+Rationale
+---------
+
+Configuration is one of the most prominent cross-cutting concerns similar to logging. Most of us already have been
+writing similar code again and again in each of our projects. Sometimes in a similar way but mostly always slightly
+different, but certainly with high coupling to your configuration backends. Given your code is reused or integrated
+some how, or deployed by some customers, struggling starts: not supported backends, different policies, missing
+combination and validation mechanisms and so on. Tamaya solves all this by defining a common API and backend SPI.
+Your code is decoupled from the configuration backend. There is no difference if your code is deployed on your dev box
+or in a clustered Docker environment in production, it stays the same!
[5/5] incubator-tamaya-site git commit: TAMAYA-186: Add existing
pages.
Posted by po...@apache.org.
TAMAYA-186: Add existing pages.
* Still work in progress.
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/3d91bad5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/3d91bad5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/3d91bad5
Branch: refs/heads/master
Commit: 3d91bad59dfd5766f0df3e053bde43bb8028ad48
Parents: 90f34d2
Author: Phil Ottlinger <po...@apache.org>
Authored: Mon Oct 31 22:34:17 2016 +0100
Committer: Phil Ottlinger <po...@apache.org>
Committed: Mon Oct 31 22:34:17 2016 +0100
----------------------------------------------------------------------
content/api.adoc | 616 +++++++++++++++++++
content/community.adoc | 143 +++++
content/core.adoc | 228 +++++++
content/devguide.adoc | 213 +++++++
content/download.adoc | 109 ++++
content/examples.adoc | 71 +++
content/extensions.adoc | 107 ++++
content/extensions/mod_builder.adoc | 101 +++
content/extensions/mod_camel.adoc | 145 +++++
content/extensions/mod_cdi.adoc | 233 +++++++
content/extensions/mod_classloader_support.adoc | 91 +++
content/extensions/mod_collections.adoc | 248 ++++++++
content/extensions/mod_consul.adoc | 75 +++
content/extensions/mod_environment.adoc | 58 ++
content/extensions/mod_etcd.adoc | 205 ++++++
content/extensions/mod_events.adoc | 372 +++++++++++
content/extensions/mod_filter.adoc | 135 ++++
content/extensions/mod_formats.adoc | 243 ++++++++
content/extensions/mod_functions.adoc | 124 ++++
content/extensions/mod_injection.adoc | 445 ++++++++++++++
content/extensions/mod_jodatime.adoc | 64 ++
content/extensions/mod_json.adoc | 77 +++
content/extensions/mod_management.adoc | 108 ++++
content/extensions/mod_metamodel-staged.adoc | 74 +++
content/extensions/mod_model.adoc | 467 ++++++++++++++
content/extensions/mod_mutable_config.adoc | 258 ++++++++
content/extensions/mod_optional.adoc | 70 +++
content/extensions/mod_osgi.adoc | 132 ++++
content/extensions/mod_remote.adoc | 131 ++++
content/extensions/mod_resolver.adoc | 144 +++++
content/extensions/mod_resources.adoc | 173 ++++++
content/extensions/mod_server.adoc | 382 ++++++++++++
content/extensions/mod_spi-support.adoc | 73 +++
content/extensions/mod_spring.adoc | 150 +++++
content/extensions/mod_yaml.adoc | 127 ++++
content/highleveldesign.adoc | 167 +++++
content/history.adoc | 48 ++
content/quickstart.adoc | 208 +++++++
content/release-guide.adoc | 276 +++++++++
content/source.adoc | 41 ++
content/start.md | 57 ++
content/usecases.adoc | 506 +++++++++++++++
jbake.properties | 2 +-
templates/menu.thyme | 6 +-
templates/post.thyme | 1 -
templates/sitemap.thyme | 2 +-
46 files changed, 7701 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/api.adoc
----------------------------------------------------------------------
diff --git a/content/api.adoc b/content/api.adoc
new file mode 100644
index 0000000..f830585
--- /dev/null
+++ b/content/api.adoc
@@ -0,0 +1,616 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[CoreDesign]]
+== Apache Tamaya: API
+
+Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
+that build the base of all the other mechanisms. As a starting point we recommend you read the corresponding
+llink:HighLevelDesign.html[High Level Design Documentation]
+
+[[API]]
+== The Tamaya API
+The API provides the artifacts as described in the link:HighLevelDesign.html[High Level Design Documentation], which are:
+
+* A simple but complete SE *API* for accessing key/value based _Configuration_:
+ ** +Configuration+ hereby models configuration, the main interface of Tamaya. +Configuration+ provides
+ *** access to literal key/value pairs.
+ *** functional extension points (+with, query+) using a unary +ConfigOperator+ or
+ a function +ConfigurationQuery<T>+.
+ ** +ConfigurationProvider+ provides with +getConfiguration()+ the static entry point for accessing configuration.
+ ** +ConfigException+ defines a runtime exception for usage by the configuration system.
+ ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned by a registered
+ +PropertyProvider+.
+ ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type.
+
+* Additionally the *SPI* provides:
+ ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+ hereby
+ *** is designed as a minimalistic interface that be implemented by any kind of data provider (local or remote)
+ *** provides single access for key/value pairs in raw format as String key/values only (+getPropertyValue+).
+ *** can optionally support scanning of its provided values, implementing +getProperties()+.
+ ** _PropertySourceProvider:_ allows to register multiple property sources dynamically, e.g. all config files found in
+ file system folder..
+ ** +ConfigurationProviderSpi+ defines the SPI that is used as a backing bean for the +ConfigurationProvider+
+ singleton.
+ ** +PropertyFilter+, which allows filtering of property values prior getting returned to the caller.
+ ** +ConfigurationContext+, which provides the container that contains the property sources and filters that form a
+ configuration.
+ ** +PropertyValueCombinationPolicy+ optionally can be registered to change the way how different key/value
+ pairs are combined to build up the final +Configuration+ passed over to the filters registered.
+ ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack.
+ ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded.
+
+This is also reflected in the main packages of the API:
+
+* +org.apache.tamaya+ contains the main API abstractions used by users.
+* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+
+ mechanism.
+
+
+
+[[APIKeyValues]]
+=== Key/Value Pairs
+
+Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple
+and most commonly used approach are simple literal key/value pairs. So the core building block of {name} are key/value pairs.
+You can think of a common +.properties+ file, e.g.
+
+[source,properties]
+.A simple properties file
+--------------------------------------------
+a.b.c=cVal
+a.b.c.1=cVal1
+a.b.c.2=cVal2
+a=aVal
+a.b=abVal
+a.b2=abVal
+--------------------------------------------
+
+Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g.
+
+[source,properties]
+--------------------------------------------
+Properties props = new Properties();
+props.readProperties(...);
+String val = props.getProperty("a.b.c");
+val = props.getProperty("a.b.c.1");
+...
+--------------------------------------------
+
+
+==== Why Using Strings Only
+
+There are good reason to keep of non String-values as core storage representation of configuration. Mostly
+there are several huge advantages:
+
+* Strings are simple to understand
+* Strings are human readable and therefore easy to prove for correctness
+* Strings can easily be used within different language, different VMs, files or network communications.
+* Strings can easily be compared and manipulated
+* Strings can easily be searched, indexed and cached
+* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in
+ production as well in testing.
+* and more...
+
+On the other side there are also disadvantages:
+
+* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as
+numbers, dates etc.
+* In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly
+ throughout your code.
+* Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some
+ extra efforts.
+
+Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above:
+
+* Adding type safe adapters on top of String allow to add any type easily, that can be directly mapped out of Strings.
+ This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.
+* Also multi-valued, complex and collection types can be defined as a corresponding +PropertyAdapter+ knows how to
+ parse and create the target instance required.
+* String s also can be used as references pointing to other locations and formats, where configuration is
+ accessible.
+
+
+[[API Configuration]]
+=== Configuration
+
++Configuration+ is the main API provided by Tamaya. It allows reading of single property values or the whole
+property map, but also supports type safe access:
+
+[source,java]
+.Interface Configuration
+--------------------------------------------
+public interface Configuration{
+ String get(String key);
+ String getOrDefault(String key, String value);
+ <T> T get(String key, Class<T> type);
+ <T> T getOrDefault(String key, Class<T> type, T defaultValue);
+ <T> T get(String key, TypeLiteral<T> type);
+ <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue);
+ Map<String,String> getProperties();
+
+ // extension points
+ Configuration with(ConfigOperator operator);
+ <T> T query(ConfigQuery<T> query);
+
+ ConfigurationContext getContext();
+}
+--------------------------------------------
+
+Hereby
+
+* +<T> T get(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK.
+* +with, query+ provide the extension points for adding additional functionality.
+* +getProperties()+ provides access to all key/values, whereas entries from non scannable property sources may not
+ be included.
+* +getOrDefault+ allows to pass default values as needed, returned if the requested value evaluated to +null+.
+
+The class +TypeLiteral+ is basically similar to the same class provided with CDI:
+
+[source,java]
+--------------------------------------------
+public class TypeLiteral<T> implements Serializable {
+
+ [...]
+
+ protected TypeLiteral(Type type) {
+ this.type = type;
+ }
+
+ protected TypeLiteral() { }
+
+ public static <L> TypeLiteral<L> of(Type type){...}
+ public static <L> TypeLiteral<L> of(Class<L> type){...}
+
+ public final Type getType() {...}
+ public final Class<T> getRawType() {...}
+
+ public static Type getGenericInterfaceTypeParameter(Class<?> clazz, Class<?> interfaceType){...}
+ public static Type getTypeParameter(Class<?> clazz, Class<?> interfaceType){...}
+
+ [...]
+}
+--------------------------------------------
+
+Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton:
+
+[source,java]
+.Accessing Configuration
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+--------------------------------------------
+
+Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+.
+
+
+[[PropertyConverter]]
+==== Property Converters
+
+As illustrated in the previous section, +Configuration+ also to access non String types. Nevertheless internally
+all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the
+configured String values into the required target type. This is achieved with the help of +PropertyConverters+:
+
+[source,java]
+--------------------------------------------
+public interface PropertyConverter<T>{
+ T convert(String value, ConversionContext context);
+ //X TODO Collection<String> getSupportedFormats();
+}
+--------------------------------------------
+
+The +ConversionContext+ contains additional meta-information for the accessed key, inclusing the key'a name and
+additional metadata.
+
++PropertyConverter+ instances can be implemented and registered by default using the +ServiceLoader+. Hereby
+a configuration String value is passed to all registered converters for a type in order of their annotated +@Priority+
+value. The first non-null result of a converter is then returned as the current configuration value.
+
+Access to converters is provided by the current +ConfigurationContext+, which is accessible from
+the +ConfigurationProvider+ singleton.
+
+
+[[ExtensionPoints]]
+=== Extension Points
+
+We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore
+we have added functional extension mechanisms to +Configuration+ that were used in other areas of the Java eco-system
+as well:
+
+* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of
+ +Configuration+. Operators can be used to cover use cases such as filtering, configuration views, security
+ interception and more.
+* +query(ConfigQuery query)+ allows to apply a function returning any kind of result based on a
+ +Configuration+ instance. Queries are used for accessing/deriving any kind of data based on of a +Configuration+
+ instance, e.g. accessing a +Set<String>+ of root keys present.
+
+Both interfaces hereby are functional interfaces. Because of backward compatibility with Java 7 we did not use
++UnaryOperator+ and +Function+ from the +java.util.function+ package. Nevertheless usage is similar, so you can
+use Lambdas and method references in Java 8:
+
+[source,java]
+.Applying a +ConfigurationQuery+ using a method reference
+--------------------------------------------
+ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext);
+--------------------------------------------
+
+NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes.
+
+
+Operator calls basically look similar:
+
+[source,java]
+.Applying a +ConfigurationOperator+ using a lambda expression:
+--------------------------------------------
+Configuration secured = ConfigurationProvider.getConfiguration()
+ .with((config) ->
+ config.get("foo")!=null?;
+ FooFilter.apply(config):
+ config);
+--------------------------------------------
+
+
+[[ConfigException]]
+=== ConfigException
+
+The class +ConfigException+ models the base *runtime* exception used by the configuration system.
+
+
+[[SPI]]
+== SPI
+
+[[PropertySource]]
+=== Interface PropertySource
+
+We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to
+understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a +java.util.Map<String,
+String>+ and +java.util.Properties+ basically model these aspects out of the box.
+
+Though there are advantages in using these types as a model, there are some severe drawbacks, notably implementation
+of these types is far not trivial and the collection API offers additional functionality not useful when aiming
+for modelling simple property sources.
+
+To render an implementation of a custom +PropertySource+ as convenient as possible only the following methods were
+identified to be necessary:
+
+[source,java]
+--------------------------------------------
+public interface PropertySource{
+ int getOrdinal();
+ String getName();
+ String get(String key);
+ boolean isScannable();
+ Map<String, String> getProperties();
+}
+--------------------------------------------
+
+Hereby
+
+* +get+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available.
+* +getProperties+ allows to extract all property data to a +Map<String,String>+. Other methods like +containsKey,
+ keySet+ as well as streaming operations then can be applied on the returned +Map+ instance.
+* But not in all scenarios a property source may be scannable, e.g. when looking up keys is very inefficient, it
+ may not make sense to iterator over all keys to collect the corresponding properties.
+ This can be evaluated by calling +isScannable()+. If a +PropertySource+ is defined as non scannable accesses to
+ +getProperties()+ may not return all key/value pairs that would be available when accessed directly using the
+ +String get(String)+ method.
+* +getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where
+ property sources with higher ordinals override the ones with lower ordinals. If ordinal are the same, the natural
+ ordering of the fulloy qualified class names of the property source implementations are used. The reason for
+ not using +@Priority+ annotations is that property sources can define dynamically their ordinals, e.g. based on
+ a property contained with the configuration itself.
+* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within the current
+ +ConfigurationContext+.
+
+This interface can be implemented by any kind of logic. It could be a simple in memory map, a distributed configuration
+provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple
+property sources with additional combination/aggregation rules in place.
+
++PropertySources+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current
+ active +ServiceContext+.
+
+
+[[PropertySourceProvider]]
+==== Interface PropertySourceProvider
+
+Instances of this type can be used to register multiple instances of +PropertySource+.
+
+[source,java]
+--------------------------------------------
+// @FunctionalInterface in Java 8
+public interface PropertySourceProvider{
+ Collection<PropertySource> getPropertySources();
+}
+--------------------------------------------
+
+This allows to evaluate the property sources to be read/that are available dynamically. All property sources
+are read out and added to the current chain of +PropertySource+ instances within the current +ConfigurationContext+,
+refer also to [[ConfigurationContext]].
+
++PropertySourceProviders+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the
+current active +ServiceContext+.
+
+
+[[PropertyFilter]]
+==== Interface PropertyFilter
+
+Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated before a +Configuration+ instance is
+passed to the user. Filters can hereby used for multiple purposes, such as
+
+* resolving placeholders
+* masking sensitive entries, such as passwords
+* constraining visibility based on the current active user
+* ...
+
++PropertyFilters+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current
+active +ServiceContext+. Similar to property sources they are managed in an ordered filter chain, based on the
+applied +@Priority+ annotations.
+
+A +PropertyFilter+ is defined as follows:
+
+[source,java]
+--------------------------------------------
+// Functional Interface
+public interface PropertyFilter{
+ String filterProperty(String value, FilterContext context);
+}
+--------------------------------------------
+
+Hereby:
+
+* returning +null+ will remove the key from the final result
+* non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies
+ filter evaluation has to be continued as long as filters are still changing some of the values to be returned.
+ To prevent possible endless loops after a defined number of loops evaluation is stopped.
+* +FilterContext+ provides additional metdata, inclusing the key accessed, which is useful in many use cases.
+
+This method is called each time a single entry is accessed, and for each property in a full properties result.
+
+
+[[PropertyValueCombinationPolicy]]
+==== Interface PropertyValueCombinationPolicy
+
+This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to
+build up the final Configuration to be passed over to the +PropertyFilters+. The default implementation is just
+overriding all values read before with the new value read. Nevertheless for collections and other use cases it is
+often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the
+new value. Finally looking at the method's signature it may be surprising to find a +Map+ for the value. The basic
+value hereby is defined by +currentValue.get(key)+. Nevertheless the +Map+ may also contain additional meta entries,
+which may be considered by the policy implementation.
+
+[source,java]
+--------------------------------------------
+// FunctionalInterface
+public interface PropertyValueCombinationPolicy{
+
+ PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
+ new PropertyValueCombinationPolicy(){
+ @Override
+ public Map<String,String> collect(Map<String,String> currentValue, String key,
+ PropertySource propertySource) {
+ PropertyValue value = propertySource.get(key);
+ return value!=null?value.getConfigEntries():currentValue;
+ }
+ };
+
+ String collect(Map<String,String> currentValue currentValue, String key,
+ PropertySource propertySource);
+
+}
+--------------------------------------------
+
+
+[[ConfigurationContext]]
+==== The Configuration Context
+
+A +Configuration+ is basically based on a so called +ConfigurationContext+, which is
+accessible from +Configuration.getContext()+:
+
+[source,java]
+.Accessing the current +ConfigurationContext+
+--------------------------------------------
+ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext();
+--------------------------------------------
+
+The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+:
+
+* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances).
+* +PropertyFilters+ registered, which filter values before they are returned to the client
+* +PropertyConverter+ instances that provide conversion functionality for converting String values to any other types.
+* the current +PropertyValueCombinationPolicy+ that determines how property values from different PropertySources are
+ combined to the final property value returned to the client.
+
+
+[[Mutability]]
+==== Changing the current Configuration Context
+
+By default the +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed
+or even not wanted. Nevertheless there are use cases where the current +ConfigurationContext+ (and
+consequently +Configuration+) must be adapted:
+
+* New configuration files where detected in a folder observed by Tamaya.
+* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must
+ be adapted to these changes.
+* The overall configuration context is manually setup by the application logic.
+* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the
+ tests executed.
+
+In such cases the +ConfigurationContext+ must be mutable, meaning it must be possible:
+
+* to add or remove +PropertySource+ instances
+* to add or remove +PropertyFilter+ instances
+* to add or remove +PropertyConverter+ instances
+* to redefine the current +PropertyValueCombinationPolicy+ instances.
+
+This can be achieved by obtaining an instance of +ConfigurationContextBuilder+. Instances of this builder can be
+accessed either
+
+* from the current +ConfigurationContext+, hereby returning a builder instance preinitialized with the values from the
+ current +ConfigurationContext+
+* from the current +ConfigurationProvider+ singleton.
+
+[source,java]
+.Accessing a +ConfigurationContextBuilder+
+--------------------------------------------
+ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder();
+ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();
+--------------------------------------------
+
+With such a builder a new +ConfigurationContext+ can be created and then applied:
+
+[source,java]
+.Creating and applying a new +ConfigurationContext+
+--------------------------------------------
+ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext()
+ .toBuilder();
+ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource())
+ .addPropertyFilter(new MyFilter()).build();
+ConfigurationProvider.setConfigurationContext(context);
+--------------------------------------------
+
+Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw an +UnsupportedOperationException+.
+This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationContextSettable()+.
+
+
+[[ConfigurationProviderSpi]]
+==== Implementing and Managing Configuration
+
+One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interface, which is backing up the
++ConfigurationProvider+ singleton. Implementing this class allows
+
+* to fully determine the implementation class for +Configuration+
+* to manage the current +ConfigurationContext+ in the scope and granularity required.
+* to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context.
+* Performing changes as set with the current +ConfigurationContextBuilder+.
+
+
+[[ServiceContext]]
+==== The ServiceContext
+
+The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya.
+The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the
++ServiceContextManager+ singleton:
+
+[source,java]
+.Accessing the +ServiceContext+
+--------------------------------------------
+ServiceContext serviceContext = ServiceContextManager.getServiceContext();
+
+public interface ServiceContext{
+ int ordinal();
+ <T> T getService(Class<T> serviceType);
+ <T> List<T> getServices(Class<T> serviceType);
+}
+--------------------------------------------
+
+With the +ServiceContext+ a component can be accessed in two different ways:
+
+. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally
+ the most significant instance is returned only.
+. access all items given its type. This will return (by default) all instances loadedable from the current
+ runtime context, ordered by priority, hereby the most significant components added first.
+
+
+## Examples
+### Accessing Configuration
+
+_Configuration_ is obtained from the ConfigurationProvider singleton:
+
+[source,java]
+.Accessing +Configuration+
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+--------------------------------------------
+
+Many users in a SE context will probably only work with _Configuration_, since it offers all functionality
+needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is
+very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _Optional_ is supported:
+
+[source,java]
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+String myKey = config.get("myKey"); // may return null
+int myLimit = config.get("all.size.limit", int.class);
+--------------------------------------------
+
+
+### Environment and System Properties
+
+By default environment and system properties are included into the _Configuration_. So we can access the current
+_PROMPT_ environment variable as follows:
+
+[source,java]
+--------------------------------------------
+String prompt = ConfigurationProvider.getConfiguration().get("PROMPT");
+--------------------------------------------
+
+Similary the system properties are directly applied to the _Configuration_. So if we pass the following system
+property to our JVM:
+
+[source,java]
+--------------------------------------------
+java ... -Duse.my.system.answer=yes
+--------------------------------------------
+
+we can access it as follows:
+
+[source,java]
+--------------------------------------------
+boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class);
+--------------------------------------------
+
+
+### Adding a Custom Configuration
+
+Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
+_tamaya-spi-support_ module you just have to perform a few steps:
+
+. Define a PropertySource as follows:
+
+[source,java]
+--------------------------------------------
+ public class MyPropertySource extends PropertiesResourcePropertySource{
+
+ public MyPropertySource(){
+ super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL);
+ }
+ }
+--------------------------------------------
+
+Then register +MyPropertySource+ using the +ServiceLoader+ by adding the following file:
+
+[source,listing]
+--------------------------------------------
+META-INF/services/org.apache.tamaya.spi.PropertySource
+--------------------------------------------
+
+...containing the following line:
+
+[source,listing]
+--------------------------------------------
+com.mypackage.MyPropertySource
+--------------------------------------------
+
+
+[[APIImpl]]
+== API Implementation
+
+The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for
+further details.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/community.adoc
----------------------------------------------------------------------
diff --git a/content/community.adoc b/content/community.adoc
new file mode 100644
index 0000000..a3219f7
--- /dev/null
+++ b/content/community.adoc
@@ -0,0 +1,143 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya: Community
+
+:sectnums:
+
+// Document properties
+:twitterhandle: tamayaconf
+
+== Users
+
+If you are a new user and you would like to participate in Tamaya
+(would be great!), you can have a look at the current
+project documentation. Apache Tamaya currently does
+not yet have a users mailing list. If you want discuss your use cases
+we encourage you to mailto:dev-subscribe@tamaya.incubator.apache.org[subscribe]
+to our mailto:dev@tamaya.incubator.apache.org[mailing list for developers].
+Furthermore, you can check our xref:a_mailing_lists[mail-archives].
+
+Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^]
+please ask on the mailing list if it's a known issue in case of a
+bug or if there is an ongoing discussion in case of a feature.
+
+You are very welcome to follow our twitter account
+http://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word
+of Tamaya with tweets, blog entries,...
+
+== Getting Involved
+
+Everybody is welcome to get involved with our community. You can find general
+information at http://apache.org/foundation/getinvolved.html and
+http://apache.org/foundation/how-it-works.html.
+The following sections provides some details about the different levels of getting involved.
+
+If you want to contribute to the
+documentation of Apache Tamaya, please
+read the instructions about the Documentation
+that addresses how to contribute, render and publish it.
+
+
+=== Contributors
+
+Before you get a committer you have to contribute to our effort.
+E.g. you can help users, participate in discussions on the dev list,
+submit patches,... . Therefore, it's essential to file
+a http://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^]
+or http://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^]
+and send it to secretary at apache dot org (or fax it) as early as possible.
+
+If you would like to submit a patch through Jira, you can have a look at the
+link:devguide.html[suggested Git approach].
+
+The lists of current contributors and committers can be found
+on the link:team-list.html[team and contributers page^].
+
+
+=== Committers
+
+Before you read this section, please ensure that you have read
+the contributor section. All of you are welcome to join our development effort.
+mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe] to our
+mailto:dev@tamaya.incubator.apache.org[mailing list for developers] and
+start contributing and help users.
+
+// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12
+Optionally mailto:commits-subscribe@tamaya.incubator.apache.org[subscribe] to our
+mailto:commits@tamaya.incubator.apache.org[mailing list for commits].
+Furthermore, you can check our link:community.html#mailing-lists[mail-archives].
+
+Further details are available at http://www.apache.org/dev/[http://www.apache.org/dev/^].
+
+=== Mailing lists
+
+The table below lists all mailings used by the Tamaya project.
+
+[width="70"]
+[cols="5*.<", options="header"]
+|===
+| List
+| Subscribe
+| Unsubscribe
+| Archive
+| Mirrors
+//-- next row
+| Developer List
+| mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe]
+| mailto:dev-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
+| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^]
+|
+//-- next row
+| Committer List
+| mailto:commits-subscribe@tamaya.incubator.apache.org[Subscribe]
+| mailto:commits-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
+| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^]
+|
+|===
+
+=== JIRA
+
+Any kind of issue has to be filed in our
+https://issues.apache.org/jira/browse/TAMAYA[issue tracker^].
+If you have any question, you can ask us
+(e.g. via the mailing list for developers).
+
+=== Spread the word
+
+You are very welcome e.g. to write blog entries, mention our twitter handle
+ @{twitterhandle} if you tweet about the project or just follow our twitter
+account http://twitter.com/{twitterhandle}[@{twitterhandle}^]
+
+=== IRC
+
+Usually discussions happen on the mailing list. Some informal discussions take
+place in our IRC-Channel irc://irc.freenode.net/apache-tamaya.
+
+----
+// with the irssi command-line client:
+$ irssi
+
+> /connect irc.freenode.net
+> /join #apache-tamaya
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/core.adoc
----------------------------------------------------------------------
diff --git a/content/core.adoc b/content/core.adoc
new file mode 100644
index 0000000..fe891b2
--- /dev/null
+++ b/content/core.adoc
@@ -0,0 +1,228 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[Core]]
+== Tamaya Core Implementation
+=== Overview
+
+Tamaya Core provides an implementation of the link:API.html[Tamaya Configuration API] and adds additional functionality
+and building blocks for supporting SPI implementations.
+
+Tamaya Core contains the following artifacts:
+
+* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+
+* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based
+ on the +@Priority+ annotations.
+* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances
+hereby providing type conversion for all important types.
+* A simple default configuration setup using the current classpath and an optional staging variable.
+* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and
+ registers them in the global +ConfigurationContext+
+* It provides a +ConfigurationContextBuilder+ and allows changing the current +ConfigurationContext+.
+
+The overall size of the library is very small. All required components are implemented and registered, so basically the
+Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible
+enough to be extended/accommodated with additional features as needed, such as
+
+* placeholder and resolution mechanisms
+* dynamic resource path lookup, e.g. with ant styled patterns
+* configuration injection and configuration templates
+* abstraction for reusable formats
+* integration with other existing solutions
+* configuration and configuration isolation targeting Java EE
+* dynamic configuration and configuration updates
+* Configuration management extensions
+* remote configuration
+* and more
+
+For details about the extension modules available and their functionality refer to the link:modules.html[extension user guide].
+
+
+[[CorePropertyConverters]]
+=== Default PropertyConverters in Core
+
+As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the
+listing of converters automatically registered with the Core module:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Target Type_ |_Class Name_ |_Supported Formats_
+|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF
+|java.math.BigInteger |BigIntegerConverter |0xFF, 1234
+|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
+|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
+|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123
+|java.ui.lang.Class |ClassConverter |<fully qualified class name>
+|java.util.Currency |CurrencyConverter |CHF, 123
+|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|_Enums_ |EnumConverter |<Enum item name>
+|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
+|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
+|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
+|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
+|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
+|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
+|ZoneId |ZoneIdConverter |Europe/Zurich
+|=======
+
+
+=== Registering PropertyConverters
+
+Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+,
+meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified
+class names of the converters to be registered (one line per each).
+
+Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically.
+
+NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically.
+
+
+[[ComponentLoadingAndPriorization]]
+=== Component Loading and Priorization
+
+Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components
+must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified
+implementation class names of the components to be registered (one line per each).
+The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya
+core adds this functionality by the possibility to add +@Priority+ annotations to the components registered.
+By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning
+
+* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value
+ effectively _overrides/replaces_ any component with lower values.
+* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the
+ ones with higher priority are before components with lower priority.
+* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is
+ still defined and predictable in almost all scenarios.
+
+
+[[RegisteringPropertySources]]
+=== Registering Property Sources
+
+PropertySources that provide configuration properties are registered as ordinary components as described in the previous
+section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit
++int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful
+due to several reasons:
+
+* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being
+ added easily.
+* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or
+ whatever may be appropriate.
+
+
+[[CorePropertySources]]
+== Configuration Setup in Core
+
+Tamaya Core provides a minimal configuration setting, that allows you to configure SE
+applications already easily. Basically configuration is built up by default as follows:
+
+. Read environment properties and add them prefixed with +env.+
+. Read all files found at +META-INF/javaconfiguration.properties+
+ and +META-INF/javaconfiguration.xml+
+
+
+=== Overview of Registered Default Property Sources and Providers
+
+The Tamaya Core implementation provides a couple of default +PropertySource+ implementations, which are automatically
+registered. They are all in the package +org.apache.tamaya.core.propertysource+ and
++org.apache.tamaya.core.provider+:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Type_ |_Class Name_ |_Ordinal Used_
+|META-INF/javaconfiguration.properties |JavaConfigurationProvider |0
+|META-INF/javaconfiguration.xml |JavaConfigurationProvider |0
+|Environment Properties |EnvironmentPropertySource |300
+|System Properties |SystemPropertySource |400
+|=======
+
+
+=== Abstract Class PropertiesFilePropertySource
+
+The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+
+instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor:
+
+[source,java]
+--------------------------------------------
+PropertiesFilePropertySource(URL url);
+--------------------------------------------
+
+
+==== Abstract Class PropertiesPropertySource
+
+The abstract class +PropertiesPropertySource+ can be used for implementing a +PropertySource+ based on a +Properties+
+instance. It requires a +PropertySource+ to be passed on the constructor:
+
+[source,java]
+--------------------------------------------
+PropertiesPropertySource(Properties properties);
+--------------------------------------------
+
+
+==== Abstract Class BasePropertySource
+
+The abstract class +BasePropertySource+ can be used for implementing custom +PropertySource+ classes. It requires only
+one method to implemented:
+
+[source,java]
+.Implementing a PropertySource using BasePropertySource
+--------------------------------------------
+public class MyPropertySource extends BasePropertySource{
+
+ public String getName(){
+ // return a unique name for the property source, e.g. based on the underlying resource. This name also
+ // allows to access the property source later
+ }
+
+ public Map<String, String> getProperties(){
+ // Get a map with all properties provided by this property source
+ // If the property source is not scannable, the map returned may be empty.
+ // In the ladder case the +boolean isScannale()+ must be overridden, since
+ // by default property sources are assumed to be scannable.
+ }
+
+}
+--------------------------------------------
+
+By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in
++PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override
+the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+.
+
+
+[[CorePropertySourceProviders]]
+=== Default PropertySourceProvider in Core
+
+With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+
+present that loads all .properties files found at +META-INF/javaconfiguration.properties+
+and +META-INF/javaconfiguration.xml+.
+
+
+[[Extensions]]
+== Adding Extensions
+
+The Core module only implements the link:API.html[API]. Many users require/wish additional functionality from a
+configuration system. Fortunately there are numerous extensions available that add further functionality.
+Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath.
+
+For detailed information on the extensions available refer to the link:extensions.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/devguide.adoc
----------------------------------------------------------------------
diff --git a/content/devguide.adoc b/content/devguide.adoc
new file mode 100644
index 0000000..6d28edc
--- /dev/null
+++ b/content/devguide.adoc
@@ -0,0 +1,213 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+
+= Apache Tamaya: Development Guide
+
+== Suggested Git Workflows
+
+=== Avoid git pull!
+
+`git pull` should never get invoked if you have dirty files lying around
+or if your branch is ahead of master. This will always lead to
+some dirty artifacts in the commit history:
+
+----
+Merge branch 'master' of http://git-wip-us.apache.org/tamaya into master
+----
+
+=== Use git pull --rebase
+
+An easy version for getting rid of the auto-merges is using
+
+----
+$ git pull --rebase
+----
+
+Please note that this sometimes trashes your working tree if there
+are unmergeable files around. Cleaning this up with a forced manual
+rebase is not something we would recommend for a git beginner.
+
+=== Working in an own branch
+
+This is actually the suggested way to prevent auto-merges. Create an own
+branch where you do your feature work. Either do all your work in one
+branch or create one branch per feature you are working on.
+
+----
+$ git branch mybranch
+----
+
+After you finished your feature, first add (`git add`) and commit (`git commit`) your work.
+Check with `git status` that you don't have any dirty files and uncommitted
+changes around. You can use `git stash` to 'backup' unfinished work.
+
+Then switch back to the master branch and pull changes
+done by other committers in the meantime.
+
+----
+$ git checkout master
+$ git pull --rebase
+----
+
+You should now get all the changes done by other committers and
+the will get applied to your local master branch. Now go back to
+your private branch and rebase your locally performed work to the HEAD of master.
+
+----
+$ git checkout mybranch
+$ git rebase master
+----
+
+If you got conflicts, you will get lines with ">>>>" added to those
+files. Resolve those conflicts manually, add them and finish the rebase.
+
+Check with `git-status` and `gitk` if the merge went well and the history now contains your changes.
+If all is well, go back to the master branch and merge your changes in.
+
+----
+$ git pull --rebase // (just for safety, you should see no changes)
+$ git checkout master
+$ git merge mybranch
+----
+
+Finally you can push your changes to the ASF git repo
+
+----
+$ git push
+----
+
+[[contributing-workflow]]
+== Contribution workflow
+
+=== Creating patches
+
+You should use the following workflow, if you plan to contribute
+patches or new features to Tamaya.
+
+First update you local copy of the repository:
+
+----
+$ git checkout master
+$ git pull --rebase
+----
+
+Then create a new local branch for your work. It's good practice to name
+it after the corresponding JIRA issue.
+
+----
+$ git checkout -b TAMAYA-XXX
+----
+
+Now you can start to work on your patch. When you are finished, commit your changes. But don't forget to **add the name
+of the JIRA issue to the commit message**.
+
+----
+$ git add -am "TAMAYA-XXX: Fixed some issue"
+----
+
+For small patches we recommend to do a single commit containing your changes. For larger contributions you should try
+to group your work into separate sub-tasks that you can commit one by one.
+
+Before you create your patch you should make sure that your local repository is up to date with the master repository.
+This is very important especially if you work on your branch for a long time. Use the following commands to pull the
+latest changes from the upstream repository and rebase your branch against the current master.
+
+
+----
+$ git checkout master
+$ git pull --rebase
+$ git checkout TAMAYA-XXX
+$ git rebase master
+----
+
+Now you are ready to create your patch:
+
+----
+$ git checkout TAMAYA-XXX
+$ git format-patch --stdout master > ../TAMAYA-XXX.patch
+----
+
+Please attach the resulting patch file to the correspoding JIRA issue.
+
+=== Applying patches
+
+If you are a committer and want to apply a patch you should do so in a separate branch.
+
+----
+$ git checkout -b TAMAYA-XXX
+----
+
+Then apply the patch using `git am` and rebase it against the master branch.
+
+----
+$ git am < ../TAMAYA-XXX.patch
+$ git rebase master
+----
+
+After reviewing the changes and testing the code, the changes are ready to
+be merged into the master branch:
+
+----
+$ git checkout master
+$ git merge TAMAYA-XXX
+$ git branch -d TAMAYA-XXX
+----
+
+=== Discussion workflow (optional)
+
+All discussions which lead to a decision take place on the mailing list.
+Sometimes it's required to show-case an idea esp. if the solution is
+more than few lines. As shown above it makes sense to use local branches
+for developing new parts. Git allows to push such local branches to a
+public repository. So it's easier to share it with the community
+for discussing it. The following listings show an example in combination
+with GitHub - for sure it works with any hosting platform like BitBucket,
+Google-Code,... The only important part here is that such branches
+*NEVER* get pushed to the main Apache repository to keep the commit history
+as clean as possible.
+
+=== Initial setup
+
+----
+$ git clone https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git
+$ git remote add discuss https://[username]@github.com/[username]/[repo-name].git
+$ git push -u discuss master
+----
+
+=== Branches for discussions
+
+----
+$ git checkout -b TAMAYA-XXX # 1-n commits
+$ git push discuss TAMAYA-XXX # share the link to the branch for the discussions
+----
+
+*If the community agrees on the suggested change, the implementation will be applied to the origin master. A committer
+has to follow the steps described above for the basic workflow to keep the commit history simple, clean and straight.
+A contributor has to follow the steps described above for creating a patch.*
+
+=== Delete the branch again
+
+----
+$ git push discuss :TAMAYA-XXX
+$ git branch -d TAMAYA-XXX
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/download.adoc
----------------------------------------------------------------------
diff --git a/content/download.adoc b/content/download.adoc
new file mode 100644
index 0000000..37e8c98
--- /dev/null
+++ b/content/download.adoc
@@ -0,0 +1,109 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//:source-highlighter: coderay
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+:linkattrs: true
+
+= Apache Tamaya: Download
+
+The latest release is Apache Tamaya {tamaya_version_released}.
+You can download it it from the
+http://www.apache.org/dist/incubator/tamaya[Apache Software Foundation Distribution Directory^].
+
+The release notes for each release of Apache Tamaya
+can be found at the link:history.html[release history page].
+
+== Current Source Code
+
+Downloading of the the current state of the project can be done by
+
+* cloning the https://github.com/apache/incubator-tamaya[GitHub mirror^]
+* Github also provides an easy way to dowload the current project source as zip archive.
+// @todo * Cloning the Apache source tree, see link:3[source section]. source.html
+
+
+== Maven Dependencies
+
+// @todo
+// @todo Details are available <a href="documentation/#_project_configuration_without_maven">here</a>.
+
+
+// @todo Source highlighting does not work currently.
+//
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>{tamaya_mvn_group_id}</groupId>
+ <artifactId>tamaya-api</artifactId>
+ <version>{tamaya_version_released}</version>
+</dependency>
+<dependency>
+ <groupId>{tamaya_mvn_group_id}</groupId>
+ <artifactId>tamaya-core</artifactId>
+ <version>{tamaya_version_released}</version>
+</dependency>
+----
+
+
+== Previous Releases
+
+All previous releases can also be found at the
+http://www.apache.org/dist/incubator/tamaya/[Apache Software Foundation Distribution Directory^].
+In our link:history.html[release history overview] you can find all previous releases of Tamaya.
+
+== Verifying Releases
+
+It is essential that you verify the integrity of any downloaded files using
+the PGP or MD5 signatures. For more information on signing artifacts and
+why we do it, check out the
+http://www.apache.org/dev/release-signing.html[Release Signing FAQ^].
+
+The PGP signatures can be verified using PGP or GPG. First download the
+http://www.apache.org/dist/incubator/tamaya/KEYS[KEYS file^]
+as well as the asc signature file for the artifact. Make sure you get
+these files from the
+http://www.apache.org/dist/incubator/tamaya/[main distribution directory^]
+rather than from a
+http://www.apache.org/dyn/closer.cgi/tamaya/[mirror^].
+Then verify the signatures using e.g.:
+
+[source,shell]
+----
+$ pgpk -a KEYS
+$ pgpv tamaya-project-1.2.0-source-release.zip.asc
+----
+
+or
+[source,shell]
+----
+$ pgp -ka KEYS
+$ pgp tamaya-project-1.2.0-source-release.zip.asc
+----
+
+or
+
+[source,shell]
+----
+$ gpg --import KEYS
+$ gpg --verify tamaya-project-1.2.0-source-release.zip.asc
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/examples.adoc
----------------------------------------------------------------------
diff --git a/content/examples.adoc b/content/examples.adoc
new file mode 100644
index 0000000..3bc94ef
--- /dev/null
+++ b/content/examples.adoc
@@ -0,0 +1,71 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya: Examples
+
+toc::[]
+
+== Tamaya Examples
+
+=== Minimal
+
+This example shows the basic functionality that is available when Tamaya is used without any further extensions.
+It shows how configuration can be added to the classpath and how it can be accessed.
+
+=== Simple PropertySource
+
+This example shows how to write and register an additional +PropertySource+ and +PropertySourceProvider+, which is
+the SPI to add your own configuration data and locations. For a more advanced example you may also have a look at
+the provided default metamodels, e.g. the simple metamodel (currently in the experimental part and not shipped with
+the current release).
+
+=== Resources
+
+This example shows how resources can be located using ANT-styled paths and this feature can help you to implement
++PropertySourceProvider+ instances that provide configuration for a set of files/folders at a certain (searchable)
+location, as provided by the resource extension_.
+
+=== Resolver
+
+The resolver example defines a configuration file that illustrates the usage of placeholders that are resolved on
+configuration access, as provided by the _resolver extension_.
+
+=== Injection
+
+The injection sample shows how to inject configuration into a created object instance, or how to instantiate a proxied
+configuration template, which provides a type-safe configuration access mechanism. This functionality is provided
+by the _injection extension_. Hereby neither JSR 330 nor 299 are used, so it is pure and minimal SE based
+implementation.
+
+=== FileObserver
+
+This example shows how the +event extension+ can be used to automatically adapt the current configuration when
+the underlying configuration data is changing, e.g. when new configuration is added to a file folder, or removed or
+adapted.
+
+=== Builder
+
+This example shows how to build a +Configuration+ using a simple pure SE builder API as provided by the
+_builder extension_.
+
+=== Remote
+
+THe remote example shows a simple setup where parts of the +Configuration+ are read remotedly.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/extensions.adoc b/content/extensions.adoc
new file mode 100644
index 0000000..93b34b5
--- /dev/null
+++ b/content/extensions.adoc
@@ -0,0 +1,107 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Extension Modules
+
+toc::[]
+
+=== Mature Extensions
+
+Mature extensions have a stable API and SPI, similar to the API and Implementations provided.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+| | N/A: currently no extensions have reached that maturity level. | -
+|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation]
+|=======
+
+
+=== Extensions
+
+Extensions in _draft state_ are tested well and normally should have rather stable APIs. Nevertheless API changes may
+still occurr, but we try to prevent such changes if possible.
+
+NOTE All extensions currently run on Java 7 as well as on Java 8.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-builder+ |Provides a fluent-style builder for configurations | link:extensions/mod_builder.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. | link:extensions/mod_filter.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-model+ |Provides support documenting ang validating configuration during runtime. |link:extensions/mod_model.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
+|=======
+
+=== Integrations
+
+These extensions integrate/bridge Tamayas functionality with other frameworks turning their configuration capabilities
+from a sledgehammer to a scalpell:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-cdi+ | Java EE/standalone compliant CDI integration | link:extensions/mod_cdi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-consul+ | Integration with consul clusters. | link:extensions/mod_consul.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-etcd+ | Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation]
+|=======
+
+
+=== Extensions in Experimental Stage
+
+Extensions in _experimental mode_ may still be under discussions. API changes may still happen, so use them
+very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-staged+ |Simple configuration extension to add staged config. | link:extensions/mod_metamodel-staged.html[Documentation]
+|=======
+
+
+=== Integrations in Experimental Stage
+
+Integrations in _experimental mode_ may still be under discussions, or may even not compile ! API changes may still happen, so use them
+very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-commons+ |Integration with Apache Commons Configuration. | -
+|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_builder.adoc b/content/extensions/mod_builder.adoc
new file mode 100644
index 0000000..d734fec
--- /dev/null
+++ b/content/extensions/mod_builder.adoc
@@ -0,0 +1,101 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Builder
+
+// include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[BuilderCore]]
+== Tamaya Builder (Extension Module)
+=== Overview
+
+The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
+e.g. as follows:
+
+[source,java]
+---------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+// do something
+Configuration config = builder.build();
+---------------------------------------------------------------
+
+Basically the builder allows to create configuration instances completely independent of the current configuration
+setup. This gives you full control on the +Configuration+ setup.
+
+=== Compatibility
+
+The module is based on Java 7, so it will run on Java 7 and does
+not require Java 8. The +ConfigurationProvider+
+as defined by the API, provides a builder instance for +ConfigurationContext+
+in a similar way. A +Configuration+ can also be created by passing an instance of a +ConfigurationContext+:
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding
+dependency to your module:
+
+[source,xml,subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-builder</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+-----------------------------------------------
+
+=== Supported Functionality
+
+The builder allows you to add +PropertySource+ instances:
+
+[source,java]
+----------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+builder.addPropertySources(sourceOne).addPropertySources(sourceTwo);
+Configuration config = builder.build();
+----------------------------------------------------------------
+
+Similarly you can add filters:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertyFilters(new MyConfigFilter());
+----------------------------------------------------------------
+
+...or +PropertySourceProvider+ instances:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertySourceProvider(new MyPropertySourceProvider());
+----------------------------------------------------------------
+
+Also the builder module allows to include/exclude any filters and property source already known to the current
++ConfigurationContext+:
+
+[source,java]
+----------------------------------------------------------------
+builder.disableProvidedPropertyConverters();
+builder.enableProvidedPropertyConverters();
+
+builder.disableProvidedPropertyFilters();
+builder.enableProvidedPropertyFilters();
+
+builder.disableProvidedPropertySources();
+builder.enableProvidedPropertySources();
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_camel.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_camel.adoc b/content/extensions/mod_camel.adoc
new file mode 100644
index 0000000..9d9a60d
--- /dev/null
+++ b/content/extensions/mod_camel.adoc
@@ -0,0 +1,145 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Integration with Apache Camel
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== Integration with Apache Camel (Extension Module)
+=== Overview
+
+The Tamaya Camel integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with Apache Camel.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-camel</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Camel integration comes basically with three artifacts:
+
+* A Camel +ResolverFunction+ implementation adding explicit property resolution
+ (+org.apache.tamaya.integration.camel.TamayaPropertyResolver+).
+* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and
+ additionally allows using Tamaya configuration as Camel _overrides_
+ (+org.apache.tamaya.integration.camel.TamayaPropertiesComponent+).
+
+
+=== Configuring using Camel Java DSL
+
+Camel integration using Java DSL is basically simple:
+
+[source, java]
+-----------------------------------------------
+import org.apache.tamaya.integration.camel.TamayaPropertiesComponent;
+
+camelContext.addComponent("properties", new TamayaPropertiesComponent());
+-----------------------------------------------
+
+Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows:
+
+[source, java]
+-----------------------------------------------
+RouteBuilder builder = new RouteBuilder() {
+ public void configure() {
+ from("direct:hello1").transform().simple("{{cfg:message}}");
+ }
+};
+camelContext.addRoutes(builder);
+builder = new RouteBuilder() {
+ public void configure() {
+ from("direct:hello2").transform().simple("{{tamaya:message}}");
+ }
+};
+camelContext.addRoutes(builder);
+-----------------------------------------------
+
+
+Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used
+as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel
++PropertiesComponent+:
+
+[source, java]
+-----------------------------------------------
+TamayaPropertiesComponent props = new TamayaPropertiesComponent();
+props.setTamayaOverrides(true);
+-----------------------------------------------
+
+
+=== Configuring using Camel XML DSL
+
+Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean
+as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we
+again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback:
+
+[source, xml]
+-----------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
+ ">
+
+ <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring">
+ <route id="r1">
+ <from uri="direct:hello1"/>
+ <transform>
+ <simple>{{message}}</simple>
+ </transform>
+ </route>
+ <route id="r2">
+ <from uri="direct:hello2"/>
+ <transform>
+ <simple>{{cfg:message}}</simple>
+ </transform>
+ </route>
+ <route id="r3">
+ <from uri="direct:hello3"/>
+ <transform>
+ <simple>{{tamaya:message}}</simple>
+ </transform>
+ </route>
+ </routeContext>
+
+ <bean id="properties" class="org.apache.tamaya.integration.camel.TamayaPropertiesComponent">
+ <property name="tamayaOverrides" value="true"/>
+ </bean>
+
+</beans>
+-----------------------------------------------