You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by po...@apache.org on 2016/10/31 21:34:46 UTC
[5/5] incubator-tamaya-site git commit: TAMAYA-186: Add existing
pages.
TAMAYA-186: Add existing pages.
* Still work in progress.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/3d91bad5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/3d91bad5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/3d91bad5
Branch: refs/heads/master
Commit: 3d91bad59dfd5766f0df3e053bde43bb8028ad48
Parents: 90f34d2
Author: Phil Ottlinger <po...@apache.org>
Authored: Mon Oct 31 22:34:17 2016 +0100
Committer: Phil Ottlinger <po...@apache.org>
Committed: Mon Oct 31 22:34:17 2016 +0100
----------------------------------------------------------------------
content/api.adoc | 616 +++++++++++++++++++
content/community.adoc | 143 +++++
content/core.adoc | 228 +++++++
content/devguide.adoc | 213 +++++++
content/download.adoc | 109 ++++
content/examples.adoc | 71 +++
content/extensions.adoc | 107 ++++
content/extensions/mod_builder.adoc | 101 +++
content/extensions/mod_camel.adoc | 145 +++++
content/extensions/mod_cdi.adoc | 233 +++++++
content/extensions/mod_classloader_support.adoc | 91 +++
content/extensions/mod_collections.adoc | 248 ++++++++
content/extensions/mod_consul.adoc | 75 +++
content/extensions/mod_environment.adoc | 58 ++
content/extensions/mod_etcd.adoc | 205 ++++++
content/extensions/mod_events.adoc | 372 +++++++++++
content/extensions/mod_filter.adoc | 135 ++++
content/extensions/mod_formats.adoc | 243 ++++++++
content/extensions/mod_functions.adoc | 124 ++++
content/extensions/mod_injection.adoc | 445 ++++++++++++++
content/extensions/mod_jodatime.adoc | 64 ++
content/extensions/mod_json.adoc | 77 +++
content/extensions/mod_management.adoc | 108 ++++
content/extensions/mod_metamodel-staged.adoc | 74 +++
content/extensions/mod_model.adoc | 467 ++++++++++++++
content/extensions/mod_mutable_config.adoc | 258 ++++++++
content/extensions/mod_optional.adoc | 70 +++
content/extensions/mod_osgi.adoc | 132 ++++
content/extensions/mod_remote.adoc | 131 ++++
content/extensions/mod_resolver.adoc | 144 +++++
content/extensions/mod_resources.adoc | 173 ++++++
content/extensions/mod_server.adoc | 382 ++++++++++++
content/extensions/mod_spi-support.adoc | 73 +++
content/extensions/mod_spring.adoc | 150 +++++
content/extensions/mod_yaml.adoc | 127 ++++
content/highleveldesign.adoc | 167 +++++
content/history.adoc | 48 ++
content/quickstart.adoc | 208 +++++++
content/release-guide.adoc | 276 +++++++++
content/source.adoc | 41 ++
content/start.md | 57 ++
content/usecases.adoc | 506 +++++++++++++++
jbake.properties | 2 +-
templates/menu.thyme | 6 +-
templates/post.thyme | 1 -
templates/sitemap.thyme | 2 +-
46 files changed, 7701 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/api.adoc
----------------------------------------------------------------------
diff --git a/content/api.adoc b/content/api.adoc
new file mode 100644
index 0000000..f830585
--- /dev/null
+++ b/content/api.adoc
@@ -0,0 +1,616 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[CoreDesign]]
+== Apache Tamaya: API
+
+Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
+that build the base of all the other mechanisms. As a starting point we recommend you read the corresponding
+llink:HighLevelDesign.html[High Level Design Documentation]
+
+[[API]]
+== The Tamaya API
+The API provides the artifacts as described in the link:HighLevelDesign.html[High Level Design Documentation], which are:
+
+* A simple but complete SE *API* for accessing key/value based _Configuration_:
+ ** +Configuration+ hereby models configuration, the main interface of Tamaya. +Configuration+ provides
+ *** access to literal key/value pairs.
+ *** functional extension points (+with, query+) using a unary +ConfigOperator+ or
+ a function +ConfigurationQuery<T>+.
+ ** +ConfigurationProvider+ provides with +getConfiguration()+ the static entry point for accessing configuration.
+ ** +ConfigException+ defines a runtime exception for usage by the configuration system.
+ ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned by a registered
+ +PropertyProvider+.
+ ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type.
+
+* Additionally the *SPI* provides:
+ ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+ hereby
+ *** is designed as a minimalistic interface that be implemented by any kind of data provider (local or remote)
+ *** provides single access for key/value pairs in raw format as String key/values only (+getPropertyValue+).
+ *** can optionally support scanning of its provided values, implementing +getProperties()+.
+ ** _PropertySourceProvider:_ allows to register multiple property sources dynamically, e.g. all config files found in
+ file system folder..
+ ** +ConfigurationProviderSpi+ defines the SPI that is used as a backing bean for the +ConfigurationProvider+
+ singleton.
+ ** +PropertyFilter+, which allows filtering of property values prior getting returned to the caller.
+ ** +ConfigurationContext+, which provides the container that contains the property sources and filters that form a
+ configuration.
+ ** +PropertyValueCombinationPolicy+ optionally can be registered to change the way how different key/value
+ pairs are combined to build up the final +Configuration+ passed over to the filters registered.
+ ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack.
+ ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded.
+
+This is also reflected in the main packages of the API:
+
+* +org.apache.tamaya+ contains the main API abstractions used by users.
+* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+
+ mechanism.
+
+
+
+[[APIKeyValues]]
+=== Key/Value Pairs
+
+Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple
+and most commonly used approach are simple literal key/value pairs. So the core building block of {name} are key/value pairs.
+You can think of a common +.properties+ file, e.g.
+
+[source,properties]
+.A simple properties file
+--------------------------------------------
+a.b.c=cVal
+a.b.c.1=cVal1
+a.b.c.2=cVal2
+a=aVal
+a.b=abVal
+a.b2=abVal
+--------------------------------------------
+
+Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g.
+
+[source,properties]
+--------------------------------------------
+Properties props = new Properties();
+props.readProperties(...);
+String val = props.getProperty("a.b.c");
+val = props.getProperty("a.b.c.1");
+...
+--------------------------------------------
+
+
+==== Why Using Strings Only
+
+There are good reason to keep of non String-values as core storage representation of configuration. Mostly
+there are several huge advantages:
+
+* Strings are simple to understand
+* Strings are human readable and therefore easy to prove for correctness
+* Strings can easily be used within different language, different VMs, files or network communications.
+* Strings can easily be compared and manipulated
+* Strings can easily be searched, indexed and cached
+* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in
+ production as well in testing.
+* and more...
+
+On the other side there are also disadvantages:
+
+* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as
+numbers, dates etc.
+* In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly
+ throughout your code.
+* Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some
+ extra efforts.
+
+Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above:
+
+* Adding type safe adapters on top of String allow to add any type easily, that can be directly mapped out of Strings.
+ This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.
+* Also multi-valued, complex and collection types can be defined as a corresponding +PropertyAdapter+ knows how to
+ parse and create the target instance required.
+* String s also can be used as references pointing to other locations and formats, where configuration is
+ accessible.
+
+
+[[API Configuration]]
+=== Configuration
+
++Configuration+ is the main API provided by Tamaya. It allows reading of single property values or the whole
+property map, but also supports type safe access:
+
+[source,java]
+.Interface Configuration
+--------------------------------------------
+public interface Configuration{
+ String get(String key);
+ String getOrDefault(String key, String value);
+ <T> T get(String key, Class<T> type);
+ <T> T getOrDefault(String key, Class<T> type, T defaultValue);
+ <T> T get(String key, TypeLiteral<T> type);
+ <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue);
+ Map<String,String> getProperties();
+
+ // extension points
+ Configuration with(ConfigOperator operator);
+ <T> T query(ConfigQuery<T> query);
+
+ ConfigurationContext getContext();
+}
+--------------------------------------------
+
+Hereby
+
+* +<T> T get(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK.
+* +with, query+ provide the extension points for adding additional functionality.
+* +getProperties()+ provides access to all key/values, whereas entries from non scannable property sources may not
+ be included.
+* +getOrDefault+ allows to pass default values as needed, returned if the requested value evaluated to +null+.
+
+The class +TypeLiteral+ is basically similar to the same class provided with CDI:
+
+[source,java]
+--------------------------------------------
+public class TypeLiteral<T> implements Serializable {
+
+ [...]
+
+ protected TypeLiteral(Type type) {
+ this.type = type;
+ }
+
+ protected TypeLiteral() { }
+
+ public static <L> TypeLiteral<L> of(Type type){...}
+ public static <L> TypeLiteral<L> of(Class<L> type){...}
+
+ public final Type getType() {...}
+ public final Class<T> getRawType() {...}
+
+ public static Type getGenericInterfaceTypeParameter(Class<?> clazz, Class<?> interfaceType){...}
+ public static Type getTypeParameter(Class<?> clazz, Class<?> interfaceType){...}
+
+ [...]
+}
+--------------------------------------------
+
+Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton:
+
+[source,java]
+.Accessing Configuration
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+--------------------------------------------
+
+Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+.
+
+
+[[PropertyConverter]]
+==== Property Converters
+
+As illustrated in the previous section, +Configuration+ also to access non String types. Nevertheless internally
+all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the
+configured String values into the required target type. This is achieved with the help of +PropertyConverters+:
+
+[source,java]
+--------------------------------------------
+public interface PropertyConverter<T>{
+ T convert(String value, ConversionContext context);
+ //X TODO Collection<String> getSupportedFormats();
+}
+--------------------------------------------
+
+The +ConversionContext+ contains additional meta-information for the accessed key, inclusing the key'a name and
+additional metadata.
+
++PropertyConverter+ instances can be implemented and registered by default using the +ServiceLoader+. Hereby
+a configuration String value is passed to all registered converters for a type in order of their annotated +@Priority+
+value. The first non-null result of a converter is then returned as the current configuration value.
+
+Access to converters is provided by the current +ConfigurationContext+, which is accessible from
+the +ConfigurationProvider+ singleton.
+
+
+[[ExtensionPoints]]
+=== Extension Points
+
+We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore
+we have added functional extension mechanisms to +Configuration+ that were used in other areas of the Java eco-system
+as well:
+
+* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of
+ +Configuration+. Operators can be used to cover use cases such as filtering, configuration views, security
+ interception and more.
+* +query(ConfigQuery query)+ allows to apply a function returning any kind of result based on a
+ +Configuration+ instance. Queries are used for accessing/deriving any kind of data based on of a +Configuration+
+ instance, e.g. accessing a +Set<String>+ of root keys present.
+
+Both interfaces hereby are functional interfaces. Because of backward compatibility with Java 7 we did not use
++UnaryOperator+ and +Function+ from the +java.util.function+ package. Nevertheless usage is similar, so you can
+use Lambdas and method references in Java 8:
+
+[source,java]
+.Applying a +ConfigurationQuery+ using a method reference
+--------------------------------------------
+ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext);
+--------------------------------------------
+
+NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes.
+
+
+Operator calls basically look similar:
+
+[source,java]
+.Applying a +ConfigurationOperator+ using a lambda expression:
+--------------------------------------------
+Configuration secured = ConfigurationProvider.getConfiguration()
+ .with((config) ->
+ config.get("foo")!=null?;
+ FooFilter.apply(config):
+ config);
+--------------------------------------------
+
+
+[[ConfigException]]
+=== ConfigException
+
+The class +ConfigException+ models the base *runtime* exception used by the configuration system.
+
+
+[[SPI]]
+== SPI
+
+[[PropertySource]]
+=== Interface PropertySource
+
+We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to
+understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a +java.util.Map<String,
+String>+ and +java.util.Properties+ basically model these aspects out of the box.
+
+Though there are advantages in using these types as a model, there are some severe drawbacks, notably implementation
+of these types is far not trivial and the collection API offers additional functionality not useful when aiming
+for modelling simple property sources.
+
+To render an implementation of a custom +PropertySource+ as convenient as possible only the following methods were
+identified to be necessary:
+
+[source,java]
+--------------------------------------------
+public interface PropertySource{
+ int getOrdinal();
+ String getName();
+ String get(String key);
+ boolean isScannable();
+ Map<String, String> getProperties();
+}
+--------------------------------------------
+
+Hereby
+
+* +get+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available.
+* +getProperties+ allows to extract all property data to a +Map<String,String>+. Other methods like +containsKey,
+ keySet+ as well as streaming operations then can be applied on the returned +Map+ instance.
+* But not in all scenarios a property source may be scannable, e.g. when looking up keys is very inefficient, it
+ may not make sense to iterator over all keys to collect the corresponding properties.
+ This can be evaluated by calling +isScannable()+. If a +PropertySource+ is defined as non scannable accesses to
+ +getProperties()+ may not return all key/value pairs that would be available when accessed directly using the
+ +String get(String)+ method.
+* +getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where
+ property sources with higher ordinals override the ones with lower ordinals. If ordinal are the same, the natural
+ ordering of the fulloy qualified class names of the property source implementations are used. The reason for
+ not using +@Priority+ annotations is that property sources can define dynamically their ordinals, e.g. based on
+ a property contained with the configuration itself.
+* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within the current
+ +ConfigurationContext+.
+
+This interface can be implemented by any kind of logic. It could be a simple in memory map, a distributed configuration
+provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple
+property sources with additional combination/aggregation rules in place.
+
++PropertySources+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current
+ active +ServiceContext+.
+
+
+[[PropertySourceProvider]]
+==== Interface PropertySourceProvider
+
+Instances of this type can be used to register multiple instances of +PropertySource+.
+
+[source,java]
+--------------------------------------------
+// @FunctionalInterface in Java 8
+public interface PropertySourceProvider{
+ Collection<PropertySource> getPropertySources();
+}
+--------------------------------------------
+
+This allows to evaluate the property sources to be read/that are available dynamically. All property sources
+are read out and added to the current chain of +PropertySource+ instances within the current +ConfigurationContext+,
+refer also to [[ConfigurationContext]].
+
++PropertySourceProviders+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the
+current active +ServiceContext+.
+
+
+[[PropertyFilter]]
+==== Interface PropertyFilter
+
+Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated before a +Configuration+ instance is
+passed to the user. Filters can hereby used for multiple purposes, such as
+
+* resolving placeholders
+* masking sensitive entries, such as passwords
+* constraining visibility based on the current active user
+* ...
+
++PropertyFilters+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current
+active +ServiceContext+. Similar to property sources they are managed in an ordered filter chain, based on the
+applied +@Priority+ annotations.
+
+A +PropertyFilter+ is defined as follows:
+
+[source,java]
+--------------------------------------------
+// Functional Interface
+public interface PropertyFilter{
+ String filterProperty(String value, FilterContext context);
+}
+--------------------------------------------
+
+Hereby:
+
+* returning +null+ will remove the key from the final result
+* non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies
+ filter evaluation has to be continued as long as filters are still changing some of the values to be returned.
+ To prevent possible endless loops after a defined number of loops evaluation is stopped.
+* +FilterContext+ provides additional metdata, inclusing the key accessed, which is useful in many use cases.
+
+This method is called each time a single entry is accessed, and for each property in a full properties result.
+
+
+[[PropertyValueCombinationPolicy]]
+==== Interface PropertyValueCombinationPolicy
+
+This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to
+build up the final Configuration to be passed over to the +PropertyFilters+. The default implementation is just
+overriding all values read before with the new value read. Nevertheless for collections and other use cases it is
+often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the
+new value. Finally looking at the method's signature it may be surprising to find a +Map+ for the value. The basic
+value hereby is defined by +currentValue.get(key)+. Nevertheless the +Map+ may also contain additional meta entries,
+which may be considered by the policy implementation.
+
+[source,java]
+--------------------------------------------
+// FunctionalInterface
+public interface PropertyValueCombinationPolicy{
+
+ PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
+ new PropertyValueCombinationPolicy(){
+ @Override
+ public Map<String,String> collect(Map<String,String> currentValue, String key,
+ PropertySource propertySource) {
+ PropertyValue value = propertySource.get(key);
+ return value!=null?value.getConfigEntries():currentValue;
+ }
+ };
+
+ String collect(Map<String,String> currentValue currentValue, String key,
+ PropertySource propertySource);
+
+}
+--------------------------------------------
+
+
+[[ConfigurationContext]]
+==== The Configuration Context
+
+A +Configuration+ is basically based on a so called +ConfigurationContext+, which is
+accessible from +Configuration.getContext()+:
+
+[source,java]
+.Accessing the current +ConfigurationContext+
+--------------------------------------------
+ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext();
+--------------------------------------------
+
+The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+:
+
+* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances).
+* +PropertyFilters+ registered, which filter values before they are returned to the client
+* +PropertyConverter+ instances that provide conversion functionality for converting String values to any other types.
+* the current +PropertyValueCombinationPolicy+ that determines how property values from different PropertySources are
+ combined to the final property value returned to the client.
+
+
+[[Mutability]]
+==== Changing the current Configuration Context
+
+By default the +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed
+or even not wanted. Nevertheless there are use cases where the current +ConfigurationContext+ (and
+consequently +Configuration+) must be adapted:
+
+* New configuration files where detected in a folder observed by Tamaya.
+* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must
+ be adapted to these changes.
+* The overall configuration context is manually setup by the application logic.
+* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the
+ tests executed.
+
+In such cases the +ConfigurationContext+ must be mutable, meaning it must be possible:
+
+* to add or remove +PropertySource+ instances
+* to add or remove +PropertyFilter+ instances
+* to add or remove +PropertyConverter+ instances
+* to redefine the current +PropertyValueCombinationPolicy+ instances.
+
+This can be achieved by obtaining an instance of +ConfigurationContextBuilder+. Instances of this builder can be
+accessed either
+
+* from the current +ConfigurationContext+, hereby returning a builder instance preinitialized with the values from the
+ current +ConfigurationContext+
+* from the current +ConfigurationProvider+ singleton.
+
+[source,java]
+.Accessing a +ConfigurationContextBuilder+
+--------------------------------------------
+ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder();
+ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();
+--------------------------------------------
+
+With such a builder a new +ConfigurationContext+ can be created and then applied:
+
+[source,java]
+.Creating and applying a new +ConfigurationContext+
+--------------------------------------------
+ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext()
+ .toBuilder();
+ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource())
+ .addPropertyFilter(new MyFilter()).build();
+ConfigurationProvider.setConfigurationContext(context);
+--------------------------------------------
+
+Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw an +UnsupportedOperationException+.
+This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationContextSettable()+.
+
+
+[[ConfigurationProviderSpi]]
+==== Implementing and Managing Configuration
+
+One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interface, which is backing up the
++ConfigurationProvider+ singleton. Implementing this class allows
+
+* to fully determine the implementation class for +Configuration+
+* to manage the current +ConfigurationContext+ in the scope and granularity required.
+* to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context.
+* Performing changes as set with the current +ConfigurationContextBuilder+.
+
+
+[[ServiceContext]]
+==== The ServiceContext
+
+The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya.
+The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the
++ServiceContextManager+ singleton:
+
+[source,java]
+.Accessing the +ServiceContext+
+--------------------------------------------
+ServiceContext serviceContext = ServiceContextManager.getServiceContext();
+
+public interface ServiceContext{
+ int ordinal();
+ <T> T getService(Class<T> serviceType);
+ <T> List<T> getServices(Class<T> serviceType);
+}
+--------------------------------------------
+
+With the +ServiceContext+ a component can be accessed in two different ways:
+
+. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally
+ the most significant instance is returned only.
+. access all items given its type. This will return (by default) all instances loadedable from the current
+ runtime context, ordered by priority, hereby the most significant components added first.
+
+
+## Examples
+### Accessing Configuration
+
+_Configuration_ is obtained from the ConfigurationProvider singleton:
+
+[source,java]
+.Accessing +Configuration+
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+--------------------------------------------
+
+Many users in a SE context will probably only work with _Configuration_, since it offers all functionality
+needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is
+very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _Optional_ is supported:
+
+[source,java]
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+String myKey = config.get("myKey"); // may return null
+int myLimit = config.get("all.size.limit", int.class);
+--------------------------------------------
+
+
+### Environment and System Properties
+
+By default environment and system properties are included into the _Configuration_. So we can access the current
+_PROMPT_ environment variable as follows:
+
+[source,java]
+--------------------------------------------
+String prompt = ConfigurationProvider.getConfiguration().get("PROMPT");
+--------------------------------------------
+
+Similary the system properties are directly applied to the _Configuration_. So if we pass the following system
+property to our JVM:
+
+[source,java]
+--------------------------------------------
+java ... -Duse.my.system.answer=yes
+--------------------------------------------
+
+we can access it as follows:
+
+[source,java]
+--------------------------------------------
+boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class);
+--------------------------------------------
+
+
+### Adding a Custom Configuration
+
+Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
+_tamaya-spi-support_ module you just have to perform a few steps:
+
+. Define a PropertySource as follows:
+
+[source,java]
+--------------------------------------------
+ public class MyPropertySource extends PropertiesResourcePropertySource{
+
+ public MyPropertySource(){
+ super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL);
+ }
+ }
+--------------------------------------------
+
+Then register +MyPropertySource+ using the +ServiceLoader+ by adding the following file:
+
+[source,listing]
+--------------------------------------------
+META-INF/services/org.apache.tamaya.spi.PropertySource
+--------------------------------------------
+
+...containing the following line:
+
+[source,listing]
+--------------------------------------------
+com.mypackage.MyPropertySource
+--------------------------------------------
+
+
+[[APIImpl]]
+== API Implementation
+
+The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for
+further details.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/community.adoc
----------------------------------------------------------------------
diff --git a/content/community.adoc b/content/community.adoc
new file mode 100644
index 0000000..a3219f7
--- /dev/null
+++ b/content/community.adoc
@@ -0,0 +1,143 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya: Community
+
+:sectnums:
+
+// Document properties
+:twitterhandle: tamayaconf
+
+== Users
+
+If you are a new user and you would like to participate in Tamaya
+(would be great!), you can have a look at the current
+project documentation. Apache Tamaya currently does
+not yet have a users mailing list. If you want discuss your use cases
+we encourage you to mailto:dev-subscribe@tamaya.incubator.apache.org[subscribe]
+to our mailto:dev@tamaya.incubator.apache.org[mailing list for developers].
+Furthermore, you can check our xref:a_mailing_lists[mail-archives].
+
+Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^]
+please ask on the mailing list if it's a known issue in case of a
+bug or if there is an ongoing discussion in case of a feature.
+
+You are very welcome to follow our twitter account
+http://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word
+of Tamaya with tweets, blog entries,...
+
+== Getting Involved
+
+Everybody is welcome to get involved with our community. You can find general
+information at http://apache.org/foundation/getinvolved.html and
+http://apache.org/foundation/how-it-works.html.
+The following sections provides some details about the different levels of getting involved.
+
+If you want to contribute to the
+documentation of Apache Tamaya, please
+read the instructions about the Documentation
+that addresses how to contribute, render and publish it.
+
+
+=== Contributors
+
+Before you get a committer you have to contribute to our effort.
+E.g. you can help users, participate in discussions on the dev list,
+submit patches,... . Therefore, it's essential to file
+a http://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^]
+or http://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^]
+and send it to secretary at apache dot org (or fax it) as early as possible.
+
+If you would like to submit a patch through Jira, you can have a look at the
+link:devguide.html[suggested Git approach].
+
+The lists of current contributors and committers can be found
+on the link:team-list.html[team and contributers page^].
+
+
+=== Committers
+
+Before you read this section, please ensure that you have read
+the contributor section. All of you are welcome to join our development effort.
+mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe] to our
+mailto:dev@tamaya.incubator.apache.org[mailing list for developers] and
+start contributing and help users.
+
+// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12
+Optionally mailto:commits-subscribe@tamaya.incubator.apache.org[subscribe] to our
+mailto:commits@tamaya.incubator.apache.org[mailing list for commits].
+Furthermore, you can check our link:community.html#mailing-lists[mail-archives].
+
+Further details are available at http://www.apache.org/dev/[http://www.apache.org/dev/^].
+
+=== Mailing lists
+
+The table below lists all mailings used by the Tamaya project.
+
+[width="70"]
+[cols="5*.<", options="header"]
+|===
+| List
+| Subscribe
+| Unsubscribe
+| Archive
+| Mirrors
+//-- next row
+| Developer List
+| mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe]
+| mailto:dev-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
+| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^]
+|
+//-- next row
+| Committer List
+| mailto:commits-subscribe@tamaya.incubator.apache.org[Subscribe]
+| mailto:commits-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
+| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^]
+|
+|===
+
+=== JIRA
+
+Any kind of issue has to be filed in our
+https://issues.apache.org/jira/browse/TAMAYA[issue tracker^].
+If you have any question, you can ask us
+(e.g. via the mailing list for developers).
+
+=== Spread the word
+
+You are very welcome e.g. to write blog entries, mention our twitter handle
+ @{twitterhandle} if you tweet about the project or just follow our twitter
+account http://twitter.com/{twitterhandle}[@{twitterhandle}^]
+
+=== IRC
+
+Usually discussions happen on the mailing list. Some informal discussions take
+place in our IRC-Channel irc://irc.freenode.net/apache-tamaya.
+
+----
+// with the irssi command-line client:
+$ irssi
+
+> /connect irc.freenode.net
+> /join #apache-tamaya
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/core.adoc
----------------------------------------------------------------------
diff --git a/content/core.adoc b/content/core.adoc
new file mode 100644
index 0000000..fe891b2
--- /dev/null
+++ b/content/core.adoc
@@ -0,0 +1,228 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[Core]]
+== Tamaya Core Implementation
+=== Overview
+
+Tamaya Core provides an implementation of the link:API.html[Tamaya Configuration API] and adds additional functionality
+and building blocks for supporting SPI implementations.
+
+Tamaya Core contains the following artifacts:
+
+* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+
+* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based
+ on the +@Priority+ annotations.
+* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances
+hereby providing type conversion for all important types.
+* A simple default configuration setup using the current classpath and an optional staging variable.
+* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and
+ registers them in the global +ConfigurationContext+
+* It provides a +ConfigurationContextBuilder+ and allows changing the current +ConfigurationContext+.
+
+The overall size of the library is very small. All required components are implemented and registered, so basically the
+Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible
+enough to be extended/accommodated with additional features as needed, such as
+
+* placeholder and resolution mechanisms
+* dynamic resource path lookup, e.g. with ant styled patterns
+* configuration injection and configuration templates
+* abstraction for reusable formats
+* integration with other existing solutions
+* configuration and configuration isolation targeting Java EE
+* dynamic configuration and configuration updates
+* Configuration management extensions
+* remote configuration
+* and more
+
+For details about the extension modules available and their functionality refer to the link:modules.html[extension user guide].
+
+
+[[CorePropertyConverters]]
+=== Default PropertyConverters in Core
+
+As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the
+listing of converters automatically registered with the Core module:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Target Type_ |_Class Name_ |_Supported Formats_
+|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF
+|java.math.BigInteger |BigIntegerConverter |0xFF, 1234
+|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
+|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
+|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123
+|java.ui.lang.Class |ClassConverter |<fully qualified class name>
+|java.util.Currency |CurrencyConverter |CHF, 123
+|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|_Enums_ |EnumConverter |<Enum item name>
+|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
+|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
+|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
+|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
+|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
+|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
+|ZoneId |ZoneIdConverter |Europe/Zurich
+|=======
+
+
+=== Registering PropertyConverters
+
+Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+,
+meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified
+class names of the converters to be registered (one line per each).
+
+Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically.
+
+NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically.
+
+
+[[ComponentLoadingAndPriorization]]
+=== Component Loading and Priorization
+
+Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components
+must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified
+implementation class names of the components to be registered (one line per each).
+The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya
+core adds this functionality by the possibility to add +@Priority+ annotations to the components registered.
+By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning
+
+* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value
+ effectively _overrides/replaces_ any component with lower values.
+* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the
+ ones with higher priority are before components with lower priority.
+* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is
+ still defined and predictable in almost all scenarios.
+
+
+[[RegisteringPropertySources]]
+=== Registering Property Sources
+
+PropertySources that provide configuration properties are registered as ordinary components as described in the previous
+section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit
++int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful
+due to several reasons:
+
+* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being
+ added easily.
+* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or
+ whatever may be appropriate.
+
+
+[[CorePropertySources]]
+== Configuration Setup in Core
+
+Tamaya Core provides a minimal configuration setting, that allows you to configure SE
+applications already easily. Basically configuration is built up by default as follows:
+
+. Read environment properties and add them prefixed with +env.+
+. Read all files found at +META-INF/javaconfiguration.properties+
+ and +META-INF/javaconfiguration.xml+
+
+
+=== Overview of Registered Default Property Sources and Providers
+
+The Tamaya Core implementation provides a couple of default +PropertySource+ implementations, which are automatically
+registered. They are all in the package +org.apache.tamaya.core.propertysource+ and
++org.apache.tamaya.core.provider+:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Type_ |_Class Name_ |_Ordinal Used_
+|META-INF/javaconfiguration.properties |JavaConfigurationProvider |0
+|META-INF/javaconfiguration.xml |JavaConfigurationProvider |0
+|Environment Properties |EnvironmentPropertySource |300
+|System Properties |SystemPropertySource |400
+|=======
+
+
+=== Abstract Class PropertiesFilePropertySource
+
+The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+
+instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor:
+
+[source,java]
+--------------------------------------------
+PropertiesFilePropertySource(URL url);
+--------------------------------------------
+
+
+==== Abstract Class PropertiesPropertySource
+
+The abstract class +PropertiesPropertySource+ can be used for implementing a +PropertySource+ based on a +Properties+
+instance. It requires a +PropertySource+ to be passed on the constructor:
+
+[source,java]
+--------------------------------------------
+PropertiesPropertySource(Properties properties);
+--------------------------------------------
+
+
+==== Abstract Class BasePropertySource
+
+The abstract class +BasePropertySource+ can be used for implementing custom +PropertySource+ classes. It requires only
+one method to implemented:
+
+[source,java]
+.Implementing a PropertySource using BasePropertySource
+--------------------------------------------
+public class MyPropertySource extends BasePropertySource{
+
+ public String getName(){
+ // return a unique name for the property source, e.g. based on the underlying resource. This name also
+ // allows to access the property source later
+ }
+
+ public Map<String, String> getProperties(){
+ // Get a map with all properties provided by this property source
+ // If the property source is not scannable, the map returned may be empty.
+ // In the ladder case the +boolean isScannale()+ must be overridden, since
+ // by default property sources are assumed to be scannable.
+ }
+
+}
+--------------------------------------------
+
+By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in
++PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override
+the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+.
+
+
+[[CorePropertySourceProviders]]
+=== Default PropertySourceProvider in Core
+
+With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+
+present that loads all .properties files found at +META-INF/javaconfiguration.properties+
+and +META-INF/javaconfiguration.xml+.
+
+
+[[Extensions]]
+== Adding Extensions
+
+The Core module only implements the link:API.html[API]. Many users require/wish additional functionality from a
+configuration system. Fortunately there are numerous extensions available that add further functionality.
+Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath.
+
+For detailed information on the extensions available refer to the link:extensions.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/devguide.adoc
----------------------------------------------------------------------
diff --git a/content/devguide.adoc b/content/devguide.adoc
new file mode 100644
index 0000000..6d28edc
--- /dev/null
+++ b/content/devguide.adoc
@@ -0,0 +1,213 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+
+= Apache Tamaya: Development Guide
+
+== Suggested Git Workflows
+
+=== Avoid git pull!
+
+`git pull` should never get invoked if you have dirty files lying around
+or if your branch is ahead of master. This will always lead to
+some dirty artifacts in the commit history:
+
+----
+Merge branch 'master' of http://git-wip-us.apache.org/tamaya into master
+----
+
+=== Use git pull --rebase
+
+An easy version for getting rid of the auto-merges is using
+
+----
+$ git pull --rebase
+----
+
+Please note that this sometimes trashes your working tree if there
+are unmergeable files around. Cleaning this up with a forced manual
+rebase is not something we would recommend for a git beginner.
+
+=== Working in an own branch
+
+This is actually the suggested way to prevent auto-merges. Create an own
+branch where you do your feature work. Either do all your work in one
+branch or create one branch per feature you are working on.
+
+----
+$ git branch mybranch
+----
+
+After you finished your feature, first add (`git add`) and commit (`git commit`) your work.
+Check with `git status` that you don't have any dirty files and uncommitted
+changes around. You can use `git stash` to 'backup' unfinished work.
+
+Then switch back to the master branch and pull changes
+done by other committers in the meantime.
+
+----
+$ git checkout master
+$ git pull --rebase
+----
+
+You should now get all the changes done by other committers and
+the will get applied to your local master branch. Now go back to
+your private branch and rebase your locally performed work to the HEAD of master.
+
+----
+$ git checkout mybranch
+$ git rebase master
+----
+
+If you got conflicts, you will get lines with ">>>>" added to those
+files. Resolve those conflicts manually, add them and finish the rebase.
+
+Check with `git-status` and `gitk` if the merge went well and the history now contains your changes.
+If all is well, go back to the master branch and merge your changes in.
+
+----
+$ git pull --rebase // (just for safety, you should see no changes)
+$ git checkout master
+$ git merge mybranch
+----
+
+Finally you can push your changes to the ASF git repo
+
+----
+$ git push
+----
+
+[[contributing-workflow]]
+== Contribution workflow
+
+=== Creating patches
+
+You should use the following workflow, if you plan to contribute
+patches or new features to Tamaya.
+
+First update you local copy of the repository:
+
+----
+$ git checkout master
+$ git pull --rebase
+----
+
+Then create a new local branch for your work. It's good practice to name
+it after the corresponding JIRA issue.
+
+----
+$ git checkout -b TAMAYA-XXX
+----
+
+Now you can start to work on your patch. When you are finished, commit your changes. But don't forget to **add the name
+of the JIRA issue to the commit message**.
+
+----
+$ git add -am "TAMAYA-XXX: Fixed some issue"
+----
+
+For small patches we recommend to do a single commit containing your changes. For larger contributions you should try
+to group your work into separate sub-tasks that you can commit one by one.
+
+Before you create your patch you should make sure that your local repository is up to date with the master repository.
+This is very important especially if you work on your branch for a long time. Use the following commands to pull the
+latest changes from the upstream repository and rebase your branch against the current master.
+
+
+----
+$ git checkout master
+$ git pull --rebase
+$ git checkout TAMAYA-XXX
+$ git rebase master
+----
+
+Now you are ready to create your patch:
+
+----
+$ git checkout TAMAYA-XXX
+$ git format-patch --stdout master > ../TAMAYA-XXX.patch
+----
+
+Please attach the resulting patch file to the correspoding JIRA issue.
+
+=== Applying patches
+
+If you are a committer and want to apply a patch you should do so in a separate branch.
+
+----
+$ git checkout -b TAMAYA-XXX
+----
+
+Then apply the patch using `git am` and rebase it against the master branch.
+
+----
+$ git am < ../TAMAYA-XXX.patch
+$ git rebase master
+----
+
+After reviewing the changes and testing the code, the changes are ready to
+be merged into the master branch:
+
+----
+$ git checkout master
+$ git merge TAMAYA-XXX
+$ git branch -d TAMAYA-XXX
+----
+
+=== Discussion workflow (optional)
+
+All discussions which lead to a decision take place on the mailing list.
+Sometimes it's required to show-case an idea esp. if the solution is
+more than few lines. As shown above it makes sense to use local branches
+for developing new parts. Git allows to push such local branches to a
+public repository. So it's easier to share it with the community
+for discussing it. The following listings show an example in combination
+with GitHub - for sure it works with any hosting platform like BitBucket,
+Google-Code,... The only important part here is that such branches
+*NEVER* get pushed to the main Apache repository to keep the commit history
+as clean as possible.
+
+=== Initial setup
+
+----
+$ git clone https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git
+$ git remote add discuss https://[username]@github.com/[username]/[repo-name].git
+$ git push -u discuss master
+----
+
+=== Branches for discussions
+
+----
+$ git checkout -b TAMAYA-XXX # 1-n commits
+$ git push discuss TAMAYA-XXX # share the link to the branch for the discussions
+----
+
+*If the community agrees on the suggested change, the implementation will be applied to the origin master. A committer
+has to follow the steps described above for the basic workflow to keep the commit history simple, clean and straight.
+A contributor has to follow the steps described above for creating a patch.*
+
+=== Delete the branch again
+
+----
+$ git push discuss :TAMAYA-XXX
+$ git branch -d TAMAYA-XXX
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/download.adoc
----------------------------------------------------------------------
diff --git a/content/download.adoc b/content/download.adoc
new file mode 100644
index 0000000..37e8c98
--- /dev/null
+++ b/content/download.adoc
@@ -0,0 +1,109 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// .
+// http://www.apache.org/licenses/LICENSE-2.0
+// .
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//:source-highlighter: coderay
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+:linkattrs: true
+
+= Apache Tamaya: Download
+
+The latest release is Apache Tamaya {tamaya_version_released}.
+You can download it it from the
+http://www.apache.org/dist/incubator/tamaya[Apache Software Foundation Distribution Directory^].
+
+The release notes for each release of Apache Tamaya
+can be found at the link:history.html[release history page].
+
+== Current Source Code
+
+Downloading of the the current state of the project can be done by
+
+* cloning the https://github.com/apache/incubator-tamaya[GitHub mirror^]
+* Github also provides an easy way to dowload the current project source as zip archive.
+// @todo * Cloning the Apache source tree, see link:3[source section]. source.html
+
+
+== Maven Dependencies
+
+// @todo
+// @todo Details are available <a href="documentation/#_project_configuration_without_maven">here</a>.
+
+
+// @todo Source highlighting does not work currently.
+//
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>{tamaya_mvn_group_id}</groupId>
+ <artifactId>tamaya-api</artifactId>
+ <version>{tamaya_version_released}</version>
+</dependency>
+<dependency>
+ <groupId>{tamaya_mvn_group_id}</groupId>
+ <artifactId>tamaya-core</artifactId>
+ <version>{tamaya_version_released}</version>
+</dependency>
+----
+
+
+== Previous Releases
+
+All previous releases can also be found at the
+http://www.apache.org/dist/incubator/tamaya/[Apache Software Foundation Distribution Directory^].
+In our link:history.html[release history overview] you can find all previous releases of Tamaya.
+
+== Verifying Releases
+
+It is essential that you verify the integrity of any downloaded files using
+the PGP or MD5 signatures. For more information on signing artifacts and
+why we do it, check out the
+http://www.apache.org/dev/release-signing.html[Release Signing FAQ^].
+
+The PGP signatures can be verified using PGP or GPG. First download the
+http://www.apache.org/dist/incubator/tamaya/KEYS[KEYS file^]
+as well as the asc signature file for the artifact. Make sure you get
+these files from the
+http://www.apache.org/dist/incubator/tamaya/[main distribution directory^]
+rather than from a
+http://www.apache.org/dyn/closer.cgi/tamaya/[mirror^].
+Then verify the signatures using e.g.:
+
+[source,shell]
+----
+$ pgpk -a KEYS
+$ pgpv tamaya-project-1.2.0-source-release.zip.asc
+----
+
+or
+[source,shell]
+----
+$ pgp -ka KEYS
+$ pgp tamaya-project-1.2.0-source-release.zip.asc
+----
+
+or
+
+[source,shell]
+----
+$ gpg --import KEYS
+$ gpg --verify tamaya-project-1.2.0-source-release.zip.asc
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/examples.adoc
----------------------------------------------------------------------
diff --git a/content/examples.adoc b/content/examples.adoc
new file mode 100644
index 0000000..3bc94ef
--- /dev/null
+++ b/content/examples.adoc
@@ -0,0 +1,71 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya: Examples
+
+toc::[]
+
+== Tamaya Examples
+
+=== Minimal
+
+This example shows the basic functionality that is available when Tamaya is used without any further extensions.
+It shows how configuration can be added to the classpath and how it can be accessed.
+
+=== Simple PropertySource
+
+This example shows how to write and register an additional +PropertySource+ and +PropertySourceProvider+, which is
+the SPI to add your own configuration data and locations. For a more advanced example you may also have a look at
+the provided default metamodels, e.g. the simple metamodel (currently in the experimental part and not shipped with
+the current release).
+
+=== Resources
+
+This example shows how resources can be located using ANT-styled paths and this feature can help you to implement
++PropertySourceProvider+ instances that provide configuration for a set of files/folders at a certain (searchable)
+location, as provided by the resource extension_.
+
+=== Resolver
+
+The resolver example defines a configuration file that illustrates the usage of placeholders that are resolved on
+configuration access, as provided by the _resolver extension_.
+
+=== Injection
+
+The injection sample shows how to inject configuration into a created object instance, or how to instantiate a proxied
+configuration template, which provides a type-safe configuration access mechanism. This functionality is provided
+by the _injection extension_. Hereby neither JSR 330 nor 299 are used, so it is pure and minimal SE based
+implementation.
+
+=== FileObserver
+
+This example shows how the +event extension+ can be used to automatically adapt the current configuration when
+the underlying configuration data is changing, e.g. when new configuration is added to a file folder, or removed or
+adapted.
+
+=== Builder
+
+This example shows how to build a +Configuration+ using a simple pure SE builder API as provided by the
+_builder extension_.
+
+=== Remote
+
+THe remote example shows a simple setup where parts of the +Configuration+ are read remotedly.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/extensions.adoc b/content/extensions.adoc
new file mode 100644
index 0000000..93b34b5
--- /dev/null
+++ b/content/extensions.adoc
@@ -0,0 +1,107 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Extension Modules
+
+toc::[]
+
+=== Mature Extensions
+
+Mature extensions have a stable API and SPI, similar to the API and Implementations provided.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+| | N/A: currently no extensions have reached that maturity level. | -
+|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation]
+|=======
+
+
+=== Extensions
+
+Extensions in _draft state_ are tested well and normally should have rather stable APIs. Nevertheless API changes may
+still occurr, but we try to prevent such changes if possible.
+
+NOTE All extensions currently run on Java 7 as well as on Java 8.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-builder+ |Provides a fluent-style builder for configurations | link:extensions/mod_builder.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. | link:extensions/mod_filter.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-model+ |Provides support documenting ang validating configuration during runtime. |link:extensions/mod_model.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
+|=======
+
+=== Integrations
+
+These extensions integrate/bridge Tamayas functionality with other frameworks turning their configuration capabilities
+from a sledgehammer to a scalpell:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-cdi+ | Java EE/standalone compliant CDI integration | link:extensions/mod_cdi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-consul+ | Integration with consul clusters. | link:extensions/mod_consul.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-etcd+ | Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation]
+|=======
+
+
+=== Extensions in Experimental Stage
+
+Extensions in _experimental mode_ may still be under discussions. API changes may still happen, so use them
+very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-staged+ |Simple configuration extension to add staged config. | link:extensions/mod_metamodel-staged.html[Documentation]
+|=======
+
+
+=== Integrations in Experimental Stage
+
+Integrations in _experimental mode_ may still be under discussions, or may even not compile ! API changes may still happen, so use them
+very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-commons+ |Integration with Apache Commons Configuration. | -
+|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_builder.adoc b/content/extensions/mod_builder.adoc
new file mode 100644
index 0000000..d734fec
--- /dev/null
+++ b/content/extensions/mod_builder.adoc
@@ -0,0 +1,101 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Builder
+
+// include::temp-properties-files-for-site/attributes.adoc[]
+:jbake-type: page
+:jbake-status: published
+
+[[BuilderCore]]
+== Tamaya Builder (Extension Module)
+=== Overview
+
+The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
+e.g. as follows:
+
+[source,java]
+---------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+// do something
+Configuration config = builder.build();
+---------------------------------------------------------------
+
+Basically the builder allows to create configuration instances completely independent of the current configuration
+setup. This gives you full control on the +Configuration+ setup.
+
+=== Compatibility
+
+The module is based on Java 7, so it will run on Java 7 and does
+not require Java 8. The +ConfigurationProvider+
+as defined by the API, provides a builder instance for +ConfigurationContext+
+in a similar way. A +Configuration+ can also be created by passing an instance of a +ConfigurationContext+:
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding
+dependency to your module:
+
+[source,xml,subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-builder</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+-----------------------------------------------
+
+=== Supported Functionality
+
+The builder allows you to add +PropertySource+ instances:
+
+[source,java]
+----------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+builder.addPropertySources(sourceOne).addPropertySources(sourceTwo);
+Configuration config = builder.build();
+----------------------------------------------------------------
+
+Similarly you can add filters:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertyFilters(new MyConfigFilter());
+----------------------------------------------------------------
+
+...or +PropertySourceProvider+ instances:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertySourceProvider(new MyPropertySourceProvider());
+----------------------------------------------------------------
+
+Also the builder module allows to include/exclude any filters and property source already known to the current
++ConfigurationContext+:
+
+[source,java]
+----------------------------------------------------------------
+builder.disableProvidedPropertyConverters();
+builder.enableProvidedPropertyConverters();
+
+builder.disableProvidedPropertyFilters();
+builder.enableProvidedPropertyFilters();
+
+builder.disableProvidedPropertySources();
+builder.enableProvidedPropertySources();
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_camel.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_camel.adoc b/content/extensions/mod_camel.adoc
new file mode 100644
index 0000000..9d9a60d
--- /dev/null
+++ b/content/extensions/mod_camel.adoc
@@ -0,0 +1,145 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+= Apache Tamaya -- Extension: Integration with Apache Camel
+:jbake-type: page
+:jbake-status: published
+
+toc::[]
+
+
+[[Optional]]
+== Integration with Apache Camel (Extension Module)
+=== Overview
+
+The Tamaya Camel integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with Apache Camel.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-camel</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Camel integration comes basically with three artifacts:
+
+* A Camel +ResolverFunction+ implementation adding explicit property resolution
+ (+org.apache.tamaya.integration.camel.TamayaPropertyResolver+).
+* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and
+ additionally allows using Tamaya configuration as Camel _overrides_
+ (+org.apache.tamaya.integration.camel.TamayaPropertiesComponent+).
+
+
+=== Configuring using Camel Java DSL
+
+Camel integration using Java DSL is basically simple:
+
+[source, java]
+-----------------------------------------------
+import org.apache.tamaya.integration.camel.TamayaPropertiesComponent;
+
+camelContext.addComponent("properties", new TamayaPropertiesComponent());
+-----------------------------------------------
+
+Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows:
+
+[source, java]
+-----------------------------------------------
+RouteBuilder builder = new RouteBuilder() {
+ public void configure() {
+ from("direct:hello1").transform().simple("{{cfg:message}}");
+ }
+};
+camelContext.addRoutes(builder);
+builder = new RouteBuilder() {
+ public void configure() {
+ from("direct:hello2").transform().simple("{{tamaya:message}}");
+ }
+};
+camelContext.addRoutes(builder);
+-----------------------------------------------
+
+
+Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used
+as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel
++PropertiesComponent+:
+
+[source, java]
+-----------------------------------------------
+TamayaPropertiesComponent props = new TamayaPropertiesComponent();
+props.setTamayaOverrides(true);
+-----------------------------------------------
+
+
+=== Configuring using Camel XML DSL
+
+Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean
+as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we
+again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback:
+
+[source, xml]
+-----------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
+ ">
+
+ <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring">
+ <route id="r1">
+ <from uri="direct:hello1"/>
+ <transform>
+ <simple>{{message}}</simple>
+ </transform>
+ </route>
+ <route id="r2">
+ <from uri="direct:hello2"/>
+ <transform>
+ <simple>{{cfg:message}}</simple>
+ </transform>
+ </route>
+ <route id="r3">
+ <from uri="direct:hello3"/>
+ <transform>
+ <simple>{{tamaya:message}}</simple>
+ </transform>
+ </route>
+ </routeContext>
+
+ <bean id="properties" class="org.apache.tamaya.integration.camel.TamayaPropertiesComponent">
+ <property name="tamayaOverrides" value="true"/>
+ </bean>
+
+</beans>
+-----------------------------------------------