You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by pl...@apache.org on 2015/06/02 20:22:46 UTC
[1/4] incubator-tamaya git commit: Moved all documents from docs/ to
docs/src/main/asciidoc
Repository: incubator-tamaya
Updated Branches:
refs/heads/master af8b36096 -> 588111340
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_resources.adoc b/docs/src/main/asciidoc/mod_resources.adoc
new file mode 100644
index 0000000..7dc0e38
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_resources.adoc
@@ -0,0 +1,175 @@
+= Apache Tamaya -- Extension: Resources
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.resources
+:title: Apache Tamaya Extension: Resources
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[Core]]
+== Tamaya Resources (Extension Module)
+=== Overview
+
+Tamaya Resources is an extension module. Refer to the 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]
+-----------------------------------------------
+<dependency>
+ <grooupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-resources</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+The module's main entry point is the singleton class +org.apache.tamaya.resource.Resources+. This class provides
+access to a +ResourceResolver+ instance:
+
+[source,java]
+-----------------------------------------------
+public interface ResourceResolver {
+ default Collection<URL> getResources(Collection<String> expressions) {...}
+ default Collection<URL> getResources(String... expressions) {...}
+ default 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.
+
+
+=== 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;
+ }
+ }
+
+}
+-------------------------------------------------------------
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/modules.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/modules.adoc b/docs/src/main/asciidoc/modules.adoc
new file mode 100644
index 0000000..00dd3bc
--- /dev/null
+++ b/docs/src/main/asciidoc/modules.adoc
@@ -0,0 +1,62 @@
+Apache Tamaya -- Extension Modules
+==================================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya Extension Modules
+:revnumber: {tamayaVersion}
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+toc::[]
+
+== Mature Extensions
+
+N/A
+
+== Draft Extensions
+
+[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:mod_builder.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:mod_resources.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:mod_resolver.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:mod_events.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:mod_formats.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:mod_injection.html[Documentation]
+|=======
+
+
+== Extensions in Experimental Stage
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:mod_jodatime.html[Documentation]
+|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/combine-configs.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/combine-configs.adoc b/docs/src/main/asciidoc/uc/combine-configs.adoc
new file mode 100644
index 0000000..2d83ab7
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/combine-configs.adoc
@@ -0,0 +1,14 @@
+=== 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.
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/context-dependent-configuration.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/context-dependent-configuration.adoc b/docs/src/main/asciidoc/uc/context-dependent-configuration.adoc
new file mode 100644
index 0000000..737232f
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/context-dependent-configuration.adoc
@@ -0,0 +1,7 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/dynamic-provisioning.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/dynamic-provisioning.adoc b/docs/src/main/asciidoc/uc/dynamic-provisioning.adoc
new file mode 100644
index 0000000..2facc67
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/dynamic-provisioning.adoc
@@ -0,0 +1,17 @@
+=== 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/external-configuration.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/external-configuration.adoc b/docs/src/main/asciidoc/uc/external-configuration.adoc
new file mode 100644
index 0000000..ea2e687
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/external-configuration.adoc
@@ -0,0 +1,6 @@
+=== 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/formats.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/formats.adoc b/docs/src/main/asciidoc/uc/formats.adoc
new file mode 100644
index 0000000..7383b0d
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/formats.adoc
@@ -0,0 +1,7 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/injection.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/injection.adoc b/docs/src/main/asciidoc/uc/injection.adoc
new file mode 100644
index 0000000..4468d6c
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/injection.adoc
@@ -0,0 +1,31 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/java8.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/java8.adoc b/docs/src/main/asciidoc/uc/java8.adoc
new file mode 100644
index 0000000..fe892cb
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/java8.adoc
@@ -0,0 +1,13 @@
+=== 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.
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/locations.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/locations.adoc b/docs/src/main/asciidoc/uc/locations.adoc
new file mode 100644
index 0000000..f18d7f6
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/locations.adoc
@@ -0,0 +1,9 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/management.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/management.adoc b/docs/src/main/asciidoc/uc/management.adoc
new file mode 100644
index 0000000..ff997a5
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/management.adoc
@@ -0,0 +1,7 @@
+=== 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
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/minimal-propertysource.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/minimal-propertysource.adoc b/docs/src/main/asciidoc/uc/minimal-propertysource.adoc
new file mode 100644
index 0000000..ee185a0
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/minimal-propertysource.adoc
@@ -0,0 +1,6 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/multiple-configurations.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/multiple-configurations.adoc b/docs/src/main/asciidoc/uc/multiple-configurations.adoc
new file mode 100644
index 0000000..2ee133f
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/multiple-configurations.adoc
@@ -0,0 +1,14 @@
+=== 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/scannable-properties.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/scannable-properties.adoc b/docs/src/main/asciidoc/uc/scannable-properties.adoc
new file mode 100644
index 0000000..e2a6b64
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/scannable-properties.adoc
@@ -0,0 +1,4 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/service-context.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/service-context.adoc b/docs/src/main/asciidoc/uc/service-context.adoc
new file mode 100644
index 0000000..31ffaaa
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/service-context.adoc
@@ -0,0 +1,14 @@
+=== 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.
+
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/simple-access.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/simple-access.adoc b/docs/src/main/asciidoc/uc/simple-access.adoc
new file mode 100644
index 0000000..bc1bf59
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/simple-access.adoc
@@ -0,0 +1,18 @@
+=== 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.
+
+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:
+
+@Inject
+private Configuration cfg;
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/simple-property-access.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/simple-property-access.adoc b/docs/src/main/asciidoc/uc/simple-property-access.adoc
new file mode 100644
index 0000000..81fb879
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/simple-property-access.adoc
@@ -0,0 +1,9 @@
+=== 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+.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/templates.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/templates.adoc b/docs/src/main/asciidoc/uc/templates.adoc
new file mode 100644
index 0000000..0aff6c3
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/templates.adoc
@@ -0,0 +1,11 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/type-safe-properties.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/type-safe-properties.adoc b/docs/src/main/asciidoc/uc/type-safe-properties.adoc
new file mode 100644
index 0000000..e71d31c
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/type-safe-properties.adoc
@@ -0,0 +1,10 @@
+=== 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.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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/uc/value-placeholders.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/uc/value-placeholders.adoc b/docs/src/main/asciidoc/uc/value-placeholders.adoc
new file mode 100644
index 0000000..57857a8
--- /dev/null
+++ b/docs/src/main/asciidoc/uc/value-placeholders.adoc
@@ -0,0 +1,8 @@
+=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/usecases.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/usecases.adoc b/docs/src/main/asciidoc/usecases.adoc
new file mode 100644
index 0000000..4c9d88a
--- /dev/null
+++ b/docs/src/main/asciidoc/usecases.adoc
@@ -0,0 +1,59 @@
+= Apache Tamaya -- Use Cases
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya
+:revnumber: 0.1-SNAPSHOT
+:revremark: Incubator
+:revdate: November 2014
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: OBF
+:author: Oliver B. Fischer
+:email: <pl...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+toc::[]
+
+
+== Use Cases for Java SE Environments
+
+include::uc/simple-access.adoc[]
+include::uc/simple-property-access.adoc[]
+include::uc/value-placeholders.adoc[]
+include::uc/type-safe-properties.adoc[]
+include::uc/templates.adoc[]
+include::uc/java8.adoc[]
+include::uc/locations.adoc[]
+include::uc/formats.adoc[]
+include::uc/multiple-configurations.adoc[]
+include::uc/external-configuration.adoc[]
+include::uc/context-dependent-configuration.adoc[]
+include::uc/dynamic-provisioning.adoc[]
+include::uc/minimal-propertysource.adoc[]
+include::uc/scannable-properties.adoc[]
+include::uc/combine-configs.adoc[]
+include::uc/management.adoc[]
+include::uc/service-context.adoc[]
+include::uc/injection.adoc[]
+
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/combine-configs.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/combine-configs.adoc b/docs/uc/combine-configs.adoc
deleted file mode 100644
index 2d83ab7..0000000
--- a/docs/uc/combine-configs.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-=== 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.
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/context-dependent-configuration.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/context-dependent-configuration.adoc b/docs/uc/context-dependent-configuration.adoc
deleted file mode 100644
index 737232f..0000000
--- a/docs/uc/context-dependent-configuration.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/dynamic-provisioning.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/dynamic-provisioning.adoc b/docs/uc/dynamic-provisioning.adoc
deleted file mode 100644
index 2facc67..0000000
--- a/docs/uc/dynamic-provisioning.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-=== 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/external-configuration.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/external-configuration.adoc b/docs/uc/external-configuration.adoc
deleted file mode 100644
index ea2e687..0000000
--- a/docs/uc/external-configuration.adoc
+++ /dev/null
@@ -1,6 +0,0 @@
-=== 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/formats.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/formats.adoc b/docs/uc/formats.adoc
deleted file mode 100644
index 7383b0d..0000000
--- a/docs/uc/formats.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/injection.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/injection.adoc b/docs/uc/injection.adoc
deleted file mode 100644
index 4468d6c..0000000
--- a/docs/uc/injection.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/java8.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/java8.adoc b/docs/uc/java8.adoc
deleted file mode 100644
index fe892cb..0000000
--- a/docs/uc/java8.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-=== 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.
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/locations.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/locations.adoc b/docs/uc/locations.adoc
deleted file mode 100644
index f18d7f6..0000000
--- a/docs/uc/locations.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/management.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/management.adoc b/docs/uc/management.adoc
deleted file mode 100644
index ff997a5..0000000
--- a/docs/uc/management.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-=== 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
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/minimal-propertysource.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/minimal-propertysource.adoc b/docs/uc/minimal-propertysource.adoc
deleted file mode 100644
index ee185a0..0000000
--- a/docs/uc/minimal-propertysource.adoc
+++ /dev/null
@@ -1,6 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/multiple-configurations.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/multiple-configurations.adoc b/docs/uc/multiple-configurations.adoc
deleted file mode 100644
index 2ee133f..0000000
--- a/docs/uc/multiple-configurations.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-=== 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/scannable-properties.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/scannable-properties.adoc b/docs/uc/scannable-properties.adoc
deleted file mode 100644
index e2a6b64..0000000
--- a/docs/uc/scannable-properties.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/service-context.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/service-context.adoc b/docs/uc/service-context.adoc
deleted file mode 100644
index 31ffaaa..0000000
--- a/docs/uc/service-context.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-=== 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.
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/simple-access.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/simple-access.adoc b/docs/uc/simple-access.adoc
deleted file mode 100644
index bc1bf59..0000000
--- a/docs/uc/simple-access.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-=== 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.
-
-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:
-
-@Inject
-private Configuration cfg;
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/simple-property-access.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/simple-property-access.adoc b/docs/uc/simple-property-access.adoc
deleted file mode 100644
index 81fb879..0000000
--- a/docs/uc/simple-property-access.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-=== 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+.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/templates.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/templates.adoc b/docs/uc/templates.adoc
deleted file mode 100644
index 0aff6c3..0000000
--- a/docs/uc/templates.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/type-safe-properties.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/type-safe-properties.adoc b/docs/uc/type-safe-properties.adoc
deleted file mode 100644
index e71d31c..0000000
--- a/docs/uc/type-safe-properties.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-=== 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.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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/uc/value-placeholders.adoc
----------------------------------------------------------------------
diff --git a/docs/uc/value-placeholders.adoc b/docs/uc/value-placeholders.adoc
deleted file mode 100644
index 57857a8..0000000
--- a/docs/uc/value-placeholders.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-=== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/usecases.adoc
----------------------------------------------------------------------
diff --git a/docs/usecases.adoc b/docs/usecases.adoc
deleted file mode 100644
index 4c9d88a..0000000
--- a/docs/usecases.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-= Apache Tamaya -- Use Cases
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya
-:revnumber: 0.1-SNAPSHOT
-:revremark: Incubator
-:revdate: November 2014
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: OBF
-:author: Oliver B. Fischer
-:email: <pl...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-toc::[]
-
-
-== Use Cases for Java SE Environments
-
-include::uc/simple-access.adoc[]
-include::uc/simple-property-access.adoc[]
-include::uc/value-placeholders.adoc[]
-include::uc/type-safe-properties.adoc[]
-include::uc/templates.adoc[]
-include::uc/java8.adoc[]
-include::uc/locations.adoc[]
-include::uc/formats.adoc[]
-include::uc/multiple-configurations.adoc[]
-include::uc/external-configuration.adoc[]
-include::uc/context-dependent-configuration.adoc[]
-include::uc/dynamic-provisioning.adoc[]
-include::uc/minimal-propertysource.adoc[]
-include::uc/scannable-properties.adoc[]
-include::uc/combine-configs.adoc[]
-include::uc/management.adoc[]
-include::uc/service-context.adoc[]
-include::uc/injection.adoc[]
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 0c22417..aec4283 100644
--- a/pom.xml
+++ b/pom.xml
@@ -545,6 +545,7 @@ under the License.
<exclude>**/bootstrap-*</exclude>
<exclude>**/js/jquery-*</exclude>
<exclude>**/*.json</exclude>
+ <exclude>**/*.adoc</exclude>
<!-- json can't get comments -->
</excludes>
</configuration>
[4/4] incubator-tamaya git commit: Moved all documents from docs/ to
docs/src/main/asciidoc
Posted by pl...@apache.org.
Moved all documents from docs/ to docs/src/main/asciidoc
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/58811134
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/58811134
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/58811134
Branch: refs/heads/master
Commit: 58811134017af53f3ac43292325a47f3e702b1c1
Parents: af8b360
Author: Oliver B. Fischer <pl...@apache.org>
Authored: Tue Jun 2 20:21:11 2015 +0200
Committer: Oliver B. Fischer <pl...@apache.org>
Committed: Tue Jun 2 20:21:11 2015 +0200
----------------------------------------------------------------------
docs/API.adoc | 709 -------------------
docs/Core.adoc | 269 -------
docs/HighLevelDesign.adoc | 210 ------
docs/Requirements.adoc | 268 -------
docs/index.adoc | 195 -----
docs/misc/PossibleContributions.adoc | 388 ----------
docs/misc/examples.adoc | 76 --
docs/mod_builder.adoc | 50 --
docs/mod_events.adoc | 57 --
docs/mod_formats.adoc | 61 --
docs/mod_injection.adoc | 214 ------
docs/mod_jodatime.adoc | 89 ---
docs/mod_resolver.adoc | 116 ---
docs/mod_resources.adoc | 175 -----
docs/modules.adoc | 62 --
docs/src/main/asciidoc/API.adoc | 709 +++++++++++++++++++
docs/src/main/asciidoc/Core.adoc | 269 +++++++
docs/src/main/asciidoc/HighLevelDesign.adoc | 210 ++++++
docs/src/main/asciidoc/Requirements.adoc | 268 +++++++
docs/src/main/asciidoc/index.adoc | 195 +++++
.../asciidoc/misc/PossibleContributions.adoc | 388 ++++++++++
docs/src/main/asciidoc/misc/examples.adoc | 76 ++
docs/src/main/asciidoc/mod_builder.adoc | 50 ++
docs/src/main/asciidoc/mod_events.adoc | 57 ++
docs/src/main/asciidoc/mod_formats.adoc | 61 ++
docs/src/main/asciidoc/mod_injection.adoc | 214 ++++++
docs/src/main/asciidoc/mod_jodatime.adoc | 89 +++
docs/src/main/asciidoc/mod_resolver.adoc | 116 +++
docs/src/main/asciidoc/mod_resources.adoc | 175 +++++
docs/src/main/asciidoc/modules.adoc | 62 ++
docs/src/main/asciidoc/uc/combine-configs.adoc | 14 +
.../uc/context-dependent-configuration.adoc | 7 +
.../main/asciidoc/uc/dynamic-provisioning.adoc | 17 +
.../asciidoc/uc/external-configuration.adoc | 6 +
docs/src/main/asciidoc/uc/formats.adoc | 7 +
docs/src/main/asciidoc/uc/injection.adoc | 31 +
docs/src/main/asciidoc/uc/java8.adoc | 13 +
docs/src/main/asciidoc/uc/locations.adoc | 9 +
docs/src/main/asciidoc/uc/management.adoc | 7 +
.../asciidoc/uc/minimal-propertysource.adoc | 6 +
.../asciidoc/uc/multiple-configurations.adoc | 14 +
.../main/asciidoc/uc/scannable-properties.adoc | 4 +
docs/src/main/asciidoc/uc/service-context.adoc | 14 +
docs/src/main/asciidoc/uc/simple-access.adoc | 18 +
.../asciidoc/uc/simple-property-access.adoc | 9 +
docs/src/main/asciidoc/uc/templates.adoc | 11 +
.../main/asciidoc/uc/type-safe-properties.adoc | 10 +
.../main/asciidoc/uc/value-placeholders.adoc | 8 +
docs/src/main/asciidoc/usecases.adoc | 59 ++
docs/uc/combine-configs.adoc | 14 -
docs/uc/context-dependent-configuration.adoc | 7 -
docs/uc/dynamic-provisioning.adoc | 17 -
docs/uc/external-configuration.adoc | 6 -
docs/uc/formats.adoc | 7 -
docs/uc/injection.adoc | 31 -
docs/uc/java8.adoc | 13 -
docs/uc/locations.adoc | 9 -
docs/uc/management.adoc | 7 -
docs/uc/minimal-propertysource.adoc | 6 -
docs/uc/multiple-configurations.adoc | 14 -
docs/uc/scannable-properties.adoc | 4 -
docs/uc/service-context.adoc | 14 -
docs/uc/simple-access.adoc | 18 -
docs/uc/simple-property-access.adoc | 9 -
docs/uc/templates.adoc | 11 -
docs/uc/type-safe-properties.adoc | 10 -
docs/uc/value-placeholders.adoc | 8 -
docs/usecases.adoc | 59 --
pom.xml | 1 +
69 files changed, 3204 insertions(+), 3203 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/API.adoc
----------------------------------------------------------------------
diff --git a/docs/API.adoc b/docs/API.adoc
deleted file mode 100644
index d9b1031..0000000
--- a/docs/API.adoc
+++ /dev/null
@@ -1,709 +0,0 @@
-Apache Tamaya -- API
-====================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya
-:revnumber: 0.1-SNAPSHOT
-:revremark: Incubator
-:revdate: January 2014
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
-
-toc::[]
-
-<<<
-:numbered!:
------------------------------------------------------------
-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.
------------------------------------------------------------
-
-:numbered:
-
-[[CoreDesign]]
-== The Tamaya Core 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. As a starting point we recommend you read the corresponding
-link:CoreDesign.html[Core Design Documentation]
-
-[[API]]
-== The Tamaya API
-The API provides the artifacts as described in the link:CoreDesign.html[Core 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+) based on +UnaryOperator<Configuration>+ (operator) and
- +Function<Configuration,T>+ (query).
- ** +ConfigurationProvider+ provides the static entry point for accessing configuration.
- ** +ConfigProvider+ provides static access to the current +Configuration+ (default configuration)
- ** +ConfigException+ defines a runtime exception for usage by the configuration system.
- ** +TypeLiteral+ provides a possibility to type safe define the target type to be returned by a registered
- +PropertyProvider+.
- ** +PropertyConverter+, which defines conversion of String values into any required target types.
-
-* Additionally the *SPI* provides:
- ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+
- hereby
- *** is designed as a minimalistic data interface to be implemented by any kind of data providers (local or remote)
- *** provides data key/value pairs in raw format as String key/values only
- *** can optionally support scanning of its provided values
- ** _PropertySourceProvider:_ allows to add property sources dynamically.
- ** +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 parts of the API, which is quite small:
-
-* +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.
-
-
-==== Configuration (Java 7)
-
-The minimal API defined for Java version earlier than Java 8 looks as follows:
-
-[source,java]
-.Interface Configuration in Java 7
---------------------------------------------
-public interface Configuration{
- String get(String key);
- <T> T get(String key, Class<T> type);
- <T> T get(String key, TypeLiteral<T> type);
- Map<String,String> getProperties();
-
- // extension points
- Configuration with(ConfigOperator operator);
- <T> T query(ConfigQuery<T> query);
-}
---------------------------------------------
-
-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.
-
-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+.
-
-==== Configuration (Java 8)
-
-The API for Java 8 adds additional support for +Optional+:
-
-[source,java]
-.Interface Configuration in Java 8
---------------------------------------------
-public interface Configuration{
- // methods also defined in Java 7
- String get(String key);
- <T> T get(String key, Class<T> type);
- <T> T get(String key, TypeLiteral<T> type);
- Map<String,String> getProperties();
- Configuration with(ConfigOperator operator);
- <T> T query(ConfigQuery<T> query);
-
- // new java 8 optional support
- default Optional<String> getOptional(String key){...}
- default <T> Optional<T> getOptional(String key, Class<T> type){...}
- default <T> Optional<T> getOptional(String key, TypeLiteral<T> type){...}
-
- default Boolean getBoolean(String key){...}
- default OptionalInt getInteger(String key){...}
- default OptionalLong getLong(String key){...}
- default OptionalDouble getDouble(String key){...}
-}
---------------------------------------------
-
-Hereby
-
-* +get(String)+ and +getOptional(String)+ provide easy access to any kind of configuration properties in their
- String format.
-* +get(String, TypeLiteral)+, +getOptional(String, TypeLiteral)+, +get(String, Class)+ and
- +getOptional(String, Class)+ provide type safe access to configuration properties.
- +PropertyConverter+ instances can be registered for a given
- target type. The are managed in an ordered list, whereas the ordering is defined by +@Priority+ annotations
- on the converters.
-* +getProperties()+ gives access to all known (=scannable) properties.
-* +with, query+ provide the extension points for adding additional functionality modelled by +ConfigOperator,
- ConfigQuery+.
-
-Instances of +Configuration+ can be accessed, exactly like in Java 7, from the +ConfigurationProvider+ singleton:
-
-[source,java]
-.Accessing Configuration
---------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
---------------------------------------------
-
-Hereby the +ConfigurationProvider+ 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);
- //X TODO Collection<String> getSupportedFormats();
-}
---------------------------------------------
-
-+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 = Configuration.current().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.getOptional("foo").isPresent()?;
- 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]
---------------------------------------------
-// @FunctionalInterface in Java 8
-public interface PropertyConverter{
- String filterProperty(String key, String valueToBeFiltered);
-}
---------------------------------------------
-
-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.
-
-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.
-
-[source,java]
---------------------------------------------
-@FunctionalInterface
-public interface PropertyValueCombinationPolicy{
-
- public final PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
- (current, key, propertySource) -> Optional.ofNullable(propertySource.get(key))
- .filter(s -> !s.isEmpty())
- .orElse(current);
-
- String collect(String currentValue, String key, PropertySource propertySource);
-}
---------------------------------------------
-
-
-[[ConfigurationContext]]
-==== The Configuration Context
-
-A +Configuration+ is basically based on a so called +ConfigurationContext+, which is
-managed by the +ConfigurationProvider+. Similarly the current +ConfigurationContext+ can be accessed from the
-+ConfigurationProvider+ singleton:
-
-[source,java]
-.Accessing the current +ConfigurationContext+
---------------------------------------------
-ConfigurationContext context = ConfigurationProvider.getConfigurationContext();
---------------------------------------------
-
-The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+:
-
-* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances).
-* +PropertyFilter+ registered that 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 most cases mutability is also not wanted
-or at least not a needed feature. 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.getConfigurationContext().toBuilder();
-ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();
---------------------------------------------
-
-With such a builder a nre +ConfigurationContext+ can be created and then applied:
-
-[source,java]
-.Creating and applying a new +ConfigurationContext+
---------------------------------------------
-ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfigurationContext().toBuilder();
-ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource())
- .addPropertyFilter(new MyFilter()).build();
-ConfigurationProvider.setConfigurationContext(context);
---------------------------------------------
-
-Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw a +UnsupportedOperationException+. if not
-sure one may access the method +boolean ConfigurationProvider.isConfigurationContextSettable()+ to check if the current
-+ConfigurationContext+ is mutable.
-
-
-[[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.getInt("all.size.limit").getAsInt(); // Never returns null
---------------------------------------------
-
-In Java 8 the following would be possible as well:
-
-[source,java]
---------------------------------------------
-int myLimit = config.getOptionalInt("all.size.limit").getAsInt(); // OptionalInt
-Class<T> targetClass = config.get("myClass", Class.class); // Optional<Class>, returns never null
---------------------------------------------
-
-
-### Environment and System Properties
-
-By default environment and system properties are provided automatically as part of the default _Configuration_. The
-environment properties hereby are prefixed with _env._. So we can access the current _PROMPT_ environment variable
-as follows:
-
-[source,java]
---------------------------------------------
-String prompt = ConfigurationProvider.getConfiguration().get("env.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.getBoolean("use.my.system.answer");
---------------------------------------------
-
-
-### Adding a Custom Configuration
-
-Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
-Tamaya core module you just have to perform the following steps:
-
-. Define a PropertySource as follows:
-
-[source,java]
---------------------------------------------
- public class MyPropertySource extends PropertiesFilePropertySource{
-
- public MyPropertySource(){
- super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"));
- }
- }
---------------------------------------------
-
-. Register the new PropertySource using the ServiceLoader by adding the following file:
-
-[source,listing]
---------------------------------------------
-META-INF/services/org.apache.tamaya.spi.PropertySource
---------------------------------------------
-
-And adding there the entry for the new PropertySource:
-
-[source,listing]
---------------------------------------------
-comp.mapackage.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/blob/58811134/docs/Core.adoc
----------------------------------------------------------------------
diff --git a/docs/Core.adoc b/docs/Core.adoc
deleted file mode 100644
index 3bb82e4..0000000
--- a/docs/Core.adoc
+++ /dev/null
@@ -1,269 +0,0 @@
-Apache Tamaya -- Core
-=====================
-:name: Tamaya
-:rootpackage: org.apache.tamaya.core
-:title: Apache Tamaya Core
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[Core]]
-== Tamaya Core
-=== 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.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
-|java.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
-|java.lang.Character |CharConverter |0xFF, 'a', 'H', 123
-|java.lang.Class |ClassConverter |<fully qualified class name>
-|java.util.Currency |CurrencyConverter |CHF, 123
-|java.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
-|_Enums_ |EnumConverter |<Enum item name>
-|java.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
-|java.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.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
-|java.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
-|java.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, but already powerful configuration setting, that allows you to configure SE
-applications already easily. Basically you can provide configuration properties using the following formats and
-locations (from weakest to strongest):
-
-. Read environment properties and add them prefixed with +env.+
-. Read all files found in +META-INF/cfg/defaults.properties+
-. Read all files found in +META-INF/cfg/${tamaya.stage}/defaults.properties+
-. Read all files found in +META-INF/cfg/config.properties+
-. Read all files found in +META-INF/cfg/${tamaya.stage}/config.properties+
-. Read current system properties.
-
-Hereby +tamaya.stage+ can be set by setting an according environment property, or by applying (overriding any environment
-property) a corresponding system property:
-
-[source, listing]
------------------------------------------
--Dtamaya.stage=test
------------------------------------------
-
-If not set the staging locations will be ignored.
-
-
-=== 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+:
-
-[width="100%",frame="1",options="header",grid="all"]
-|=======
-|_Type_ |_Class Name_ |_Ordinal Used_
-|Environment Properties |EnvironmentPropertySource |300
-|System Properties |SystemPropertySource |400
-|Base Implementation |BasePropertySource |1000
-|Properties Implementation |PropertiesPropertySource |1000
-|Properties Implementation based on a URL |PropertiesFilePropertySource |1000
-|=======
-
-There is also a class +DefaultOrdinal+, which defines several default ordinals. Beside the ordinals for system
-and environment properties above, there may additional default ordinals defined in the future.
-
-
-=== 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+.
-
-
-[[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 different 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:modules.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/HighLevelDesign.adoc
----------------------------------------------------------------------
diff --git a/docs/HighLevelDesign.adoc b/docs/HighLevelDesign.adoc
deleted file mode 100644
index 825bfa7..0000000
--- a/docs/HighLevelDesign.adoc
+++ /dev/null
@@ -1,210 +0,0 @@
-Apache Tamaya -- High Level Design
-==================================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya
-:revnumber: 0.1-SNAPSHOT
-:revremark: Incubator
-:revdate: January 2014
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
-
-toc::[]
-
-<<<
-:numbered!:
------------------------------------------------------------
-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.
------------------------------------------------------------
-
-:numbered:
-
-[[Core Concepts]]
-== The Tamaya Core Parts
-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
-* 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.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 basically is compatible with Java 7 and Java 8. Java 8 additionally introduces additional methods
-hereby leveraging the newly added Java 8 +Optional+ features and _default_ methods.
-
-== Further Documentation
-
-Being here we recommend to have a look at the more detailed documentation of Tamaya's link:API.html[API] and
-link:SPI.html[SPI], and of its current available link:modules.html[modules].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/Requirements.adoc
----------------------------------------------------------------------
diff --git a/docs/Requirements.adoc b/docs/Requirements.adoc
deleted file mode 100644
index ca64fcd..0000000
--- a/docs/Requirements.adoc
+++ /dev/null
@@ -1,268 +0,0 @@
-Apache Tamaya -- Requirements
-=============================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya Requirements
-:revnumber: 1.0
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: OBF
-:author: Oliver B. Fischer
-:email: <pl...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-toc::[]
-<<<
-[[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/blob/58811134/docs/index.adoc
----------------------------------------------------------------------
diff --git a/docs/index.adoc b/docs/index.adoc
deleted file mode 100644
index 5707fc5..0000000
--- a/docs/index.adoc
+++ /dev/null
@@ -1,195 +0,0 @@
-Apache Tamaya -- Documentation
-==============================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya
-:revnumber: 0.1-SNAPSHOT
-:revremark: Incubator
-:revdate: November 2014
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
-
-toc::[]
-
-<<<
-:numbered!:
------------------------------------------------------------
-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.
------------------------------------------------------------
-
-:numbered:
-
-<<<
-
-== Introduction
-[[WhatIsTamaya]]
-=== What is Apache Tamaya?
-Tamaya is a very powerful yet flexible configuration solution. It's core is built based on a few simple concepts.
-Summarizing Tamaya provides you
-
-* a simple _key/value_ configuration model.
-* a uniform API for accessing _configuration_, regardless if you are running in a Java SE, Java EE or OSGI environment.
- This API is capable of hiding all the complexities in configuration management, your developers only need to know,
- where and in which format configuration can be added to the system.
-* A +ConfigurationBuilder+ allowing you to create a configuration completely manually and managing the configuration
- lifecycle on your own.
-* a minimalistic implementation, which in the future might also be targeting Java ME environments.
-* a powerful SPI that allows you to extend/adapt Tamaya with all kind of additional mechanisms commonly used in
- many use cases.
-* a bunch of modules that can be added to your classpath thus adding different functionality to your system as needed.
-
-
-=== What is Apache Tamaya NOT?
-
-Nevertheless there are a few things that are not part of Tamaya:
-
-* Tamaya comes as a modular framework, where you have to decide, which features make sense for you. So you have to do
- a selection, which modules make sense.
-* Though Tamaya comes with a very minimalistic configuration scheme out-of-the-box, it does by default typically not
- cover your enterprise requirements. Also here Tamaya offers hooks and examples showing how you can easily
- replace your current configuration logic with Tamaya. So you must know how you want to organize configuration in
- your enterprise context, such as supported file locations, formats, overriding and filter rules etc.
-
-
-[[WorkingGroup]]
-=== Working Group
-This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This
-specification is the result of the collaborative work of the members of the Tamaya Users Group and the community at
-large.
-
-=== Goals
-Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of
-well defined aspects of a software product without having to recompile/rebuild the code. Summarizing configuration
-can affect basically every part of a system, which renders configuration to a real cross-cutting concern, usable in
-many facets.
-
-=== Targets
-Tamaya targets to support all general configuration aspects in a system, e.g.
-
-* application configuration
- ** plugins
- ** modules
- ** components
-* Container configuration, e.g. of Java EE enabling portability and dynamic provisioning
-* Configuration of CDI (interceptors, decorators and alternatives)
-* Configuration of Bean Validation, JSF, web applications etc.
-* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values,
- and by providing accessors to evaluate current configuration values. This can be used explicitly or transparently
- by client code.
-
-Since configuration is implemented and applied in various ways Tamaya will allow you to use
-
-* multiple configuration locations, including remote locations
-* multiple configuration formats, including custom formats
-* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und
- URIs are supported by default.
-* type conversion
-* configuration filtering and property adapters
-* configuration of collections
-
-The Tamaya project consists of the following parts:
-
-* The link:API.html[API] is a complete SE based configuration API, that provides the minimum of functionality needed.
- It is modelled in a extensible way and only requires a few kb. The main features supported by the link:API.html[] are:
- ** Reading configuration as String/String key/value pairs
- ** Reading configuration as type safe values, including type conversion.
- ** Converting/mapping configuration using operators and queries.
- ** An SPI providing abstractions for handling property sources, property filters and component lifecycle management.
-
-* The link:Core.html[Core] implements the link:API.html[API]. Basically with the core part (and the API) you are ready
-to go, but you may want to add additional extensions that provide more features that are very useful.
-* Extensions are additional libraries that you can add to your project setup. Most important features are:
- ** Dynamic resolution of configured values.
- ** Pattern based resource location
- ** Configuration injection and configuration template support
- ** Support for additional configuration formats
- ** Collection Support
- ** Prepared configuration metamodels
- ** Integration with other frameworks as configuration consumer or producer.
-* Finally the *documentation* module provides comprehensive documentation on all features provided.
-
-
-=== Required Java version
-The full API is based on Java SE 8.0 language features, whereas a compatible implementation of API and Core
-is similarly available for Java SE 7 as well.
-
-
-== Where should I continue
-
-=== Further Documentation
-
-* If you want to have a deeper look at the API/SPI, we recommend the link:API.html[API documentation].
-* If you want to have an overview about the available modules, continue link:modules.html[here].
-* If you want to look to the numerous examples, continue link:examples.html[here].
-* If you are interested in the software design in place, continue link:HighLevelDesign.html[here].
-
-Finally
-* If you are interested in the collected requirements, continue link:Requirements.html[here].
-* If you are interested in the collected use cases, continue link:usecases.html[here].
-
-=== API Documentation
-
-Javadoc of the current API
-
-* link:API.html[General API Documentation] and link:../javadoc/api/java7/index.html[API Javadoc for Java7] /
- link:../javadoc/api/java8/index.html[API Javadoc for Java8]
-
-Javadoc of the current Core Implementation
-
-* link:Core.html[General Core Documentation] and link:../javadoc/core/java7/index.html[Core Javadoc for Java7] /
- link:../javadoc/core/java8/index.html[Core Javadoc for Java8]
-
-Javadoc of the current Extension Modules
-
-
-=== Examples
-
-A comprehensive set of examples can be found link:../examples.html[here].
-
-
[2/4] incubator-tamaya git commit: Moved all documents from docs/ to
docs/src/main/asciidoc
Posted by pl...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/Core.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/Core.adoc b/docs/src/main/asciidoc/Core.adoc
new file mode 100644
index 0000000..3bb82e4
--- /dev/null
+++ b/docs/src/main/asciidoc/Core.adoc
@@ -0,0 +1,269 @@
+Apache Tamaya -- Core
+=====================
+:name: Tamaya
+:rootpackage: org.apache.tamaya.core
+:title: Apache Tamaya Core
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[Core]]
+== Tamaya Core
+=== 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.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
+|java.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
+|java.lang.Character |CharConverter |0xFF, 'a', 'H', 123
+|java.lang.Class |ClassConverter |<fully qualified class name>
+|java.util.Currency |CurrencyConverter |CHF, 123
+|java.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|_Enums_ |EnumConverter |<Enum item name>
+|java.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|java.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.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
+|java.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, but already powerful configuration setting, that allows you to configure SE
+applications already easily. Basically you can provide configuration properties using the following formats and
+locations (from weakest to strongest):
+
+. Read environment properties and add them prefixed with +env.+
+. Read all files found in +META-INF/cfg/defaults.properties+
+. Read all files found in +META-INF/cfg/${tamaya.stage}/defaults.properties+
+. Read all files found in +META-INF/cfg/config.properties+
+. Read all files found in +META-INF/cfg/${tamaya.stage}/config.properties+
+. Read current system properties.
+
+Hereby +tamaya.stage+ can be set by setting an according environment property, or by applying (overriding any environment
+property) a corresponding system property:
+
+[source, listing]
+-----------------------------------------
+-Dtamaya.stage=test
+-----------------------------------------
+
+If not set the staging locations will be ignored.
+
+
+=== 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+:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Type_ |_Class Name_ |_Ordinal Used_
+|Environment Properties |EnvironmentPropertySource |300
+|System Properties |SystemPropertySource |400
+|Base Implementation |BasePropertySource |1000
+|Properties Implementation |PropertiesPropertySource |1000
+|Properties Implementation based on a URL |PropertiesFilePropertySource |1000
+|=======
+
+There is also a class +DefaultOrdinal+, which defines several default ordinals. Beside the ordinals for system
+and environment properties above, there may additional default ordinals defined in the future.
+
+
+=== 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+.
+
+
+[[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 different 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:modules.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/HighLevelDesign.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/HighLevelDesign.adoc b/docs/src/main/asciidoc/HighLevelDesign.adoc
new file mode 100644
index 0000000..825bfa7
--- /dev/null
+++ b/docs/src/main/asciidoc/HighLevelDesign.adoc
@@ -0,0 +1,210 @@
+Apache Tamaya -- High Level Design
+==================================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya
+:revnumber: 0.1-SNAPSHOT
+:revremark: Incubator
+:revdate: January 2014
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
+
+toc::[]
+
+<<<
+:numbered!:
+-----------------------------------------------------------
+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.
+-----------------------------------------------------------
+
+:numbered:
+
+[[Core Concepts]]
+== The Tamaya Core Parts
+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
+* 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.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 basically is compatible with Java 7 and Java 8. Java 8 additionally introduces additional methods
+hereby leveraging the newly added Java 8 +Optional+ features and _default_ methods.
+
+== Further Documentation
+
+Being here we recommend to have a look at the more detailed documentation of Tamaya's link:API.html[API] and
+link:SPI.html[SPI], and of its current available link:modules.html[modules].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/Requirements.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/Requirements.adoc b/docs/src/main/asciidoc/Requirements.adoc
new file mode 100644
index 0000000..ca64fcd
--- /dev/null
+++ b/docs/src/main/asciidoc/Requirements.adoc
@@ -0,0 +1,268 @@
+Apache Tamaya -- Requirements
+=============================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya Requirements
+:revnumber: 1.0
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: OBF
+:author: Oliver B. Fischer
+:email: <pl...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+toc::[]
+<<<
+[[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/blob/58811134/docs/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/index.adoc b/docs/src/main/asciidoc/index.adoc
new file mode 100644
index 0000000..5707fc5
--- /dev/null
+++ b/docs/src/main/asciidoc/index.adoc
@@ -0,0 +1,195 @@
+Apache Tamaya -- Documentation
+==============================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya
+:revnumber: 0.1-SNAPSHOT
+:revremark: Incubator
+:revdate: November 2014
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
+
+toc::[]
+
+<<<
+:numbered!:
+-----------------------------------------------------------
+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.
+-----------------------------------------------------------
+
+:numbered:
+
+<<<
+
+== Introduction
+[[WhatIsTamaya]]
+=== What is Apache Tamaya?
+Tamaya is a very powerful yet flexible configuration solution. It's core is built based on a few simple concepts.
+Summarizing Tamaya provides you
+
+* a simple _key/value_ configuration model.
+* a uniform API for accessing _configuration_, regardless if you are running in a Java SE, Java EE or OSGI environment.
+ This API is capable of hiding all the complexities in configuration management, your developers only need to know,
+ where and in which format configuration can be added to the system.
+* A +ConfigurationBuilder+ allowing you to create a configuration completely manually and managing the configuration
+ lifecycle on your own.
+* a minimalistic implementation, which in the future might also be targeting Java ME environments.
+* a powerful SPI that allows you to extend/adapt Tamaya with all kind of additional mechanisms commonly used in
+ many use cases.
+* a bunch of modules that can be added to your classpath thus adding different functionality to your system as needed.
+
+
+=== What is Apache Tamaya NOT?
+
+Nevertheless there are a few things that are not part of Tamaya:
+
+* Tamaya comes as a modular framework, where you have to decide, which features make sense for you. So you have to do
+ a selection, which modules make sense.
+* Though Tamaya comes with a very minimalistic configuration scheme out-of-the-box, it does by default typically not
+ cover your enterprise requirements. Also here Tamaya offers hooks and examples showing how you can easily
+ replace your current configuration logic with Tamaya. So you must know how you want to organize configuration in
+ your enterprise context, such as supported file locations, formats, overriding and filter rules etc.
+
+
+[[WorkingGroup]]
+=== Working Group
+This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This
+specification is the result of the collaborative work of the members of the Tamaya Users Group and the community at
+large.
+
+=== Goals
+Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of
+well defined aspects of a software product without having to recompile/rebuild the code. Summarizing configuration
+can affect basically every part of a system, which renders configuration to a real cross-cutting concern, usable in
+many facets.
+
+=== Targets
+Tamaya targets to support all general configuration aspects in a system, e.g.
+
+* application configuration
+ ** plugins
+ ** modules
+ ** components
+* Container configuration, e.g. of Java EE enabling portability and dynamic provisioning
+* Configuration of CDI (interceptors, decorators and alternatives)
+* Configuration of Bean Validation, JSF, web applications etc.
+* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values,
+ and by providing accessors to evaluate current configuration values. This can be used explicitly or transparently
+ by client code.
+
+Since configuration is implemented and applied in various ways Tamaya will allow you to use
+
+* multiple configuration locations, including remote locations
+* multiple configuration formats, including custom formats
+* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und
+ URIs are supported by default.
+* type conversion
+* configuration filtering and property adapters
+* configuration of collections
+
+The Tamaya project consists of the following parts:
+
+* The link:API.html[API] is a complete SE based configuration API, that provides the minimum of functionality needed.
+ It is modelled in a extensible way and only requires a few kb. The main features supported by the link:API.html[] are:
+ ** Reading configuration as String/String key/value pairs
+ ** Reading configuration as type safe values, including type conversion.
+ ** Converting/mapping configuration using operators and queries.
+ ** An SPI providing abstractions for handling property sources, property filters and component lifecycle management.
+
+* The link:Core.html[Core] implements the link:API.html[API]. Basically with the core part (and the API) you are ready
+to go, but you may want to add additional extensions that provide more features that are very useful.
+* Extensions are additional libraries that you can add to your project setup. Most important features are:
+ ** Dynamic resolution of configured values.
+ ** Pattern based resource location
+ ** Configuration injection and configuration template support
+ ** Support for additional configuration formats
+ ** Collection Support
+ ** Prepared configuration metamodels
+ ** Integration with other frameworks as configuration consumer or producer.
+* Finally the *documentation* module provides comprehensive documentation on all features provided.
+
+
+=== Required Java version
+The full API is based on Java SE 8.0 language features, whereas a compatible implementation of API and Core
+is similarly available for Java SE 7 as well.
+
+
+== Where should I continue
+
+=== Further Documentation
+
+* If you want to have a deeper look at the API/SPI, we recommend the link:API.html[API documentation].
+* If you want to have an overview about the available modules, continue link:modules.html[here].
+* If you want to look to the numerous examples, continue link:examples.html[here].
+* If you are interested in the software design in place, continue link:HighLevelDesign.html[here].
+
+Finally
+* If you are interested in the collected requirements, continue link:Requirements.html[here].
+* If you are interested in the collected use cases, continue link:usecases.html[here].
+
+=== API Documentation
+
+Javadoc of the current API
+
+* link:API.html[General API Documentation] and link:../javadoc/api/java7/index.html[API Javadoc for Java7] /
+ link:../javadoc/api/java8/index.html[API Javadoc for Java8]
+
+Javadoc of the current Core Implementation
+
+* link:Core.html[General Core Documentation] and link:../javadoc/core/java7/index.html[Core Javadoc for Java7] /
+ link:../javadoc/core/java8/index.html[Core Javadoc for Java8]
+
+Javadoc of the current Extension Modules
+
+
+=== Examples
+
+A comprehensive set of examples can be found link:../examples.html[here].
+
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/misc/PossibleContributions.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/misc/PossibleContributions.adoc b/docs/src/main/asciidoc/misc/PossibleContributions.adoc
new file mode 100644
index 0000000..a0040d6
--- /dev/null
+++ b/docs/src/main/asciidoc/misc/PossibleContributions.adoc
@@ -0,0 +1,388 @@
+Apache Tamaya - Possible Tasks
+==============================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya
+:revnumber: 0.1-SNAPSHOT
+:revremark: Draft
+:revdate: October 2014
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <at...@gmail.com>
+:source-highlighter: coderay
+:website: http://tamaya.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+
+'''
+
+<<<
+
+-> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[]
+
+toc::[]
+
+<<<
+:numbered!:
+-----------------------------------------------------------
+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.
+-----------------------------------------------------------
+
+:numbered:
+
+<<<
+
+== Introduction
+
+== What is Tamaya
+
+{name} is the Apache standard for flexible and powerful configuration. Objective is to provide flavors for
+Java SE, ME as well as to ship with powerful features for Java EE and Cloud Solutions. All functions provided
+is build on top of a small but very powerful, flexible and extendible API. This API is implemented by a core implementation,
+which then can be extended or adapted for use in different runtime scenarios, such as SE, ME, EE, Spring, OSGI
+and more. Similarly additional modules may be provided that help also existing solution to be plugged into
+{name}, so you can start right away using {name} without having to rebuild/change your existing application.
+
+== Main Features of {name}
+
+The main features of {name} currently are
+
+* *A simple key/value store*, named +PropertyProvider+ (simply called "provider").
+* Simple *built-in meta-data model*, that allows to easily attach metadata to a provider or single property keys.
+* Support for *different configuration formats*.
+* Support for *different configuration locations*, including remote locations.
+* Powerful and flexible *options to combine providers to new composite providers* using different combination policies.
+* The *Configuration model* adds additional features:
+** *Type Adapters* allow to convert configuration into any required target type.
+** *Built-in support* for all basic Java types.
+* *Contextual, hierarchical and multi-layered environment model*. The model is rather simple, but nevertheless
+ powerful enough to map complex layered runtime environments such as Java EE or multi-tenant SaaS solutions.
+* *Configurable System Properties* allow to tweak system properties to behave contextually.
+* *Templates* provide a type safe configuration mechanism where an annotated interface is implemented by the
+ configuration system, providing data from an underlying configuration.
+* *Configuration Injection* allows configured values to be directly injected into the bean's configured.
+* *Loading Policies* allow to control how configuration changes are reflected on the configured beans.
+* *Configuration Operators and Queries* can be used to easily implement advanced features such as *Views,
+ Security Constraints and Filters*.
+* Provider and configuration changes can be observed by registering *PropertyChangeListeners*.
+* Configurations are *versioned*, so remote pull scenarios can be implemented very efficiently.
+* The system supports *multiple configurations* identified by name.
+* The configuration system provides a powerful management console for reading and updating of configuration.
+* The system also supports distributed configuration scenarios by leveraging existing solutions, such as Memcached,
+ Hazelcast or Zookeper.
+* The system is built on "Java 8 features*.
+* A *Java 7 Backport* is provided.
+
+=== Purpose of this Document
+
+The document should help to organize people and ideas around the Apache Tamaya Library. It list possible features,
+ideas and tasks that need to be done. Everybody can have a look at and see, where hos contribution and capabilities
+would fit best.
+
+== Basics
+
+=== Styles, Logo
+
+The project requires
+
+* a good Apache styled logo and
+* CSS styles as needed,
+* an initial web page,
+* a twitter account
+* ...
+
+=== Infrastructure
+
+We should setup all needed infrastructure
+* code repos
+* project modules (including module sites)
+* coding and documentation guidelines
+* automatic builds (CI), included automatic coverage and sonar quality checks.
+* a docker image or appliance, with everything setup, so contributors can easily
+ start contributing...
+* ...
+
+== Main Features
+
+=== Metadata Model
+
+Currently +MetaInfo+ models metadata as a separate constuct. It has been shown that this leads to more complex
+handling when creating composites and makes the API overall more complex. The idea is to model metadata as simple
+key/value pairs, that are part of the provider/configuration data as well, but handled separately. Metadata hereby
+is identified by a starting '_' character in its key. For example refer to the following configuration properties:
+
+[source,listing]
+.Basic Properties
+----------------------------------------------------------------
+a.b.Foo=foo
+a.b.Bar=bar
+a.AnyOther=whatelse
+Something=none
+----------------------------------------------------------------
+
+Now we can model meta-data as follows:
+
+[source,listing]
+.Metadata Properties
+----------------------------------------------------------------
+[a.b].info=An area info
+[a.b.Foo].auth=role1,role2
+[a.b.Foo].encrypt=PGP
+[a.b.Foo].sensitive=true
+[].info=This is a test configuration example.
+----------------------------------------------------------------
+
+The above would model the following:
+
+* The area +a.b+ has the meta property +info+.
+* The entry +a.b.Foo+ has three meta properties +auth,encrypt+ and +sensitive+. These could be interpreted by a security
+ view and used to encrypt the values returned by the configuration instance, if not the current user has one of the
+ specified roles.
+* The last meta data defines an attribute +info+ for the whole provider/configuration (the root area).
+
+Given that the overall entries would be as follows:
+
+[source,listing]
+.Full Properties with Meta Properties
+----------------------------------------------------------------
+[a.b].info=An area info
+a.b.Foo=foo
+[a.b.Foo].auth=role1,role2
+[a.b.Foo].encrypt=PGP
+[a.b.Foo].sensitive=true
+a.b.Bar=bar
+[].info=This is a test configuration example.
+a.AnyOther=whatelse
+Something=none
+----------------------------------------------------------------
+
+The current +MetaInfo+ class could be adapted, so it is reading data from the underlying configuration/provider,
+instead of its own datastructure. This would make a later mapping of configuration and its metadata into DB table, JSON
+etc, much more easier.
+The providers on the other side may suppress any metadata from ordinary output, such
+as +toString()+, Similarly accessing metadata using the official config API (+get, getOrDefault, getAreas+ etc)
+should be disabled. The +MetaInfoBuilder+ must probably as well adapted or redesigned.
+
+=== Collection Support
+
+Add a key/value based model for mapping collections such as sets, maps, list. Implement according adapters.
+In combination with the metadata model above this could be something like:
+
+[source,listing]
+.Collection Support
+----------------------------------------------------------------
+mySet=[a,b,c,d,e\,e,f]
+[mySet].type=set
+#optional define the implementation class
+[mySet].class=java.util.TreeSet
+
+myList=[a,b,c,d,e\,e,f]
+[myList].type=list
+#optional define the implementation class
+[myList].class=java.util.ArrayList
+
+myMap=[a:aa,b:bb,c:cc,d:dd,e:e\,e,f:ff]
+[myMap].type=map
+#optional define the implementation class
+[myMap].class=java.util.TreeMap
+
+#Finally we could also add support for non String based types
+myTypedSet=[1,2,3,4.5,6,7.10.123]
+[myTypedSet].contentClass=java.lang.Double
+myTypedList=[CHF 10.20, EUR 12.20, BTC 0.002]
+[myTypedList].contentType=org.javamoney.moneta.FastMoney
+myTypedMap=[CHF:CHF 10.20, EUR:EUR 12.20, BTC:BTC 0.002]
+[myTypedMap].contentTypes=javax.money.CurrencyUnit,javax.money.MonetaryAmount
+----------------------------------------------------------------
+
+
+=== Management Service
+
+A JMX/Restful API should be designed and built that exposes configuration information. Access should be secured, e.g.
+using OAuth or other security mechasnisms.
+
+=== Management Client
+
+A nice web-based client to manage configuration data would be nice as well. This also includes a UI for creating new
+configurations.
+
+=== Mapping Configuration to a Database
+
+A flexible mechanism should be implemented that allows the use of databases (SQL/JPA as well as non-SQL) for
+storing/retreiving/managing configuration:
+
+* JPA, Hibernate
+* MongoDB
+* ...
+
+=== Integration with OSGI
+
+Examples are to be created and tested, where OSGI is used as the basic runtime platform, e.g. Apache Felix, but as well
+others.
+
+=== Integration with Jigsaw
+
+Once Jigsaw is mature and in a usable (still early) stage, examples are to be created and tested, where OSGI is used as
+the basic runtime platform, e.g. Apache Felix, but as well others.
+
+== Distributed/Remote Configuration Support
+
+=== Configuration Server
+
+A configuration server should be implemented that provides access to configurations and triggers updates to registered
+clients (push). Similarly a poull model should be supported, where clients can asl for the current version id of a certain
+configuration and reload it if necessary.
+
+=== Configuration Distribution Policies
+
+Different configuration distribution policies should be defined any implemented, e.g. distributed cache, restful services,
+web services, EJB/RMI calls, asynchronous queues, publish/subsribe models, ...
+
+=== Dynamic Service Lookup
+
+Configuration Servers and Clients should bea ble to locate each other in different ways:
+
+* with fixed configured IPs, or IP ranges
+* using a dynamic service location protocol like
+** SLP
+** Distributed Maps/Datagrids
+** Apache Zookeeper
+
+=== Configuration Client
+
+A subset of the API would be created that exposes only a well defined subset, of exactly one configuration targeted
+to a certain instance, VM or whatever. The client should be connectable to a server in different ways (see configuration
+distributiont policies).
+
+=== Preferences Support
+
+Write a +PreferencesFactory+ for +java.util.preferences+.
+
+== Third Party Integration
+
+=== Integration with Deltaspike Config
+
+Integration with Deltaspike Config should be implemented and discussed with Deltaspike guys.
+
+=== Integration with Spring
+
+A {name} module should be created that allows Spring to be used either as client or configuration provider.
+
+=== Integration with Jetty
+
+A {name} module should be created that allows a Jetty instance to be deployed and started that is (completely)
+configured based on configuration server.
+
+=== Integration with Tomcat
+
+A {name} module should be created that allows a Tomcat instance to be deployed and started that is (completely)
+configured based on configuration server.
+
+=== Configuration of Java EE
+
+In the Java EE area there would be several options:
+
+=== Configuration of Application Servers (administrative resources)
+
+It should be possible to start a application server instance remotely and configure all administrative resources and the
+deployments based on the configuration service, server to be considered maybe
+
+* Wildfly
+* IBM
+* Weblogic
+* Glassfish
+* Apache Geronimo
+
+==== Configuration of CDI
+
+Implement a CDI extension that controls CDI based on configuration:
+* Add beans
+* Remove (veto) beans
+* Add/remove interceptors
+* Add/remove decorators
+* Activate alternatives
+* ...
+
+==== Configuration of Bean Validation
+
+* Add configurable validators.
+* Configure bean validation based on configuration
+* ...
+
+=== JNDI Support
+
+Write a +JCA+ adapter to provide configuration data through JNDI.
+
+==== Configure JSF
+
+Use the JSF +XML Document+ event to completely configure JSF.
+
+==== Configure Web Services
+
+Provide a WebServiceProviderFactory that may be configured.
+
+==== Configure JPA
+
+Provide an implementation that allows configuration of persistence units. Talk with JPA EG people to see if we can
+get an SPI to hook in a stadardized way.
+
+==== Configure EJBs
+
+Provide an implementation that allows configuration of EJBs and MDBs:
+
+* Register beans
+* Unregister/disable beans
+* Intercept beans
+* Support Configuration Injection (in the worst case using a standard Interceptor, provide supporting artifacts to
+ help developers to achive this easily).
+* Talk with EE8 Umbrella EG (Bill Shanon, Linda DeMichels) on a feasible SPI for EE8, if possible join the EG.
+
+==== Configure ...
+
+Just think of any Java EE aspects that might be worth to be configured. If it can be done, e.g. by managing CDI managed
+resources, it might be easy. For others it is a good idea to discuss things with our matter of experts...
+
+== Special Goodies
+
+=== Maintenance Mode Servlet Filter
+
+Provide a servlet filter that is capable of switching to maintenance mode, based on configuration. Similarly also a forwarding
+servlet could be useful, wehere only request based on configuration are forwarded, other might be rejected or dropped
+as configured.
+
+=== Dynamic Camel Routes
+
+Provides dynamic (configurable) Camel routes, e.g. usable within ServiceMix or standalone.
+
+=== Dynamic CXF
+
+Provides dynamic (configurable) CXF adapters, e.g. usable within ServiceMix or standalone.
+
+=== Configurable Apache MQ
+
+Provides an implementation for configuring Apache MQ.
+
+=== Dynamic ...
+
+Interested to see what other ideas are around. Let us know!
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/misc/examples.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/misc/examples.adoc b/docs/src/main/asciidoc/misc/examples.adoc
new file mode 100644
index 0000000..55ed049
--- /dev/null
+++ b/docs/src/main/asciidoc/misc/examples.adoc
@@ -0,0 +1,76 @@
+= Tamayas Asciidoctor Example Document
+Oliver B. Fischer
+
+:encoding: UTF-8
+:source-highlighter: coderay
+
+This document is used to see if the current setup
+of Asciidoctor within the Tamaya project is working
+correctly. Therefore it contains some sections
+with different examples of Asciidoctors capabilities.
+
+== Asciidoctor Environment
+
+Some facts on the current Asciidoctor environment.
+
+Asciidoctor version:: {asciidoctor-version}
+
+
+== Plant UML
+
+This chapter contains a
+http://plantuml.sourceforge.net/[Plant UML] diagram.
+
+
+[plantuml, diagram-classes, png]
+....
+class BlockProcessor
+class DiagramBlock
+class DitaaBlock
+class PlantUmlBlock
+
+BlockProcessor <|-- DiagramBlock
+DiagramBlock <|-- DitaaBlock
+DiagramBlock <|-- PlantUmlBlock
+....
+
+
+== Ditaa
+
+This section contains a diagram from
+http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram website]
+generated with http://ditaa.sourceforge.net/[ditaa].
+
+[ditaa, "asciidoctor-diagram-process"]
+....
+ +-------------+
+ | Asciidoctor |-------+
+ | diagram | |
+ +-------------+ | PNG out
+ ^ |
+ | ditaa in |
+ | v
+ +--------+ +--------+----+ /---------------\
+ | |---+ Asciidoctor +--->| |
+ | Text | +-------------+ | Beautiful |
+ |Document| | !magic! | | Output |
+ | {d}| | | | |
+ +---+----+ +-------------+ \---------------/
+ : ^
+ | Lots of work |
+ +-----------------------------------+
+....
+
+
+
+== GraphViz
+
+This section contains a diagram
+[graphviz]
+....
+graph {
+ a -- b; b -- c; c -- d; d -- e; e -- f; a -- f; a -- c[color=red];
+ a -- d; a -- e; b -- d; b -- e; b -- f; c -- e; c -- f;
+ d -- f;
+}
+....
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_builder.adoc b/docs/src/main/asciidoc/mod_builder.adoc
new file mode 100644
index 0000000..59f1a89
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_builder.adoc
@@ -0,0 +1,50 @@
+= Apache Tamaya -- Extension: Builder
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.builder
+:title: Apache Tamaya Extension: Builder
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Oliver B. Fischer
+:email: <pl...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[Core]]
+== Tamaya Builder (Extension Module)
+=== Overview
+
+TBW
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/mod_events.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_events.adoc b/docs/src/main/asciidoc/mod_events.adoc
new file mode 100644
index 0000000..68ad90a
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_events.adoc
@@ -0,0 +1,57 @@
+= Apache Tamaya -- Extension: Events
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.events
+:title: Apache Tamaya Extension: Events
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[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.
+
+
+
+tbc...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_formats.adoc b/docs/src/main/asciidoc/mod_formats.adoc
new file mode 100644
index 0000000..0b45e8a
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_formats.adoc
@@ -0,0 +1,61 @@
+= Apache Tamaya -- Extension: Formats
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.formats
+:title: Apache Tamaya Extension: Formats
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[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.
+
+
+tbc...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_injection.adoc b/docs/src/main/asciidoc/mod_injection.adoc
new file mode 100644
index 0000000..c3d9102
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_injection.adoc
@@ -0,0 +1,214 @@
+= Apache Tamaya -- Extension: Injection
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.injection
+:title: Apache Tamaya Extension: Injection
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[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. As an example refer to the following
+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;
+
+ @ConfiguredProperty(keys={"a.b.c.key1","a.b.legacyKey",area1.key2"})
+ @DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
+ String value1;
+
+ // Using a (default) String -> Integer converter
+ @ConfiguredProperty(keys="a.b.c.key2")
+ private int value2;
+
+ // resolved by default as foo.bar.ConfiguredClass.accessUrl
+ // Using a (default) String -> URL converter
+ @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.
+ @ConfiguredProperty(keys="BD")
+ @WithAdapter(MyBigDecimalRoundingAdapter.class)
+ private BigDecimal bigNumber;
+
+ ...
+}
+--------------------------------------------
+
+The class does not show all (but most) possibilities provided. Configuring an instance of the
+class using Tamaya is very simple. The only thing is to 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);
+--------------------------------------------
+
+==== The Annotations in detail
+
+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 +@ConfiguredProperty+ 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>
+--------------------------------------------
+
+The following bean can be configured as follows:
+
+[source, java]
+--------------------------------------------
+package a.b;
+
+public final class Tenant{
+ private int id;
+ private String name;
+ private String description;
+
+ public int getId(){
+ return id;
+ }
+ public String getName(){
+ return name;
+ }
+ public String getDescription(){
+ return description;
+ }
+}
+
+Tenant tenant = ConfigurationInjector.getInstance().configure(new Tenant());
+--------------------------------------------
+
+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]
+--------------------------------------------
+Supplier<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+, +@WithConfig+, +@WithConfigOperator+, +@WithPropertyAdapter+.
+
+To illustrate the mechanism below the most simple variant of a configured class is given:
+
+[source,java]
+.Most simple configured class
+--------------------------------------------
+pubic class ConfiguredItem{
+ @ConfiguredProperty
+ private String aValue;
+}
+--------------------------------------------
+
+When this class is configured, e.g. by passing it to +Configuration.configure(Object)+,
+the following is happening:
+
+* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.of();+
+* The current property value (String) is evaluated by calling +cfg.get("aValue");+
+* if not successful, an error is thrown (+ConfigException+)
+* On success, since no type conversion is involved, the value is injected.
+* The configured bean is registered as a weak change listener in the config system's underlying
+ configuration, so future config changes can be propagated (controllable by applying the
+ +@WithLoadPolicy+ annotation).
+
+In the next example we explicitly define the property value:
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
+
+ @ConfiguredProperty
+ @ConfiguredProperty("a.b.value")
+ @configuredProperty("a.b.deprecated.value")
+ @DefaultValue("${env:java.version}")
+ private String aValue;
+}
+--------------------------------------------
+
+Within this example we evaluate multiple possible keys. Evaluation is aborted if a key could be successfully
+resolved. Hereby the ordering of the annotations define the ordering of resolution, so in the example above
+resolution equals to +"aValue", "a.b.value", "a.b.deprecated.value"+. If no value could be read
+from the configuration, it uses the value from the +@DefaultValue+ annotation. Interesting here
+is that this value is not static, it is evaluated by calling +Configuration.evaluateValue(Configuration, String)+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_jodatime.adoc b/docs/src/main/asciidoc/mod_jodatime.adoc
new file mode 100644
index 0000000..cbaaf36
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_jodatime.adoc
@@ -0,0 +1,89 @@
+= Apache Tamaya -- Extension: JodaTime
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.jodatime
+:title: Apache Tamaya Extension: JodaTime
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: April 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: OBF
+:author: Oliver B. Fischer
+:email: <pl...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[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/blob/58811134/docs/src/main/asciidoc/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/mod_resolver.adoc b/docs/src/main/asciidoc/mod_resolver.adoc
new file mode 100644
index 0000000..2f36287
--- /dev/null
+++ b/docs/src/main/asciidoc/mod_resolver.adoc
@@ -0,0 +1,116 @@
+= Apache Tamaya -- Extension: Resolver
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.resolver
+:title: Apache Tamaya Extension: Resolver
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:icons:
+:encoding: UTF-8
+:numbered:
+
+// 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.
+
+[[Core]]
+== Tamaya Resolver (Extension Module)
+
+=== Overview
+
+Tamaya Resolver is an extension module. Refer to the 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.
+
+=== 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-resolver</artifactId>
+ <version>{tamayaVersion}</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
+|=======
+|_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 repeasted until no further change of values could be detetced. In case of a endless loop
+the evaluation is broken after a (configurable) number of cycles.
[3/4] incubator-tamaya git commit: Moved all documents from docs/ to
docs/src/main/asciidoc
Posted by pl...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/misc/PossibleContributions.adoc
----------------------------------------------------------------------
diff --git a/docs/misc/PossibleContributions.adoc b/docs/misc/PossibleContributions.adoc
deleted file mode 100644
index a0040d6..0000000
--- a/docs/misc/PossibleContributions.adoc
+++ /dev/null
@@ -1,388 +0,0 @@
-Apache Tamaya - Possible Tasks
-==============================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya
-:revnumber: 0.1-SNAPSHOT
-:revremark: Draft
-:revdate: October 2014
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <at...@gmail.com>
-:source-highlighter: coderay
-:website: http://tamaya.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-
-'''
-
-<<<
-
--> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[]
-
-toc::[]
-
-<<<
-:numbered!:
------------------------------------------------------------
-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.
------------------------------------------------------------
-
-:numbered:
-
-<<<
-
-== Introduction
-
-== What is Tamaya
-
-{name} is the Apache standard for flexible and powerful configuration. Objective is to provide flavors for
-Java SE, ME as well as to ship with powerful features for Java EE and Cloud Solutions. All functions provided
-is build on top of a small but very powerful, flexible and extendible API. This API is implemented by a core implementation,
-which then can be extended or adapted for use in different runtime scenarios, such as SE, ME, EE, Spring, OSGI
-and more. Similarly additional modules may be provided that help also existing solution to be plugged into
-{name}, so you can start right away using {name} without having to rebuild/change your existing application.
-
-== Main Features of {name}
-
-The main features of {name} currently are
-
-* *A simple key/value store*, named +PropertyProvider+ (simply called "provider").
-* Simple *built-in meta-data model*, that allows to easily attach metadata to a provider or single property keys.
-* Support for *different configuration formats*.
-* Support for *different configuration locations*, including remote locations.
-* Powerful and flexible *options to combine providers to new composite providers* using different combination policies.
-* The *Configuration model* adds additional features:
-** *Type Adapters* allow to convert configuration into any required target type.
-** *Built-in support* for all basic Java types.
-* *Contextual, hierarchical and multi-layered environment model*. The model is rather simple, but nevertheless
- powerful enough to map complex layered runtime environments such as Java EE or multi-tenant SaaS solutions.
-* *Configurable System Properties* allow to tweak system properties to behave contextually.
-* *Templates* provide a type safe configuration mechanism where an annotated interface is implemented by the
- configuration system, providing data from an underlying configuration.
-* *Configuration Injection* allows configured values to be directly injected into the bean's configured.
-* *Loading Policies* allow to control how configuration changes are reflected on the configured beans.
-* *Configuration Operators and Queries* can be used to easily implement advanced features such as *Views,
- Security Constraints and Filters*.
-* Provider and configuration changes can be observed by registering *PropertyChangeListeners*.
-* Configurations are *versioned*, so remote pull scenarios can be implemented very efficiently.
-* The system supports *multiple configurations* identified by name.
-* The configuration system provides a powerful management console for reading and updating of configuration.
-* The system also supports distributed configuration scenarios by leveraging existing solutions, such as Memcached,
- Hazelcast or Zookeper.
-* The system is built on "Java 8 features*.
-* A *Java 7 Backport* is provided.
-
-=== Purpose of this Document
-
-The document should help to organize people and ideas around the Apache Tamaya Library. It list possible features,
-ideas and tasks that need to be done. Everybody can have a look at and see, where hos contribution and capabilities
-would fit best.
-
-== Basics
-
-=== Styles, Logo
-
-The project requires
-
-* a good Apache styled logo and
-* CSS styles as needed,
-* an initial web page,
-* a twitter account
-* ...
-
-=== Infrastructure
-
-We should setup all needed infrastructure
-* code repos
-* project modules (including module sites)
-* coding and documentation guidelines
-* automatic builds (CI), included automatic coverage and sonar quality checks.
-* a docker image or appliance, with everything setup, so contributors can easily
- start contributing...
-* ...
-
-== Main Features
-
-=== Metadata Model
-
-Currently +MetaInfo+ models metadata as a separate constuct. It has been shown that this leads to more complex
-handling when creating composites and makes the API overall more complex. The idea is to model metadata as simple
-key/value pairs, that are part of the provider/configuration data as well, but handled separately. Metadata hereby
-is identified by a starting '_' character in its key. For example refer to the following configuration properties:
-
-[source,listing]
-.Basic Properties
-----------------------------------------------------------------
-a.b.Foo=foo
-a.b.Bar=bar
-a.AnyOther=whatelse
-Something=none
-----------------------------------------------------------------
-
-Now we can model meta-data as follows:
-
-[source,listing]
-.Metadata Properties
-----------------------------------------------------------------
-[a.b].info=An area info
-[a.b.Foo].auth=role1,role2
-[a.b.Foo].encrypt=PGP
-[a.b.Foo].sensitive=true
-[].info=This is a test configuration example.
-----------------------------------------------------------------
-
-The above would model the following:
-
-* The area +a.b+ has the meta property +info+.
-* The entry +a.b.Foo+ has three meta properties +auth,encrypt+ and +sensitive+. These could be interpreted by a security
- view and used to encrypt the values returned by the configuration instance, if not the current user has one of the
- specified roles.
-* The last meta data defines an attribute +info+ for the whole provider/configuration (the root area).
-
-Given that the overall entries would be as follows:
-
-[source,listing]
-.Full Properties with Meta Properties
-----------------------------------------------------------------
-[a.b].info=An area info
-a.b.Foo=foo
-[a.b.Foo].auth=role1,role2
-[a.b.Foo].encrypt=PGP
-[a.b.Foo].sensitive=true
-a.b.Bar=bar
-[].info=This is a test configuration example.
-a.AnyOther=whatelse
-Something=none
-----------------------------------------------------------------
-
-The current +MetaInfo+ class could be adapted, so it is reading data from the underlying configuration/provider,
-instead of its own datastructure. This would make a later mapping of configuration and its metadata into DB table, JSON
-etc, much more easier.
-The providers on the other side may suppress any metadata from ordinary output, such
-as +toString()+, Similarly accessing metadata using the official config API (+get, getOrDefault, getAreas+ etc)
-should be disabled. The +MetaInfoBuilder+ must probably as well adapted or redesigned.
-
-=== Collection Support
-
-Add a key/value based model for mapping collections such as sets, maps, list. Implement according adapters.
-In combination with the metadata model above this could be something like:
-
-[source,listing]
-.Collection Support
-----------------------------------------------------------------
-mySet=[a,b,c,d,e\,e,f]
-[mySet].type=set
-#optional define the implementation class
-[mySet].class=java.util.TreeSet
-
-myList=[a,b,c,d,e\,e,f]
-[myList].type=list
-#optional define the implementation class
-[myList].class=java.util.ArrayList
-
-myMap=[a:aa,b:bb,c:cc,d:dd,e:e\,e,f:ff]
-[myMap].type=map
-#optional define the implementation class
-[myMap].class=java.util.TreeMap
-
-#Finally we could also add support for non String based types
-myTypedSet=[1,2,3,4.5,6,7.10.123]
-[myTypedSet].contentClass=java.lang.Double
-myTypedList=[CHF 10.20, EUR 12.20, BTC 0.002]
-[myTypedList].contentType=org.javamoney.moneta.FastMoney
-myTypedMap=[CHF:CHF 10.20, EUR:EUR 12.20, BTC:BTC 0.002]
-[myTypedMap].contentTypes=javax.money.CurrencyUnit,javax.money.MonetaryAmount
-----------------------------------------------------------------
-
-
-=== Management Service
-
-A JMX/Restful API should be designed and built that exposes configuration information. Access should be secured, e.g.
-using OAuth or other security mechasnisms.
-
-=== Management Client
-
-A nice web-based client to manage configuration data would be nice as well. This also includes a UI for creating new
-configurations.
-
-=== Mapping Configuration to a Database
-
-A flexible mechanism should be implemented that allows the use of databases (SQL/JPA as well as non-SQL) for
-storing/retreiving/managing configuration:
-
-* JPA, Hibernate
-* MongoDB
-* ...
-
-=== Integration with OSGI
-
-Examples are to be created and tested, where OSGI is used as the basic runtime platform, e.g. Apache Felix, but as well
-others.
-
-=== Integration with Jigsaw
-
-Once Jigsaw is mature and in a usable (still early) stage, examples are to be created and tested, where OSGI is used as
-the basic runtime platform, e.g. Apache Felix, but as well others.
-
-== Distributed/Remote Configuration Support
-
-=== Configuration Server
-
-A configuration server should be implemented that provides access to configurations and triggers updates to registered
-clients (push). Similarly a poull model should be supported, where clients can asl for the current version id of a certain
-configuration and reload it if necessary.
-
-=== Configuration Distribution Policies
-
-Different configuration distribution policies should be defined any implemented, e.g. distributed cache, restful services,
-web services, EJB/RMI calls, asynchronous queues, publish/subsribe models, ...
-
-=== Dynamic Service Lookup
-
-Configuration Servers and Clients should bea ble to locate each other in different ways:
-
-* with fixed configured IPs, or IP ranges
-* using a dynamic service location protocol like
-** SLP
-** Distributed Maps/Datagrids
-** Apache Zookeeper
-
-=== Configuration Client
-
-A subset of the API would be created that exposes only a well defined subset, of exactly one configuration targeted
-to a certain instance, VM or whatever. The client should be connectable to a server in different ways (see configuration
-distributiont policies).
-
-=== Preferences Support
-
-Write a +PreferencesFactory+ for +java.util.preferences+.
-
-== Third Party Integration
-
-=== Integration with Deltaspike Config
-
-Integration with Deltaspike Config should be implemented and discussed with Deltaspike guys.
-
-=== Integration with Spring
-
-A {name} module should be created that allows Spring to be used either as client or configuration provider.
-
-=== Integration with Jetty
-
-A {name} module should be created that allows a Jetty instance to be deployed and started that is (completely)
-configured based on configuration server.
-
-=== Integration with Tomcat
-
-A {name} module should be created that allows a Tomcat instance to be deployed and started that is (completely)
-configured based on configuration server.
-
-=== Configuration of Java EE
-
-In the Java EE area there would be several options:
-
-=== Configuration of Application Servers (administrative resources)
-
-It should be possible to start a application server instance remotely and configure all administrative resources and the
-deployments based on the configuration service, server to be considered maybe
-
-* Wildfly
-* IBM
-* Weblogic
-* Glassfish
-* Apache Geronimo
-
-==== Configuration of CDI
-
-Implement a CDI extension that controls CDI based on configuration:
-* Add beans
-* Remove (veto) beans
-* Add/remove interceptors
-* Add/remove decorators
-* Activate alternatives
-* ...
-
-==== Configuration of Bean Validation
-
-* Add configurable validators.
-* Configure bean validation based on configuration
-* ...
-
-=== JNDI Support
-
-Write a +JCA+ adapter to provide configuration data through JNDI.
-
-==== Configure JSF
-
-Use the JSF +XML Document+ event to completely configure JSF.
-
-==== Configure Web Services
-
-Provide a WebServiceProviderFactory that may be configured.
-
-==== Configure JPA
-
-Provide an implementation that allows configuration of persistence units. Talk with JPA EG people to see if we can
-get an SPI to hook in a stadardized way.
-
-==== Configure EJBs
-
-Provide an implementation that allows configuration of EJBs and MDBs:
-
-* Register beans
-* Unregister/disable beans
-* Intercept beans
-* Support Configuration Injection (in the worst case using a standard Interceptor, provide supporting artifacts to
- help developers to achive this easily).
-* Talk with EE8 Umbrella EG (Bill Shanon, Linda DeMichels) on a feasible SPI for EE8, if possible join the EG.
-
-==== Configure ...
-
-Just think of any Java EE aspects that might be worth to be configured. If it can be done, e.g. by managing CDI managed
-resources, it might be easy. For others it is a good idea to discuss things with our matter of experts...
-
-== Special Goodies
-
-=== Maintenance Mode Servlet Filter
-
-Provide a servlet filter that is capable of switching to maintenance mode, based on configuration. Similarly also a forwarding
-servlet could be useful, wehere only request based on configuration are forwarded, other might be rejected or dropped
-as configured.
-
-=== Dynamic Camel Routes
-
-Provides dynamic (configurable) Camel routes, e.g. usable within ServiceMix or standalone.
-
-=== Dynamic CXF
-
-Provides dynamic (configurable) CXF adapters, e.g. usable within ServiceMix or standalone.
-
-=== Configurable Apache MQ
-
-Provides an implementation for configuring Apache MQ.
-
-=== Dynamic ...
-
-Interested to see what other ideas are around. Let us know!
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/misc/examples.adoc
----------------------------------------------------------------------
diff --git a/docs/misc/examples.adoc b/docs/misc/examples.adoc
deleted file mode 100644
index 55ed049..0000000
--- a/docs/misc/examples.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-= Tamayas Asciidoctor Example Document
-Oliver B. Fischer
-
-:encoding: UTF-8
-:source-highlighter: coderay
-
-This document is used to see if the current setup
-of Asciidoctor within the Tamaya project is working
-correctly. Therefore it contains some sections
-with different examples of Asciidoctors capabilities.
-
-== Asciidoctor Environment
-
-Some facts on the current Asciidoctor environment.
-
-Asciidoctor version:: {asciidoctor-version}
-
-
-== Plant UML
-
-This chapter contains a
-http://plantuml.sourceforge.net/[Plant UML] diagram.
-
-
-[plantuml, diagram-classes, png]
-....
-class BlockProcessor
-class DiagramBlock
-class DitaaBlock
-class PlantUmlBlock
-
-BlockProcessor <|-- DiagramBlock
-DiagramBlock <|-- DitaaBlock
-DiagramBlock <|-- PlantUmlBlock
-....
-
-
-== Ditaa
-
-This section contains a diagram from
-http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram website]
-generated with http://ditaa.sourceforge.net/[ditaa].
-
-[ditaa, "asciidoctor-diagram-process"]
-....
- +-------------+
- | Asciidoctor |-------+
- | diagram | |
- +-------------+ | PNG out
- ^ |
- | ditaa in |
- | v
- +--------+ +--------+----+ /---------------\
- | |---+ Asciidoctor +--->| |
- | Text | +-------------+ | Beautiful |
- |Document| | !magic! | | Output |
- | {d}| | | | |
- +---+----+ +-------------+ \---------------/
- : ^
- | Lots of work |
- +-----------------------------------+
-....
-
-
-
-== GraphViz
-
-This section contains a diagram
-[graphviz]
-....
-graph {
- a -- b; b -- c; c -- d; d -- e; e -- f; a -- f; a -- c[color=red];
- a -- d; a -- e; b -- d; b -- e; b -- f; c -- e; c -- f;
- d -- f;
-}
-....
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_builder.adoc b/docs/mod_builder.adoc
deleted file mode 100644
index 59f1a89..0000000
--- a/docs/mod_builder.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-= Apache Tamaya -- Extension: Builder
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.builder
-:title: Apache Tamaya Extension: Builder
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Oliver B. Fischer
-:email: <pl...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[Core]]
-== Tamaya Builder (Extension Module)
-=== Overview
-
-TBW
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/mod_events.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_events.adoc b/docs/mod_events.adoc
deleted file mode 100644
index 68ad90a..0000000
--- a/docs/mod_events.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-= Apache Tamaya -- Extension: Events
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.ext.events
-:title: Apache Tamaya Extension: Events
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[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.
-
-
-
-tbc...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_formats.adoc b/docs/mod_formats.adoc
deleted file mode 100644
index 0b45e8a..0000000
--- a/docs/mod_formats.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= Apache Tamaya -- Extension: Formats
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.ext.formats
-:title: Apache Tamaya Extension: Formats
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[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.
-
-
-tbc...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_injection.adoc b/docs/mod_injection.adoc
deleted file mode 100644
index c3d9102..0000000
--- a/docs/mod_injection.adoc
+++ /dev/null
@@ -1,214 +0,0 @@
-= Apache Tamaya -- Extension: Injection
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.ext.injection
-:title: Apache Tamaya Extension: Injection
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[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. As an example refer to the following
-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;
-
- @ConfiguredProperty(keys={"a.b.c.key1","a.b.legacyKey",area1.key2"})
- @DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
- String value1;
-
- // Using a (default) String -> Integer converter
- @ConfiguredProperty(keys="a.b.c.key2")
- private int value2;
-
- // resolved by default as foo.bar.ConfiguredClass.accessUrl
- // Using a (default) String -> URL converter
- @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.
- @ConfiguredProperty(keys="BD")
- @WithAdapter(MyBigDecimalRoundingAdapter.class)
- private BigDecimal bigNumber;
-
- ...
-}
---------------------------------------------
-
-The class does not show all (but most) possibilities provided. Configuring an instance of the
-class using Tamaya is very simple. The only thing is to 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);
---------------------------------------------
-
-==== The Annotations in detail
-
-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 +@ConfiguredProperty+ 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>
---------------------------------------------
-
-The following bean can be configured as follows:
-
-[source, java]
---------------------------------------------
-package a.b;
-
-public final class Tenant{
- private int id;
- private String name;
- private String description;
-
- public int getId(){
- return id;
- }
- public String getName(){
- return name;
- }
- public String getDescription(){
- return description;
- }
-}
-
-Tenant tenant = ConfigurationInjector.getInstance().configure(new Tenant());
---------------------------------------------
-
-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]
---------------------------------------------
-Supplier<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+, +@WithConfig+, +@WithConfigOperator+, +@WithPropertyAdapter+.
-
-To illustrate the mechanism below the most simple variant of a configured class is given:
-
-[source,java]
-.Most simple configured class
---------------------------------------------
-pubic class ConfiguredItem{
- @ConfiguredProperty
- private String aValue;
-}
---------------------------------------------
-
-When this class is configured, e.g. by passing it to +Configuration.configure(Object)+,
-the following is happening:
-
-* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.of();+
-* The current property value (String) is evaluated by calling +cfg.get("aValue");+
-* if not successful, an error is thrown (+ConfigException+)
-* On success, since no type conversion is involved, the value is injected.
-* The configured bean is registered as a weak change listener in the config system's underlying
- configuration, so future config changes can be propagated (controllable by applying the
- +@WithLoadPolicy+ annotation).
-
-In the next example we explicitly define the property value:
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
-
- @ConfiguredProperty
- @ConfiguredProperty("a.b.value")
- @configuredProperty("a.b.deprecated.value")
- @DefaultValue("${env:java.version}")
- private String aValue;
-}
---------------------------------------------
-
-Within this example we evaluate multiple possible keys. Evaluation is aborted if a key could be successfully
-resolved. Hereby the ordering of the annotations define the ordering of resolution, so in the example above
-resolution equals to +"aValue", "a.b.value", "a.b.deprecated.value"+. If no value could be read
-from the configuration, it uses the value from the +@DefaultValue+ annotation. Interesting here
-is that this value is not static, it is evaluated by calling +Configuration.evaluateValue(Configuration, String)+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_jodatime.adoc b/docs/mod_jodatime.adoc
deleted file mode 100644
index cbaaf36..0000000
--- a/docs/mod_jodatime.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-= Apache Tamaya -- Extension: JodaTime
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.ext.jodatime
-:title: Apache Tamaya Extension: JodaTime
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: April 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: OBF
-:author: Oliver B. Fischer
-:email: <pl...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[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/blob/58811134/docs/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_resolver.adoc b/docs/mod_resolver.adoc
deleted file mode 100644
index 2f36287..0000000
--- a/docs/mod_resolver.adoc
+++ /dev/null
@@ -1,116 +0,0 @@
-= Apache Tamaya -- Extension: Resolver
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.ext.resolver
-:title: Apache Tamaya Extension: Resolver
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:icons:
-:encoding: UTF-8
-:numbered:
-
-// 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.
-
-[[Core]]
-== Tamaya Resolver (Extension Module)
-
-=== Overview
-
-Tamaya Resolver is an extension module. Refer to the 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.
-
-=== 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-resolver</artifactId>
- <version>{tamayaVersion}</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
-|=======
-|_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 repeasted until no further change of values could be detetced. In case of a endless loop
-the evaluation is broken after a (configurable) number of cycles.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_resources.adoc b/docs/mod_resources.adoc
deleted file mode 100644
index 7dc0e38..0000000
--- a/docs/mod_resources.adoc
+++ /dev/null
@@ -1,175 +0,0 @@
-= Apache Tamaya -- Extension: Resources
-
-:name: Tamaya
-:rootpackage: org.apache.tamaya.ext.resources
-:title: Apache Tamaya Extension: Resources
-:revnumber: 0.1.1
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-'''
-
-<<<
-
-toc::[]
-
-<<<
-:numbered!:
-<<<
-[[Core]]
-== Tamaya Resources (Extension Module)
-=== Overview
-
-Tamaya Resources is an extension module. Refer to the 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]
------------------------------------------------
-<dependency>
- <grooupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-resources</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-
-The module's main entry point is the singleton class +org.apache.tamaya.resource.Resources+. This class provides
-access to a +ResourceResolver+ instance:
-
-[source,java]
------------------------------------------------
-public interface ResourceResolver {
- default Collection<URL> getResources(Collection<String> expressions) {...}
- default Collection<URL> getResources(String... expressions) {...}
- default 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.
-
-
-=== 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;
- }
- }
-
-}
--------------------------------------------------------------
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/modules.adoc
----------------------------------------------------------------------
diff --git a/docs/modules.adoc b/docs/modules.adoc
deleted file mode 100644
index 00dd3bc..0000000
--- a/docs/modules.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-Apache Tamaya -- Extension Modules
-==================================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya Extension Modules
-:revnumber: {tamayaVersion}
-:revremark: Incubator
-:revdate: March 2015
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch
-:email: <an...@apache.org>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-// 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.
-toc::[]
-
-== Mature Extensions
-
-N/A
-
-== Draft Extensions
-
-[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:mod_builder.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:mod_resources.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:mod_resolver.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:mod_events.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:mod_formats.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:mod_injection.html[Documentation]
-|=======
-
-
-== Extensions in Experimental Stage
-
-[width="100%",frame="1",options="header",grid="all"]
-|=======
-|_Artifact_ |_Description_ |_Links_
-|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:mod_jodatime.html[Documentation]
-|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/58811134/docs/src/main/asciidoc/API.adoc
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/API.adoc b/docs/src/main/asciidoc/API.adoc
new file mode 100644
index 0000000..d9b1031
--- /dev/null
+++ b/docs/src/main/asciidoc/API.adoc
@@ -0,0 +1,709 @@
+Apache Tamaya -- API
+====================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya
+:revnumber: 0.1-SNAPSHOT
+:revremark: Incubator
+:revdate: January 2014
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// 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.
+'''
+
+<<<
+
+image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[]
+
+toc::[]
+
+<<<
+:numbered!:
+-----------------------------------------------------------
+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.
+-----------------------------------------------------------
+
+:numbered:
+
+[[CoreDesign]]
+== The Tamaya Core 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. As a starting point we recommend you read the corresponding
+link:CoreDesign.html[Core Design Documentation]
+
+[[API]]
+== The Tamaya API
+The API provides the artifacts as described in the link:CoreDesign.html[Core 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+) based on +UnaryOperator<Configuration>+ (operator) and
+ +Function<Configuration,T>+ (query).
+ ** +ConfigurationProvider+ provides the static entry point for accessing configuration.
+ ** +ConfigProvider+ provides static access to the current +Configuration+ (default configuration)
+ ** +ConfigException+ defines a runtime exception for usage by the configuration system.
+ ** +TypeLiteral+ provides a possibility to type safe define the target type to be returned by a registered
+ +PropertyProvider+.
+ ** +PropertyConverter+, which defines conversion of String values into any required target types.
+
+* Additionally the *SPI* provides:
+ ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+
+ hereby
+ *** is designed as a minimalistic data interface to be implemented by any kind of data providers (local or remote)
+ *** provides data key/value pairs in raw format as String key/values only
+ *** can optionally support scanning of its provided values
+ ** _PropertySourceProvider:_ allows to add property sources dynamically.
+ ** +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 parts of the API, which is quite small:
+
+* +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.
+
+
+==== Configuration (Java 7)
+
+The minimal API defined for Java version earlier than Java 8 looks as follows:
+
+[source,java]
+.Interface Configuration in Java 7
+--------------------------------------------
+public interface Configuration{
+ String get(String key);
+ <T> T get(String key, Class<T> type);
+ <T> T get(String key, TypeLiteral<T> type);
+ Map<String,String> getProperties();
+
+ // extension points
+ Configuration with(ConfigOperator operator);
+ <T> T query(ConfigQuery<T> query);
+}
+--------------------------------------------
+
+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.
+
+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+.
+
+==== Configuration (Java 8)
+
+The API for Java 8 adds additional support for +Optional+:
+
+[source,java]
+.Interface Configuration in Java 8
+--------------------------------------------
+public interface Configuration{
+ // methods also defined in Java 7
+ String get(String key);
+ <T> T get(String key, Class<T> type);
+ <T> T get(String key, TypeLiteral<T> type);
+ Map<String,String> getProperties();
+ Configuration with(ConfigOperator operator);
+ <T> T query(ConfigQuery<T> query);
+
+ // new java 8 optional support
+ default Optional<String> getOptional(String key){...}
+ default <T> Optional<T> getOptional(String key, Class<T> type){...}
+ default <T> Optional<T> getOptional(String key, TypeLiteral<T> type){...}
+
+ default Boolean getBoolean(String key){...}
+ default OptionalInt getInteger(String key){...}
+ default OptionalLong getLong(String key){...}
+ default OptionalDouble getDouble(String key){...}
+}
+--------------------------------------------
+
+Hereby
+
+* +get(String)+ and +getOptional(String)+ provide easy access to any kind of configuration properties in their
+ String format.
+* +get(String, TypeLiteral)+, +getOptional(String, TypeLiteral)+, +get(String, Class)+ and
+ +getOptional(String, Class)+ provide type safe access to configuration properties.
+ +PropertyConverter+ instances can be registered for a given
+ target type. The are managed in an ordered list, whereas the ordering is defined by +@Priority+ annotations
+ on the converters.
+* +getProperties()+ gives access to all known (=scannable) properties.
+* +with, query+ provide the extension points for adding additional functionality modelled by +ConfigOperator,
+ ConfigQuery+.
+
+Instances of +Configuration+ can be accessed, exactly like in Java 7, from the +ConfigurationProvider+ singleton:
+
+[source,java]
+.Accessing Configuration
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+--------------------------------------------
+
+Hereby the +ConfigurationProvider+ 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);
+ //X TODO Collection<String> getSupportedFormats();
+}
+--------------------------------------------
+
++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 = Configuration.current().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.getOptional("foo").isPresent()?;
+ 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]
+--------------------------------------------
+// @FunctionalInterface in Java 8
+public interface PropertyConverter{
+ String filterProperty(String key, String valueToBeFiltered);
+}
+--------------------------------------------
+
+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.
+
+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.
+
+[source,java]
+--------------------------------------------
+@FunctionalInterface
+public interface PropertyValueCombinationPolicy{
+
+ public final PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
+ (current, key, propertySource) -> Optional.ofNullable(propertySource.get(key))
+ .filter(s -> !s.isEmpty())
+ .orElse(current);
+
+ String collect(String currentValue, String key, PropertySource propertySource);
+}
+--------------------------------------------
+
+
+[[ConfigurationContext]]
+==== The Configuration Context
+
+A +Configuration+ is basically based on a so called +ConfigurationContext+, which is
+managed by the +ConfigurationProvider+. Similarly the current +ConfigurationContext+ can be accessed from the
++ConfigurationProvider+ singleton:
+
+[source,java]
+.Accessing the current +ConfigurationContext+
+--------------------------------------------
+ConfigurationContext context = ConfigurationProvider.getConfigurationContext();
+--------------------------------------------
+
+The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+:
+
+* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances).
+* +PropertyFilter+ registered that 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 most cases mutability is also not wanted
+or at least not a needed feature. 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.getConfigurationContext().toBuilder();
+ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();
+--------------------------------------------
+
+With such a builder a nre +ConfigurationContext+ can be created and then applied:
+
+[source,java]
+.Creating and applying a new +ConfigurationContext+
+--------------------------------------------
+ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfigurationContext().toBuilder();
+ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource())
+ .addPropertyFilter(new MyFilter()).build();
+ConfigurationProvider.setConfigurationContext(context);
+--------------------------------------------
+
+Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw a +UnsupportedOperationException+. if not
+sure one may access the method +boolean ConfigurationProvider.isConfigurationContextSettable()+ to check if the current
++ConfigurationContext+ is mutable.
+
+
+[[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.getInt("all.size.limit").getAsInt(); // Never returns null
+--------------------------------------------
+
+In Java 8 the following would be possible as well:
+
+[source,java]
+--------------------------------------------
+int myLimit = config.getOptionalInt("all.size.limit").getAsInt(); // OptionalInt
+Class<T> targetClass = config.get("myClass", Class.class); // Optional<Class>, returns never null
+--------------------------------------------
+
+
+### Environment and System Properties
+
+By default environment and system properties are provided automatically as part of the default _Configuration_. The
+environment properties hereby are prefixed with _env._. So we can access the current _PROMPT_ environment variable
+as follows:
+
+[source,java]
+--------------------------------------------
+String prompt = ConfigurationProvider.getConfiguration().get("env.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.getBoolean("use.my.system.answer");
+--------------------------------------------
+
+
+### Adding a Custom Configuration
+
+Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
+Tamaya core module you just have to perform the following steps:
+
+. Define a PropertySource as follows:
+
+[source,java]
+--------------------------------------------
+ public class MyPropertySource extends PropertiesFilePropertySource{
+
+ public MyPropertySource(){
+ super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"));
+ }
+ }
+--------------------------------------------
+
+. Register the new PropertySource using the ServiceLoader by adding the following file:
+
+[source,listing]
+--------------------------------------------
+META-INF/services/org.apache.tamaya.spi.PropertySource
+--------------------------------------------
+
+And adding there the entry for the new PropertySource:
+
+[source,listing]
+--------------------------------------------
+comp.mapackage.MyPropertySource
+--------------------------------------------
+
+
+[[APIImpl]]
+== API Implementation
+
+The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for
+further details.