You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2015/03/03 17:38:37 UTC
[3/3] incubator-tamaya git commit: Updated docs.
Updated docs.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/566988f8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/566988f8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/566988f8
Branch: refs/heads/master
Commit: 566988f87b26018508d1366de23611a3c1ac2ed4
Parents: a77b089
Author: anatole <an...@apache.org>
Authored: Tue Mar 3 17:38:20 2015 +0100
Committer: anatole <an...@apache.org>
Committed: Tue Mar 3 17:38:20 2015 +0100
----------------------------------------------------------------------
docs/Extensions.adoc | 841 -------------------
docs/Requirements.adoc | 268 ++++++
docs/examples/examples.adoc | 76 --
docs/injection.adoc | 201 -----
docs/misc/4_ImplementationCore.adoc | 47 --
docs/misc/examples.adocoff | 76 ++
docs/mod_events.adoc | 57 ++
docs/mod_formats.adoc | 61 ++
docs/mod_injection.adoc | 214 +++++
docs/mod_resolver.adoc | 57 ++
docs/modules.adoc | 15 +-
docs/pom.xml | 5 +-
docs/requirements/Requirements.adoc | 249 ------
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/se/combine-configs.adoc | 14 -
.../se/context-dependent-configuration.adoc | 7 -
docs/usecases/se/dynamic-provisioning.adoc | 17 -
docs/usecases/se/external-configuration.adoc | 6 -
docs/usecases/se/formats.adoc | 7 -
docs/usecases/se/injection.adoc | 31 -
docs/usecases/se/java8.adoc | 13 -
docs/usecases/se/locations.adoc | 9 -
docs/usecases/se/management.adoc | 7 -
docs/usecases/se/minimal-propertysource.adoc | 6 -
docs/usecases/se/multiple-configurations.adoc | 14 -
docs/usecases/se/scannable-properties.adoc | 4 -
docs/usecases/se/service-context.adoc | 14 -
docs/usecases/se/simple-access.adoc | 18 -
docs/usecases/se/simple-property-access.adoc | 9 -
docs/usecases/se/templates.adoc | 11 -
docs/usecases/se/type-safe-properties.adoc | 10 -
docs/usecases/se/value-placeholders.adoc | 8 -
docs/usecases/usecases.adoc | 44 -
50 files changed, 953 insertions(+), 1668 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/566988f8/docs/Extensions.adoc
----------------------------------------------------------------------
diff --git a/docs/Extensions.adoc b/docs/Extensions.adoc
deleted file mode 100644
index db949ac..0000000
--- a/docs/Extensions.adoc
+++ /dev/null
@@ -1,841 +0,0 @@
-// 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.
-<<<
-[[CoreConcepts]]
-== {name} Core Concepts
-Though {name} 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 contains the following core concepts/artifacts:
-
-* Literal Key/Value Pairs
-* _PropertyProvider:_ is the the SPI for a source that provides configuration data. A +PropertyProvider+
- hereby defines
- ** a minimalistic SPI to be implemented by the config data source
- ** provides data key/value pairs in raw format as String key/values only
- ** providers should not have any dependencies other than to the datasource
- ** providers may read context dependent data, but basically providers themselves are not contextual.
- Context management should be done by the ConfigurationProvider implementation that also is responsible
- for combining a set of property providers to a Configuration.
- _Configuration_ is the API that users of Tamaya will see, when they access configuration in raw format. Hereby +Configuration+
- ** adds type support for non String types
- ** provides functional extension points (+with,query+)
- ** allows registering/deregistering of change listeners
- ** is the entry point for evaluating the current +Configuration+
- ** each +PropertyProvider+ can be easily converted into a +Configuration+
- ** allows configuration entries to be injected
- ** to access configuration _templates_ (annotated interfaces).
- ** Configuration may support mutability by allowing instances of +ConfigChangeSet+ to be passed.
-* _PropertyProviders_ allows to aggregate different property providers. Hereby property providers are
- seen as sets, which can be combined to new providers using set styled operations (aggregate, intersect, subtract).
- This allows to model and create composite container providers, to build up more complex configuration models
- step by step.
-* _MetaInfo_ is provided by each +Configuration, PropertyProvider+ and describes the configuration/provider and its entries.
-* _Environment_ is the base model for modelling the environment and the accessor for getting the current +Environment+ instance.
-* _Annotations_ a set of annotations allows to configure configuration injection on classes or interface (aka config templates).
-
-The SPI contains the following core concepts/artifacts:
-
-* _Bootstrap_ is the delegate singleton that is used by the framework to resolve components. The effective component
- loading can be accessed by implementing and registering an instance of +ServiceProvider+ using +java.util.ServiceLoader+.
-* All the singleton used explicitly (+PropertyAdapters,PropertyProviders+ are backed up corresponding API interfaces.
- To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded
- by the current +Bootstrap+ setup (by default ServiceLoader based).
-* Also the singleton used implicitly by +Configuration, Environment, Stage+ are backed up corresponding SPI interfaces.
- To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded
- by the current +Bootstrap+ setup (by default ServiceLoader based).
-
-This is also reflected in the main parts of the API, which is quite small:
-
-* +org.apache.tamaya+ contains the main abstractions +Configuration, ConfigOperator, ConfigQuery, PropertyAdapter, Stage,
- Environment, PropertyProvider, MetaInfo+
-* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +Bootstrap+ mechanism.
-+ +org.apache.tamaya.annot+ contains the annotations defined.
-
-In the implementation are there are additional projects:
-
-* +org.apache.tamaya.core+ contains the core implementation of the API. Deploying it together with the API results in a
- flexible framework that can be easily used for configuration of different complexity. But out of the box this framework
- will not do much more than exposing system and environment properties, its power comes when an additional meta-model
- is defined and deployed. Hereby you can write your own, or use on e of the provided ones (see later).
-* the core part is extended by multiple additional modules
- ** CDI integration
- ** Default configuration meta-models and providers for the most common usage scenarios
- *** standalone applications
- *** Java EE
- *** ...
-
-These parts are explained in the following sections. It is recommended that user's of the API read through this part.
-All subsequent parts are building upon this concepts and may be more difficult to understand without having read
-this section.
-
-
-[[APIKeyValues]]
-=== Key/Value Pairs
-
-Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple
-and similarly most commonly used 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]
-.Accessing some properties
---------------------------------------------
-Properties props = new Properties();
-props.readProperties(...);
-String val = props.getProperty("a.b.c");
-val = props.getProperty("a.b.c.1");
-...
---------------------------------------------
-
-This looks familiar to most of you. Nevertheless when looking closer to the above key/value pairs,
-there are more concepts in place: looking at the keys +a.b.c+, +a.b.c.1+, +a.b.c.2+, +a+, +a.b+ we
-see that the key names build up a flattened tree structure. So we can define the following:
-
-Given a key +p1.p2.p3.k=value+:
-
-* +p1.p2.p3.k+ is called the _qualified key_
-* +p1.p2.p3+ is the key's _area_
-* the child areas +p1.p2", "p1+ are called _areas_ as well
-* +k+ is the _(unqualified) key_
-
-Given that you can perform some very useful actions:
-
-* you can filter the keys with an area. E.g. in the example before you can query for all keys within the area +a.b.c+
- and map them to new properties set as follows:
-
-[source,properties]
-.Accessing an area
---------------------------------------------
-1=cVal1
-2=cVal2
---------------------------------------------
-
-Similarly accessing the area +a+ results in the following properties:
-
-[source,properties]
-.Accessing the area +a+
---------------------------------------------
-b=abVal
-b2=abVal
---------------------------------------------
-
-Additionally you can access all values of an area recursively, so accessing +a+ recursively results in
-the following properties:
-
-[source,properties]
-.Accessing area +a+ recursively
---------------------------------------------
-b.c=cVal
-b.c.1=cVal1
-b.c.2=cVal2
-b=abVal
-b2=abVal
---------------------------------------------
-
-Why this is useful? Well there are different use cases:
-
-* you can segregate your configuration properties, e.g. a module can access its module configuration by
- querying all properties under the area +config.modules.myModule+ (or whatever would be appropriate).
-* you can use this mechanism to configure maps (or more generally: collections).
-* you can easily filter parts of configuration
-* ...and more.
-
-==== Why Using Strings Only
-
-Using Strings as base representation of configuration comes with 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.
-* Often you want not to work with Strings, but with according types.
-* Strings are not hierarchical, so mapping hierarchical 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 converters 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.
-* Even more complex mappings can be easily realized, by using String not as a direct representation of configuration,
- but a reference that defines where the more complex configuration artifact is available. This mechanism is similarly
- easy to understand as parsing Strings to numbers, but is powerful enough to provide e.g. all kind of deployment
- descriptors in Java EE.
-* Hierarchical and collection types can be mapped in different ways:
-** The keys of configuration can have additional syntax/semantics. E.g. when adding dor-separating path semantics
-*** trees/maps can also simply be mapped.
-
-[APIPropertyProviders]
-=== Property Providers
-==== Basic Model
-
-We have seen that constrain 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 +vava.util.Map<String,
-String>+ and +java.util.Properties+ basically model these quite well out of the box.
-So it makes sense to build configuration on top of the JDK's +Map+ interface. This creates immediately additional
-benefits:
-
-* we inherit full Lambda and collection support
-* Maps are widely known and well understood
-
-Nevertheless there are some things to be considered:
-
-* Configuration also requires meta-data, such as
-** the origin of a certain configuration entry and how it was derived from other values
-** the sensitivity of some data
-** the provider that have read the data
-** the time, when the data was read
-** the timestamp, when some data may be outdated
-** ...
-
-Basically the same is also the not related to some single configuration key, but also to a whole map.
-The +PropertyProvider+ interface models exact these aspects and looks as illustrated below:
-
-[source,java]
-.Interface PropertyProvider
---------------------------------------------
-public interface PropertyProvider{
-
- Optional<String> get(String key);
- boolean containsKey(String key);
- Map<String, String> toMap();
- MetaInfo getMetaInfo();
-
- default Set<String> keySet();
- default ConfigChangeSet load();
- default boolean isMutable();
- default void apply(ConfigChangeSet change);
-}
---------------------------------------------
-
-Hereby
-
-* +getMetaInfo()+ return the meta information for the property provider, as well as for individual property key/value pairs.
-* +get, containsKey, keySet+ look similar to the methods on +Map+, though +get+ uses the +Optional+ type introduced
- with Java 8. This avoids returning +null+ or throwing exceptions in case no such entry is available and also
- reduced the API's footprint, since default values can be easily implemented by calling +Optional.orElse+.
-* +isMutable()+ allows to easy check, if a property provider is mutable, which is more elegant than catching
- +NonSupportedOperation+ exception thrown on the according methods of +Map+.
-* +load()+ finally allows to (re)load a property map. It depends on the implementing source, if this operation
- has any effect. If the map changes an according +ConfigChange+ must be returned, describing the
- changes applied.
-* +hasSameProperties+ allows to perform a comparison with another provider.
-* +toMap+ allows to extract thing to a +Map+.
-
-This simple model will be used within the spi, where configuration can be injected/provided from external resources.
-But we have seen, that we have to consider additional aspects, such as extendability and type safety. Therefore we
-extend +PropertyMap+ and hereby also apply the 'composite pattern', which results in the following key abstraction.
-
-==== Meta Information
-
-Each instance also provides an instance of +MetaInfo+, which provides meta information for the providers and its properties:
-
-[source,java]
-.Accessing Meta Information
---------------------------------------------
-PropertyProvider prov = ...;
-MetaInfo metaInfo = prov.getMetaInfo();
-Set<String> keys = metaInfo.keySet(); // returns the attribute keys, for which meta-information is accessible.
-String metaData = metaInfo.get("a.b.c.value"); // access meta information
-String itemName = metaInfo.getName(); // access meta information for the provider
---------------------------------------------
-
-As we have seen above there is as well a +MetaInfoBuilder+, which must be used to create instances of
-+MetaInfo+.
-
-==== Mutability
-
-Property providers optionally may be mutable. This can be checked by calling +boolean isMutable()+. If a provider
-is mutable a +ConfigChangeSet+ can be passed. This change set can then be applied by the provider. On creation
-of the +ConfigChangeSetBuilder+ a provider can pass version information, so _optimistic locking_ can be implemented
-easily:
-
-[source,java]
-.Creating and applying a +ConfigChangeSet+ to a provider
---------------------------------------------
-PropertyProvider prov = ...;
-ConfigChangeSet changeSet = ConfigChangeSetBuilder.of(provider) // creating a default version
- .remove("key1ToBeRemoved", +key2ToBeRemoved")
- .put("key2", "key2Value")
- .put("key3", 12345)
- .put("key4", 123.45)
- .build();
-provider.apply(changeSet);
---------------------------------------------
-
-[[API CombineProviders]]
-==== Combining Property Providers
-
-Looking at the structures of configuration system used by large companies we typically encounter some kind of configuration
-hierarchies that are combined in arbitrary ways. Users of the systems are typically not aware of the complexities in this
-area, since they simply know the possible locations, formats and the overriding policies. Framework providers on the other
-side must face the complexities and it would be very useful if Tamaya can support here by providing prebuilt functionality
-that helps implementing these aspects. All this leads to the feature set of combining property providers. Hereby the following
-strategies are useful:
-
-* aggregating providers, hereby later providers added
- ** override any existing entries from earlier providers
- ** combine conflicting entries from earlier providers, e.g. into a comma-separated structure.
- ** may throw a ConfigExcepotion ig entries are conflicting
- ** may only add entries not yet defined by former providers, preventing entries that are already present to be overwritte
- ** any custom aggregation strategy, which may be a mix of above
-* intersecting providers
-* subtracting providers
-* filtering providers
-
-These common functionality is provided by the +PropertyProviders+ singleton. Additionally to the base strategies above a +MetaInfo+
-instance can be passed optionally as well to define the meta information for the newly created provider instances.
-Let's assume we have two property providers with the following data:
-
-[source,properties]
-.Provider 1
---------------------------------------------
-a=a
-b=b
-c=c
-g=g
-h=h
-i=i
---------------------------------------------
-
-[source,properties]
-.Provider 2
---------------------------------------------
-a=A
-b=B
-c=C
-d=D
-e=E
-f=F
---------------------------------------------
-
-Looking in detail you see that the entries +a,b,c+ are present in both providers, whereas +d,e,f+ are only present in provider 1,
-and +g,h,i+ only in provider 2.
-
-[source,java]
-.Example Combining PropertyProviders
---------------------------------------------
-PropertyProvider provider1 = ...
-PropertyProvider provider2 = ...
-
-// aggregate, hereby values from provider 2 override values from provider 1
-PropertyProvider unionOverriding = PropertyProviders.aggregate(AggregationPolicy.OVERRIDE(), provider1, provider2);
-System.out.println("unionOverriding: " + unionOverriding);
-
-// ignore duplicates, values present in provider 1 are not overriden by provider 2
-PropertyProvider unionIgnoringDuplicates = PropertyProviders.aggregate(AggregationPolicy.IGNORE_DUPLICATES(), provider1, provider2);
-System.out.println("unionIgnoringDuplicates: " + unionIgnoringDuplicates);
-
-// this variant combines/maps duplicate values into a new value
-PropertyProvider unionCombined = PropertyProviders.aggregate(AggregationPolicy.COMBINE(), provider1, provider2);
-System.out.println("unionCombined: " + unionCombined);
-
-// This variant throws an exception since there are key/value paris in both providers, but with different values
-try{
- PropertyProviders.aggregate(AggregationPolicy.EXCEPTION(), provider1, provider2);
-}
-catch(ConfigException e){
- // expected!
-}
---------------------------------------------
-
-The example above produces the following outpout:
-
-[source,listing]
-.Example Combining PropertyProviders
---------------------------------------------
-AggregatedPropertyProvider{
- (name = dynamicAggregationTests)
- a = "[a][A]"
- b = "[b][B]"
- c = "[c][C]"
- d = "[D]"
- e = "[E]"
- f = "[F]"
- g = "[g]"
- h = "[h]"
- i = "[i]"
-}
-unionOverriding: AggregatedPropertyProvider{
- (name = <noname>)
- a = "A"
- b = "B"
- c = "C"
- d = "D"
- e = "E"
- f = "F"
- g = "g"
- h = "h"
- i = "i"
-}
-unionIgnoringDuplicates: AggregatedPropertyProvider{
- (name = <noname>)
- a = "a"
- b = "b"
- c = "c"
- d = "D"
- e = "E"
- f = "F"
- g = "g"
- h = "h"
- i = "i"
-}
-unionCombined: AggregatedPropertyProvider{
- (name = <noname>)
- a = "a,A"
- b = "b,B"
- c = "c,C"
- d = "D"
- e = "E"
- f = "F"
- g = "g"
- h = "h"
- i = "i"
-}
---------------------------------------------
-
-No +AggregationPolicy+ is also an interface that can be implemented:
-
-[source,java]
-.AggregationPolicy Interface
---------------------------------------------
-@FunctionalInterface
-public interface AggregationPolicy {
- String aggregate(String key, String value1, String value2);
-}
---------------------------------------------
-
-So we can also define our own aggregation strategy using a Lambda expression:
-
-[source,java]
-.Use a Custom AggregationPolicy
---------------------------------------------
-PropertyProvider provider1 = ...;
-PropertyProvider provider2 = ...;
-PropertyProvider props = PropertyProviders.aggregate(
- (k, v1, v2) -> (v1 != null ? v1 : "") + '[' + v2 + "]",
- MetaInfo.of("dynamicAggregationTests"),
- props1, props2);
-System.out.println(props);
---------------------------------------------
-
-Additionally we also pass here an instance of +MetaInfo+. The output of this code snippet is as follows:
-
-[source,listing]
-.Listing of dynamic aggregation policy
---------------------------------------------
-AggregatedPropertyProvider{
- (name = dynamicAggregationTests)
- a = "[a][A]"
- b = "[b][B]"
- c = "[c][C]"
- d = "[D]"
- e = "[E]"
- f = "[F]"
- g = "[g]"
- h = "[h]"
- i = "[i]"
-}
---------------------------------------------
-
-Summarizing the +PropertyProviders+ singleton allows to combine providers in various forms:
-
-[source,listing]
-.Methods provided on PropertyProviders
---------------------------------------------
-public final class PropertyProviders {
-
- private PropertyProviders() {}
-
- public static PropertyProvider fromArgs(String... args) {
- public static PropertyProvider fromArgs(MetaInfo metaInfo, String... args) {
- public static PropertyProvider fromPaths(AggregationPolicy aggregationPolicy, String... paths) {
- public static PropertyProvider fromPaths(String... paths) {
- public static PropertyProvider fromPaths(List<String> paths) {
- public static PropertyProvider fromPaths(AggregationPolicy aggregationPolicy, List<String> paths) {
- public static PropertyProvider fromPaths(MetaInfo metaInfo, List<String> paths) {
- public static PropertyProvider fromPaths(AggregationPolicy aggregationPolicy, MetaInfo metaInfo, List<String> paths) {
- public static PropertyProvider fromUris(URI... uris) {
- public static PropertyProvider fromUris(AggregationPolicy aggregationPolicy, URI... uris) {
- public static PropertyProvider fromUris(List<URI> uris) {
- public static PropertyProvider fromUris(AggregationPolicy aggregationPolicy, List<URI> uris) {
- public static PropertyProvider fromUris(MetaInfo metaInfo, URI... uris) {
- public static PropertyProvider fromUris(AggregationPolicy aggregationPolicy, MetaInfo metaInfo, URI... uris) {
- public static PropertyProvider fromUris(MetaInfo metaInfo, List<URI> uris) {
- public static PropertyProvider fromUris(AggregationPolicy aggregationPolicy, MetaInfo metaInfo, List<URI> uris) {
- public static PropertyProvider fromMap(Map<String, String> map) {
- public static PropertyProvider fromMap(MetaInfo metaInfo, Map<String, String> map) {
- public static PropertyProvider empty() {
- public static PropertyProvider emptyMutable() {
- public static PropertyProvider empty(MetaInfo metaInfo) {
- public static PropertyProvider emptyMutable(MetaInfo metaInfo) {
- public static PropertyProvider fromEnvironmentProperties() {
- public static PropertyProvider fromSystemProperties() {
- public static PropertyProvider freezed(PropertyProvider provider) {
- public static PropertyProvider aggregate(AggregationPolicy mapping, MetaInfo metaInfo, PropertyProvider... providers){
- public static PropertyProvider aggregate(PropertyProvider... providers) {
- public static PropertyProvider aggregate(List<PropertyProvider> providers) {
- public static PropertyProvider aggregate(AggregationPolicy mapping, PropertyProvider... propertyMaps) {
- public static PropertyProvider aggregate(AggregationPolicy mapping, List<PropertyProvider> providers) {
- public static PropertyProvider mutable(PropertyProvider provider) {
- public static PropertyProvider intersected(AggregationPolicy aggregationPolicy, PropertyProvider... providers) {
- public static PropertyProvider intersected(PropertyProvider... providers) {
- public static PropertyProvider subtracted(PropertyProvider target, PropertyProvider... providers) {
- public static PropertyProvider filtered(Predicate<String> filter, PropertyProvider provider) {
- public static PropertyProvider contextual(Supplier<PropertyProvider> mapSupplier,
- Supplier<String> isolationKeySupplier) {
- public static PropertyProvider delegating(PropertyProvider mainMap, Map<String, String> parentMap) {
- public static PropertyProvider replacing(PropertyProvider mainMap, Map<String, String> replacementMap) {
-}
---------------------------------------------
-
-
-[[API Configuration]]
-=== Configuration
-==== Basic Model
-
-Configuration inherits all basic features from +PropertyProvider+, but additionally adds functionality for
-type safety and extension mechanisms:
-
-[source,java]
-.Interface Configuration
---------------------------------------------
-public interface Configuration extends PropertyProvider{
-
- default OptionalBoolean getBoolean(String key);
- default OptionalInt getInteger(String key);
- default OptionalLong getLong(String key);
- default OptionalDouble getDouble(String key);
- default <T> Optional<T> getAdapted(String key, PropertyAdapter<T> adapter);
- <T> Optional<T> get(String key, Class<T> type);
-
- // accessing areas
- default Set<String> getAreas();
- default Set<String> getTransitiveAreas();
- default Set<String> getAreas(final Predicate<String> predicate);
- default Set<String> getTransitiveAreas(Predicate<String> predicate);
- default boolean containsArea(String key);
-
- // extension points
- default Configuration with(ConfigOperator operator);
- default <T> T query(ConfigQuery<T> query);
-
- // versioning
- default String getVersion(){return "N/A";}
- void addPropertyChangeListener(PropertyChangeListener l);
- void removePropertyChangeListener(PropertyChangeListener l);
-
- // singleton accessors
- public static boolean isDefined(String name);
- public static <T> T current(String name, Class<T> template);
- public static Configuration current(String name);
- public static Configuration current();
- public static <T> T current(Class<T> type){
- public static void configure(Object instance);
- public static String evaluateValue(String expression);
- public static String evaluateValue(Configuration config, String expression);
- public static void addGlobalPropertyChangeListener(PropertyChangeListener listener);
- public static void removeGlobalPropertyChangeListener(PropertyChangeListener listener);
-}
---------------------------------------------
-
-Hereby
-
-* +XXX getXXX(String)+ provide type safe accessors for all basic wrapper types of the JDK.
-* +getAdapted+ allow accessing any type, hereby also passing a +PropertyAdapter+ that converts
- the configured literal value to the type required.
-* +getAreas()+, +getTransitiveAreas()+ allow to examine the hierarchical tree modeled by the configuration tree.
- Optionally also predicates can be passed to select only part of the tree to be returned.
-* +containsArea+ allows to check, if an area is defined.
-* +with, query+ provide the extension points for adding additional functionality.
-
-* the static accessor methods define:
- ** +current(), current(Class), current(String), current(String, Class)+ return the configuration valid for the current runtime environment.
- ** +addPropertyChangeListener, removePropertyChangeListener+ allow to register or unregister
- global config change listener instances.
- ** evaluateValue allows to evaluate a configuration expression based on a given configuration.
- ** +configure+ performs injection of configured values.
-
-[[TypeConversion]]
-==== Type Conversion
-
-Configuration extend +PropertyProvider+ and add additional support for non String types. This is achieved
-with the help of +PropertyAdapter+ instances:
-
-[source,java]
-.PropertyAdapter
---------------------------------------------
-@FunctionalInterface
-public interface PropertyAdapter<T>{
- T adapt(String value);
-}
---------------------------------------------
-
-PropertyAdapter instances can be implemented manually or registered and accessed from the
-+PropertyAdapers+ singleton. Hereby the exact mechanism is determined by the API backing up the singleton.
-By default corresponding +PropertyAdapter+ instances can be registered using the Java +ServiceLoader+
-mechanism, or programmatically ba calling the +register(Class, PropertyAdapter)+ method.
-
-[source,java]
---------------------------------------------
-public final class PropertyAdapters{
- public static <T> PropertyAdapter<T> register(Class<T> targetType, PropertyAdapter<T> adapter);
- public static boolean isTargetTypeSupported(Class<?> targetType);
- public static <T> PropertyAdapter<T> getAdapter(Class<T> targetType);
- public static <T> PropertyAdapter<T> getAdapter(Class<T> targetType, WithPropertyAdapter annotation);
-}
---------------------------------------------
-
-Whereas this mechanism per se looks not very useful it's power shows up when combining it with the annotations
-API provided, e.g. look at the following annotated class:
-
-[source,java]
-.Annotated Example Class
---------------------------------------------
-public class ConfiguredClass{
-
- @ConfiguredProperty
- private String testProperty;
-
- @ConfiguredProperty("a.b.c.key1")
- @DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
- String value1;
-
- @ConfiguredProperty("a.b.c.key2")
- private int value2;
-
- @ConfiguredProperty
- @DefaultValue("http://127.0.0.1:8080/res/api/v1/info.json")
- private URL accessUrl;
-
- @ConfiguredProperty
- @DefaultValue("5")
- private Integer int1;
-
- @ConfiguredProperty("a.b.customType")
- private MyCustomType myCustomType;
-
- @ConfiguredProperty("BD")
- private BigDecimal bigNumber;
-
- ...
-}
---------------------------------------------
-
-The class does not show all the possibilities that are provided, but it shows that arbitrary types can be supported easily.
-This applied similarly to collection types, whereas collections are more advanced and therefore described in a separate section
-later.
-
-Given the class above and the current configuration can provide the values required, configuring an instance of the
-class is simple:
-
-[source,java]
-.Configuring the Example Class
---------------------------------------------
-ConfiguredClass classInstance = new ConfiguredClass();
-Configuration.configure(configuredClass);
---------------------------------------------
-
-Additional types can transparently be supported by implementing and registering corresponding SPI instances. This is explained
-in the SPI documentation of {name}.
-
-==== 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 similar functional extension mechanisms that were used in other areas of the Java eco-system as well:
-
-* +ConfigOperator+ define unary operations on +Configuration+. They can be used for filtering, implementing
- configuration views, security interception etc.
-* +ConfigQuery+ defines a function returning any kind of result based on a configuration instance. Typical
- use cases of queries could be the implementation of configuration SPI instances that are required
- by other libraries or frameworks.
-
-Both interfaces hereby are defined as functional interfaces:
-
-[source,java]
-.ConfigOperator and ConfigQuery
---------------------------------------------
-@FunctionalInterface
-public interface ConfigOperator{
- Configuration operate(Configuration config);
-}
-
-@FunctionalInterface
-public interface ConfigQuery<T>{
- T query(Configuration config);
-}
---------------------------------------------
-
-Both interfaces can be applied on a +Configuration+ instance:
-
-[source,java]
-.Applying Config operators and queries
---------------------------------------------
-Configuration secured = Configuration.of().apply(ConfigSecurity::secure);
-ConfigSecurity securityContext = Configuration.of().query(ConfigSecurity::targetSecurityContext);
---------------------------------------------
-
-NOTE: +ConfigSecurity+ is an arbitrary class.
-
-=== Configuration Injection
-
-The +Configuration+ interface provides static methods that allow to anykind of instances be configured
-ny just passing the instances calling +Configuration.configure(instance);+. The classes passed hereby must
-be annotated with +@ConfiguredProperty+ to define the configured properties. 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)+.
-
-=== Environment
-
-The environment basically is also a kind of property/value provider similar to +System.getProperties()+ and +System
-.getenv()+ in the JDK. Nevertheless it provides additional functionality:
-
-[source,java]
-.Interface Environment
---------------------------------------------
-public interface Environments {
-
- String getEnvironmentType();
- String getEnvironmentId();
- Environment getParentEnvironment();
-
- Optional<String> get(String key);
- boolean containsKey(String key);
- Set<String> keySet();
- Map<String,String> toMap();
-
- public static Environment current(){
- public static Environment getRootEnvironment(){
- public static List<String> getEnvironmentTypeOrder(){
- public static List<String> getEnvironmentHierarchy(){
- public static Optional<Environment> getInstance(String environmentType, String contextId){
- public static Set<String> getEnvironmentContexts(String environmentType){
- public static boolean isEnvironmentActive(String environmentType){
---------------------------------------------
-
-* environments are hierarchical. Hereby all environments inherit from the root environment. The root environment
- hereby must contain
- ** all JDK's system properties, with same keys, values
- ** all JDK's environment properties, prefixed with +env:+.
- ** additional root properties are allowed as well.
-* the root environment is always directly accessible by calling +Environment.getRootEnvironment()+
-* the current environment can be accessed by calling +Environment.of()+.
-* each environment also defines a +Stage+ (implementing +StageSupplier+). Hereby, if not set explicitly the +Stage+ is inherited from the root
- environment. Consequently the root environment must provide a +Stage+, which by default is +Stage.development()+.
-
-Additionally each environment instance is uniquely identified by the environment type (accessible from
-+getEnvironmentType()+ and the environment id (accessible from +getEnvironmentId()+). So it is possible to access
-an +Environment+ by calling +of(String environmentType, String environmentId)+. Implementations may restrict access
-to environments depending on the current runtime environment (runtime context) active. The API does
-not require further aspects.
-
-The call to +getEnvironmentIds(String)+ returns all context ids of the known +Environment+ instances
-of a given type. E.g. assuming there is an environment type +war+ calling +Environment.getEnvironmentIds("war")+
-may return +"/web/app1", "/web/app2"+ (assuming the war context ids equal the web applications root contexts).
-
-All environments are basically ordered. The ordering can be accessed by calling +getEnvironmentTypeOrder()+. Hereby
-not every environment type in a hierarchy must necessarily present. This is reflected by +getEnvironmentHierarchy()+
-which returns the environment type ids in order, but only containing the types of the environments
-currently present and accessible in the hierarchy. As an example an environment type order in an advanced
-use case could be something like +"root","ear","war","saas","user"+, whereas the concrete environment type hierarchy
-may be +"root","war","saas"+, because the application was not included
-in an additional ear archive and no user is currently active (anonymous). The call to +isEnvironmentActive(String)+
-allows to determine if an environment of the given type is currently active.
-Finally the environment hierarchy is of course similarly reflected by the relationship (+getParentEnvironment()+).
-The following code should illustrate some of these concepts:
-
-[source,java]
-.Interface Environment
---------------------------------------------
-List<String> envHierarchy = Environment.getEnvironmentHierarchy();
- // -> "root","war","saas"
-Environment env = Environment.of();
-System.out.println(env.getEnvironmentContext()); // saas
-System.out.println(env.getEnvironmentId()); // mysolution_pro
-env = env.getParentEnvironment();
-System.out.println(env.getEnvironmentContext()); // war
-System.out.println(env.getEnvironmentId()); // pro
-env = env.getParentEnvironment();
-System.out.println(env.getEnvironmentContext()); // root
-System.out.println(env.getEnvironmentId()); // system
-env = env.getParentEnvironment();
-// env is null now!
---------------------------------------------
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/566988f8/docs/Requirements.adoc
----------------------------------------------------------------------
diff --git a/docs/Requirements.adoc b/docs/Requirements.adoc
new file mode 100644
index 0000000..ca64fcd
--- /dev/null
+++ b/docs/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/566988f8/docs/examples/examples.adoc
----------------------------------------------------------------------
diff --git a/docs/examples/examples.adoc b/docs/examples/examples.adoc
deleted file mode 100644
index 55ed049..0000000
--- a/docs/examples/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/566988f8/docs/injection.adoc
----------------------------------------------------------------------
diff --git a/docs/injection.adoc b/docs/injection.adoc
deleted file mode 100644
index 2522fdd..0000000
--- a/docs/injection.adoc
+++ /dev/null
@@ -1,201 +0,0 @@
-Apache Tamaya -- Injection Module
-=================================
-:name: Tamaya
-:rootpackage: org.apache.tamaya.inject
-:title: Apache Tamaya Injection
-: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.
-<<<
-[[Injection]]
-== The Tamaya Injection API
-=== Overview
-
-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/566988f8/docs/misc/4_ImplementationCore.adoc
----------------------------------------------------------------------
diff --git a/docs/misc/4_ImplementationCore.adoc b/docs/misc/4_ImplementationCore.adoc
deleted file mode 100644
index 2233002..0000000
--- a/docs/misc/4_ImplementationCore.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-// 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.
-<<<
-[[CoreConcepts]]
-== {name} Core Implementation Concepts
-Tamaya comes with an implementation module that implements the Tamaya API. The API itself does only provide the API for configuration usage.
-Especially it does not define how the current runtime +Environment+ is mapped to a +Configuration+. This the gaop that should be solved
-by the core library.
-
-The high level packages give you a good overview of the functionality provided:
-
-* +org.apache.tamaya.core+ is the root package of the Tamaya core implementation.
-* +org.apache.tamaya.core.config+ provides
-
-
-
-The SPI contains the following core concepts/artifacts:
-
-* _Bootstrap_ is the delegate singleton that is used by the framework to resolve components. The effective component
- loading can be accessed by implementing and registering an instance of +ServiceProvider+ using +java.util.ServiceLoader+.
-* All the singleton used explicitly (+PropertyAdapters,PropertyProviders+ are backed up corresponding API interfaces.
- To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded
- by the current +Bootstrap+ setup (by default ServiceLoader based).
-* Also the singleton used implicitly by +Configuration, Environment, Stage+ are backed up corresponding SPI interfaces.
- To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded
- by the current +Bootstrap+ setup (by default ServiceLoader based).
-
-This is also reflected in the main parts of the API, which is quite small:
-
-* +org.apache.tamaya+ contains the main abstractions +Configuration, ConfigOperator, ConfigQuery, PropertyAdapter, Stage,
- Environment, PropertyProvider, MetaInfo+
-* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +Bootstrap+ mechanism.
-+ +org.apache.tamaya.annot+ contains the annotations defined.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/566988f8/docs/misc/examples.adocoff
----------------------------------------------------------------------
diff --git a/docs/misc/examples.adocoff b/docs/misc/examples.adocoff
new file mode 100644
index 0000000..55ed049
--- /dev/null
+++ b/docs/misc/examples.adocoff
@@ -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/566988f8/docs/mod_events.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_events.adoc b/docs/mod_events.adoc
new file mode 100644
index 0000000..d294929
--- /dev/null
+++ b/docs/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/566988f8/docs/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_formats.adoc b/docs/mod_formats.adoc
new file mode 100644
index 0000000..8662223
--- /dev/null
+++ b/docs/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/566988f8/docs/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_injection.adoc b/docs/mod_injection.adoc
new file mode 100644
index 0000000..510dc9e
--- /dev/null
+++ b/docs/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/566988f8/docs/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_resolver.adoc b/docs/mod_resolver.adoc
new file mode 100644
index 0000000..2b111b2
--- /dev/null
+++ b/docs/mod_resolver.adoc
@@ -0,0 +1,57 @@
+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:
+: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 Resolver 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/566988f8/docs/modules.adoc
----------------------------------------------------------------------
diff --git a/docs/modules.adoc b/docs/modules.adoc
index 383939d..9d3e1ed 100644
--- a/docs/modules.adoc
+++ b/docs/modules.adoc
@@ -36,6 +36,17 @@ Apache Tamaya -- Extension Modules
toc::[]
-== Module Overview
+== Mature Extensions
-tbd.
\ No newline at end of file
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+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
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/566988f8/docs/pom.xml
----------------------------------------------------------------------
diff --git a/docs/pom.xml b/docs/pom.xml
index 27e98d2..53b5d43 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -29,7 +29,7 @@ under the License.
<artifactId>tamaya-docs</artifactId>
<name>Apache Tamaya - Documentation</name>
- <description>The Documentation projects keeps together the documentation files in asciidic and other formats
+ <description>The Documentation projects keeps together the documentation files in asciidoc and other formats
for the Apache Tamaya project.
</description>
@@ -86,13 +86,12 @@ under the License.
</goals>
<configuration>
<baseDir>${project.basedir}</baseDir>
- <outputDirectory>target/design</outputDirectory>
+ <outputDirectory>target/adocs</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<backend>html</backend>
<embedAssets>true</embedAssets>
<imagesDir>${project.basedir}/images/icons</imagesDir>
<sourceDirectory>.</sourceDirectory>
- <sourceDocumentName>TamayaDocumentation.adoc</sourceDocumentName>
</configuration>
</execution>
</executions>