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 2016/03/17 01:28:42 UTC
[11/11] incubator-tamaya git commit: Moved all docs to site part.
Removed some of the file hierarchies for getting things work.
Moved all docs to site part. Removed some of the file hierarchies for getting things work.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/fbda5b8e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/fbda5b8e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/fbda5b8e
Branch: refs/heads/master
Commit: fbda5b8e3d72214c9b61cca8f4c1a5cabaa46158
Parents: f080642
Author: anatole <an...@apache.org>
Authored: Thu Mar 17 01:26:33 2016 +0100
Committer: anatole <an...@apache.org>
Committed: Thu Mar 17 01:26:33 2016 +0100
----------------------------------------------------------------------
docs/pom.xml | 5 +-
docs/src/main/assembly/documentation.xml | 2 +-
pom.xml | 8 +-
src/site/asciidoc/API.adoc | 615 ++++++++++++++++++
src/site/asciidoc/Core.adoc | 224 +++++++
src/site/asciidoc/HighLevelDesign.adoc | 166 +++++
src/site/asciidoc/Requirements.adoc | 250 ++++++++
src/site/asciidoc/community.adoc | 13 +-
src/site/asciidoc/devguide.adoc | 209 ++++++
src/site/asciidoc/devguide/index.adoc | 207 ------
src/site/asciidoc/download.adoc | 4 +-
src/site/asciidoc/examples.adoc | 69 ++
src/site/asciidoc/extensions.adoc | 105 +++
src/site/asciidoc/extensions/index.adoc | 124 ----
src/site/asciidoc/extensions/mod_builder.adoc | 14 -
src/site/asciidoc/extensions/mod_camel.adoc | 22 +-
src/site/asciidoc/extensions/mod_cdi.adoc | 22 +-
.../extensions/mod_classloader_support.adoc | 21 -
.../asciidoc/extensions/mod_collections.adoc | 21 -
src/site/asciidoc/extensions/mod_consul.adoc | 22 +-
.../asciidoc/extensions/mod_environment.adoc | 22 +-
src/site/asciidoc/extensions/mod_etcd.adoc | 22 +-
src/site/asciidoc/extensions/mod_events.adoc | 25 +-
src/site/asciidoc/extensions/mod_filter.adoc | 22 +-
src/site/asciidoc/extensions/mod_formats.adoc | 25 +-
src/site/asciidoc/extensions/mod_functions.adoc | 24 -
src/site/asciidoc/extensions/mod_injection.adoc | 25 +-
src/site/asciidoc/extensions/mod_jodatime.adoc | 24 -
src/site/asciidoc/extensions/mod_json.adoc | 40 +-
.../asciidoc/extensions/mod_management.adoc | 25 +-
.../extensions/mod_metamodel-staged.adoc | 22 +-
src/site/asciidoc/extensions/mod_model.adoc | 25 +-
.../asciidoc/extensions/mod_mutable_config.adoc | 25 +-
src/site/asciidoc/extensions/mod_optional.adoc | 25 +-
src/site/asciidoc/extensions/mod_osgi.adoc | 25 +-
src/site/asciidoc/extensions/mod_remote.adoc | 25 +-
src/site/asciidoc/extensions/mod_resolver.adoc | 15 -
src/site/asciidoc/extensions/mod_resources.adoc | 15 -
src/site/asciidoc/extensions/mod_server.adoc | 25 +-
.../asciidoc/extensions/mod_spi-support.adoc | 22 +-
src/site/asciidoc/extensions/mod_spring.adoc | 21 +-
src/site/asciidoc/extensions/mod_yaml.adoc | 40 +-
src/site/asciidoc/history.adoc | 2 +-
.../asciidoc/misc/PossibleContributions.adoc | 45 +-
src/site/asciidoc/quickstart.adoc | 18 +-
src/site/asciidoc/release-guide.adoc | 14 +-
src/site/asciidoc/source.adoc | 5 +-
src/site/asciidoc/usecases.adoc | 273 ++++++++
src/site/asciidoc/userguide.adoc | 36 ++
src/site/asciidoc/userguide/API.adoc | 634 -------------------
src/site/asciidoc/userguide/Core.adoc | 246 -------
.../asciidoc/userguide/HighLevelDesign.adoc | 186 ------
src/site/asciidoc/userguide/Requirements.adoc | 267 --------
src/site/asciidoc/userguide/examples.adoc | 82 ---
src/site/asciidoc/userguide/index.adoc | 44 --
.../asciidoc/userguide/uc/combine-configs.adoc | 14 -
.../uc/context-dependent-configuration.adoc | 7 -
.../userguide/uc/dynamic-provisioning.adoc | 18 -
.../userguide/uc/external-configuration.adoc | 6 -
src/site/asciidoc/userguide/uc/formats.adoc | 8 -
src/site/asciidoc/userguide/uc/injection.adoc | 31 -
src/site/asciidoc/userguide/uc/java8.adoc | 14 -
src/site/asciidoc/userguide/uc/locations.adoc | 10 -
src/site/asciidoc/userguide/uc/management.adoc | 7 -
.../userguide/uc/minimal-propertysource.adoc | 6 -
.../userguide/uc/multiple-configurations.adoc | 14 -
.../userguide/uc/scannable-properties.adoc | 4 -
.../asciidoc/userguide/uc/service-context.adoc | 15 -
.../asciidoc/userguide/uc/simple-access.adoc | 25 -
.../userguide/uc/simple-property-access.adoc | 9 -
src/site/asciidoc/userguide/uc/templates.adoc | 12 -
.../userguide/uc/type-safe-properties.adoc | 10 -
.../userguide/uc/value-placeholders.adoc | 8 -
src/site/asciidoc/userguide/usecases.adoc | 58 --
src/site/markdown/index.md | 18 +-
src/site/site.xml | 6 +-
76 files changed, 2032 insertions(+), 2782 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/fbda5b8e/docs/pom.xml
----------------------------------------------------------------------
diff --git a/docs/pom.xml b/docs/pom.xml
index 11bc2c1..97d6991 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -97,11 +97,12 @@ under the License.
<goal>process-asciidoc</goal>
</goals>
<configuration>
+ <sourceDirectory>${project.basedir}/../src/site/asciidoc</sourceDirectory>
<attributes>
<tamayaVersion>${project.version}</tamayaVersion>
</attributes>
- <baseDir>${project.basedir}</baseDir>
- <imagesDir>${project.basedir}/src/main/images/</imagesDir>
+ <projectDirectory>${project.basedir}/../src/site/asciidoc</projectDirectory>
+ <!--<imagesDir>${project.basedir}/../src/site/asciidoc/</imagesDir>-->
<outputDirectory>${project.build.directory}/adocs</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<backend>html</backend>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/fbda5b8e/docs/src/main/assembly/documentation.xml
----------------------------------------------------------------------
diff --git a/docs/src/main/assembly/documentation.xml b/docs/src/main/assembly/documentation.xml
index 501a0c6..a264485 100644
--- a/docs/src/main/assembly/documentation.xml
+++ b/docs/src/main/assembly/documentation.xml
@@ -30,7 +30,7 @@ under the License.
<fileSets>
<fileSet>
- <directory>${project.directory}/../src/site/asciidoc</directory>
+ <directory>${project.build.directory}/adocs</directory>
<outputDirectory>docs</outputDirectory>
</fileSet>
</fileSets>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/fbda5b8e/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 0cc6f49..625b0d3 100644
--- a/pom.xml
+++ b/pom.xml
@@ -151,12 +151,12 @@ under the License.
<developers>
<developer>
<name>Anatole Tresch</name>
- <id>atsticks</id>
- <email>atsticks -at- apache.org</email>
+ <id>anatole</id>
+ <email>anatole -at- apache.org</email>
<roles>
<role>PMC</role>
</roles>
- <timezone />
+ <timezone>+1</timezone>
</developer>
<developer>
@@ -198,7 +198,7 @@ under the License.
<role>PMC</role>
</roles>
<email>plexus@apache.org</email>
- <timezone>-1</timezone>
+ <timezone>+1</timezone>
</developer>
</developers>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/fbda5b8e/src/site/asciidoc/API.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/API.adoc b/src/site/asciidoc/API.adoc
new file mode 100644
index 0000000..741f39e
--- /dev/null
+++ b/src/site/asciidoc/API.adoc
@@ -0,0 +1,615 @@
+// 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[]
+
+[[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/blob/fbda5b8e/src/site/asciidoc/Core.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/Core.adoc b/src/site/asciidoc/Core.adoc
new file mode 100644
index 0000000..8e4edfe
--- /dev/null
+++ b/src/site/asciidoc/Core.adoc
@@ -0,0 +1,224 @@
+// 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[]
+
+[[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.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
+|java.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
+|java.lang.Character |CharConverter |0xFF, 'a', 'H', 123
+|java.lang.Class |ClassConverter |<fully qualified class name>
+|java.util.Currency |CurrencyConverter |CHF, 123
+|java.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|_Enums_ |EnumConverter |<Enum item name>
+|java.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|java.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
+|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
+|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
+|java.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
+|java.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
+|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
+|ZoneId |ZoneIdConverter |Europe/Zurich
+|=======
+
+
+=== Registering PropertyConverters
+
+Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+,
+meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified
+class names of the converters to be registered (one line per each).
+
+Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically.
+
+NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically.
+
+
+[[ComponentLoadingAndPriorization]]
+=== Component Loading and Priorization
+
+Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components
+must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified
+implementation class names of the components to be registered (one line per each).
+The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya
+core adds this functionality by the possibility to add +@Priority+ annotations to the components registered.
+By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning
+
+* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value
+ effectively _overrides/replaces_ any component with lower values.
+* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the
+ ones with higher priority are before components with lower priority.
+* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is
+ still defined and predictable in almost all scenarios.
+
+
+[[RegisteringPropertySources]]
+=== Registering Property Sources
+
+PropertySources that provide configuration properties are registered as ordinary components as described in the previous
+section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit
++int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful
+due to several reasons:
+
+* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being
+ added easily.
+* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or
+ whatever may be appropriate.
+
+
+[[CorePropertySources]]
+== Configuration Setup in Core
+
+Tamaya Core provides a minimal 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+
+
+
+=== 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
+|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+.
+
+
+[[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/blob/fbda5b8e/src/site/asciidoc/HighLevelDesign.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/HighLevelDesign.adoc b/src/site/asciidoc/HighLevelDesign.adoc
new file mode 100644
index 0000000..1e85677
--- /dev/null
+++ b/src/site/asciidoc/HighLevelDesign.adoc
@@ -0,0 +1,166 @@
+// 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[]
+
+
+[[Core Concepts]]
+== The Tamaya High Level Design
+Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
+that build the base of all the other mechanisms:
+
+The *API* (package +org.apache.tamaya+) provides
+
+* A simple but complete SE *API* for accessing key/value based _Configuration_:
+ ** +Configuration+ hereby models configuration, the main interface of Tamaya, providing key/value pairs as raw
+ (String-based) key/value pairs, allowing also access to typed values.
+ ** +ConfigurationProvider+ provides the static entry point for accessing configuration.
+
+The *SPI* (package +org.apache.tamaya.spi+) provides:
+ ** A simple minimalistic model for configuration data, called _PropertySource_.
+ ** Several extension points for adding additional configuration property sources or adapting the internal workings
+ of the overall system.
+ ** A +ServiceContext / ServiceContextManager+ that controls the loading of the components in Tamaya. This allows to
+ adapt the behaviour depending on the runtime environment in use, e.g. a Java standalone application, an OSGI
+ container or a Java EE application server.
+
+Tamaya *Modules* finally allow to add additional functionality to customize your configuration solution with the
+functionality you want. E.g. modules are providing features such as
+
+* Configuration _injection_
+* _Dynamic placeholders_ and resolution mechanism for configuration values
+* Abstractions for reusable _configuration formats_
+* Dynamic configuration updates and change events
+* Support for OSGI/Java EE Classloading
+* A configuration server/client
+* and more...
+
+
+== How Tamaya organizes Configuration
+=== Overview
+
+All the mentioned artifacts are used to organize configuration in a higly flexible and extendable way. Hereby the
++PropertySource+ is the key artifact. In general Tamaya organizes Configuration as follows:
+
+image::../images/CoreDesign.png[]
+
+Key abstraction hereby is the +ConfigurationContext+, which basically
+
+* an ordered chain of +PropertySource+ instances. This chain is used to evaluate raw configuration values.
+* a set of +PropertyFilter+ instances that filter the raw values evaluated from the property source chain.
+* a set of +PropertyConverter+ that convert String values into typed values when needed.
+
+In most standalone use cases only one +ConfigurationContext+ will be active at a time. But in more complex scenarios,
+such as Java EE also multiple contexts could be active that are active depending on the current runtime context
+(e.g. attached to the corresponding classloader(s)). These aspects are basically handled by the
++ConfigurationProvider+ and its corresponding SPIs.
+
+=== Loading the current _ConfigurationContext_
+
+The +ConfigurationContext+ is the core of Tamaya. It manages all configuration sources and additional components
+required to evaluate a concrete configuration value:
+
+* Tamaya loads all available +PropertySource+ instances. Hereby +PropertySource+ instances can be
+ ** Directly registered (using the mechanism defined by the current +ServiceContext+ implementation, by default
+ the Java +ServiceLoader+.
+ ** Provided by a registered instance of +PropertySourceProvider+.
+* All loaded property sources are _ordered based on each ordinal_, returned from +PropertySource.getOrdinal()+ as
+ an ordered chain of PropertySources, building up the ordered chain of +PropertySource+ instances used for raw
+ configuration value evaluation.
+* Tamaya loads all available +PropertyFilter+ instances. Hereby +PropertyFilter+ instances can be registered
+ by default using the Java +ServiceLoader+ API. The +PropertyFilter+ instances loaded are ordered based on the
+ +@Priority+ annotations found on each filter. If no priority annotation is present, +0+ is assumed.
+* Tamaya loads all available +PropertyConverter+ instances. Hereby +PropertyConverter+ instances can be registered
+ by default using the Java +ServiceLoader+ API. The +PropertyConverter+ instances loaded are ordered based on the
+ +@Priority+ annotations found on each filter. If no priority annotation is present, +0+ is assumed. It is
+ possible to register multiple converters for the same target type.
+
+=== Evaluating raw property values
+When evaluating a concrete configuration value for a given key, Tamaya iterates through this chain of registered
+PropertySources. Hereby the final value, by default, is determined by the last non-null value returned from a
++PropertySource+.
+
+Since the ladder may not always be appropriate, e.g. when values should be combined instead of overridden, a
+instance of +PropertyValueCombinationPolicy+ can be registered, which allows to add more detailed behaviour how values
+are combined.
+
+Access to the complete configuration +Map+ is performing the same resolution and combination algorithm, but for all
+key/value pairs available.
+
+=== Filtering the raw properties:
+Each raw configuration value evaluated is filtered by the ordered filter chain, as long as there are any changes
+applied by any of the filters called. This ensures that also transitive replacements by filters are possible.
+If, after a configurable number of evaluation loops still values are changes during each loop, the filtering
+process is aborted, since a non-resolvable circular filter issue is assumed.
+
+The output is the final configuration value as type +String+.
+
+=== Applying type conversion:
+Finally, if the required target type, does not match +Java.lang.String+, all registered +PropertyConverter+
+instances targeting the corresponding target type are asked to convert the given (String-based) configuration
+entry to the required (non String) target type.
+
+Hereby the first _non-null_ value returned by a +PropertyConverter+ is used as the final typed configuration value and
+returned to the caller.
+
+=== Advanced Features
+Basically the bahaviour of Tamaya can be customized using the following mechanisms. Basically configuration can be
+provided using the following mechanism:
+
+* Registering additional (default) +PropertySource+ instances. Depending on their _ordinal value_ they
+ will override or extend existing configuration.
+* Registering additional (default) +PropertySourceProvider+ instances.that can provide multiple +PropertySource+
+ instances.
+
+Additionally Tamaya provides hooks for further adapting the internal workings:
+
+* Adapting the way how multiple entries with the same key are combined (+PropertyValueCombinationPolicy+). This
+ may be useful, if overriding is not the way how entries of the same key should be combined. An example, where
+ such an alternate scenario is useful are list entries, that combine all entries encountered to a collecting
+ list entry.
+* Adding additional support for new target types configurable by registering additional +PropertyConverter+
+ instances. This can be used for adding support for new types as well as for adding support for additional
+ formats.
+* Complex extensions may adapt the complete +ConfigurationContext+, using the +ConfigurationContextBuilder+ and
+ reapply the changed instance using +ConfigurationProvider.setConfigurationContext(ConfigurationContext)+.
+ This is one example how to react on dynamic changes detected on configuration files read.
+* Registering additional +PropertyFilter+ instances, that filter the configuration values extracted.
+* Registering an alternate +ServiceContext+ to support alternate runtime containers, e.g. a CDI container.
+* A combination of all above.
+
+Additionally instances of +ConfigOperator, ConfigQuery+ can be provided that provide additional functionality
+that should not be globally visible. It is recommended to provide them from a singleton accessor, hereby hiding
+the effective implementation classes.
+
+== Component Loading
+
+As mentioned the component loading of Tamaya can be adapted. By default the JDK +ServiceLoader+ API is used to determine
+a +ServiceContext+ implementation that should control
+Tamaya's overall component loading. If not found, a default implementation is registered, which relies on the
+Java +hava.util.ServiceLoader+ mechanism. This behaviour can be changed by implementing your own version
+of the +ServiceContext+ interface, annotating it with a +@Priority+ annotation and registering it using the
++java.util.ServiceLoader+ mechanism.
+
+== Compatibility
+
+The Tamaya API is compatible with Java 7 and beyond.
+
+== Further Documentation
+
+Being here we recommend to have a look at the more detailed documentation of Tamaya's link:API.html[API and SPI],
+and of its current available link:extensions.html[modules].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/fbda5b8e/src/site/asciidoc/Requirements.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/Requirements.adoc b/src/site/asciidoc/Requirements.adoc
new file mode 100644
index 0000000..1c6ead1
--- /dev/null
+++ b/src/site/asciidoc/Requirements.adoc
@@ -0,0 +1,250 @@
+// 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[]
+
+[[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/fbda5b8e/src/site/asciidoc/community.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/community.adoc b/src/site/asciidoc/community.adoc
index c10b119..d2917a3 100644
--- a/src/site/asciidoc/community.adoc
+++ b/src/site/asciidoc/community.adoc
@@ -17,15 +17,16 @@
// under the License.
//
+include::temp-properties-files-for-site/attributes.adoc[]
-= Community
+== Community
:toc:
:sectnums:
// Document properties
:twitterhandle: tamayaconf
-== Users
+=== Users
// todo Fix the links when finishing the new homepage, Oliver B. Fischer, 2015-09-12
If you are a new user and you would like to participate in Tamaya
@@ -44,7 +45,7 @@ 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
+=== Getting Involved
Everybody is welcome to get involved with our community. You can find general
information at http://apache.org/foundation/getinvolved.html and
@@ -59,7 +60,7 @@ documentation.html[instructions about the Documentation]
that addresses how to contribute, render and publish it.
-=== Contributors
+==== 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,
@@ -69,14 +70,14 @@ or http://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate
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/050-gitworkflow.html[suggested Git approach].
+link:devguide.html[suggested Git approach].
// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12
The lists of current contributors and committers can be found
on the link:contributors.html[contributers page^].
-=== Committers
+==== 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.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/fbda5b8e/src/site/asciidoc/devguide.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/devguide.adoc b/src/site/asciidoc/devguide.adoc
new file mode 100644
index 0000000..a61a10e
--- /dev/null
+++ b/src/site/asciidoc/devguide.adoc
@@ -0,0 +1,209 @@
+// 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[]
+
+== 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/blob/fbda5b8e/src/site/asciidoc/devguide/index.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/devguide/index.adoc b/src/site/asciidoc/devguide/index.adoc
deleted file mode 100644
index 599d9a1..0000000
--- a/src/site/asciidoc/devguide/index.adoc
+++ /dev/null
@@ -1,207 +0,0 @@
-= Apache Tamaya -- Development Guide
-//:name: Tamaya
-//:rootpackage: org.apache.tamaya
-//:title: Apache Tamaya
-//:revnumber: 0.1-SNAPSHOT
-//:revremark: Incubator
-//:revdate: November 2014
-//:longversion: {revnumber} ({revremark}) {revdate}
-//:authorinitials: ATR
-//:author: Anatole Tresch
-//:email: <an...@apache.org>
-:source-highlighter: coderay
-//:website: http://tamaya.incubator.apache.org/
-:toc:
-//:toc-placement: manual
-:encoding: UTF-8
-:numbered:
-
-
-== 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/blob/fbda5b8e/src/site/asciidoc/download.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/download.adoc b/src/site/asciidoc/download.adoc
index e81332b..78e0700 100644
--- a/src/site/asciidoc/download.adoc
+++ b/src/site/asciidoc/download.adoc
@@ -20,9 +20,7 @@
include::temp-properties-files-for-site/attributes.adoc[]
:linkattrs: true
-= Downloading Apache Tamaya
-
-// @todo Is a ToC here really required? :toc:
+== Downloading Apache Tamaya
The latest release is Apache Tamaya {tamaya_version_current}.
You can download it it from the