tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ple...@apache.org
Subject [4/4] incubator-tamaya git commit: Moved all documents from docs/ to docs/src/main/asciidoc
Date Tue, 02 Jun 2015 18:22:49 GMT
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 <plexus@apache.org>
Authored: Tue Jun 2 20:21:11 2015 +0200
Committer: Oliver B. Fischer <plexus@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: <anatole@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: <anatole@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: <anatole@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: <plexus@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: <anatole@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].
-
-


Mime
View raw message