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/12/18 22:39:50 UTC
[06/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_mutable_config.adoc b/content/documentation/extensions/mod_mutable_config.adoc
new file mode 100644
index 0000000..cb8869d
--- /dev/null
+++ b/content/documentation/extensions/mod_mutable_config.adoc
@@ -0,0 +1,267 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Mutable Configuration
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Mutable Configuration (Extension Module)
+=== Overview
+
+Tamaya Configuration by default is read-only, which covers must of the use cases. But there are many legit scenarios
+where configuration should be written back to some backend systems or the local file system. This module adds this
+functionality.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+To benefit from configuration mutability support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-mutable-config</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+=== Core Architecture
+
+==== Accessing MutableConfiguration
+
+The core of the module is the +MutableConfigurationProvider+ singleton, which provides access to +MutableConfiguration+
+instance, which extends +Configuration+. This interface adds additional methods to add/update or remove property values.
+Hereby changes applied are managed in a transaction like context, called +ConfigChangeContext+. Each context defines
+a UUID that identifes a change.
+Backends for writing changes applied are of type +MutablePropertySource+, similarly extending the +PropertySource+
+SPI with methods for writing changes back. Registrations and ordering policies are like with ordinary property sources,
+with one important difference. Mutable property source can be targeted by write operations.
+
+The example below shows how a +MutableConfiguration+ can be obtained the simplest way:
+
+[source,java]
+.Accessing and changing configuration
+--------------------------------------------
+MutableConfiguration config = MutableConfigurationProvider
+ .createMutableConfiguration();
+config.put("newKey", "newValue")
+ .put("anotherKey", "updatedValue")
+ .remove("valueNotValid")
+ .store();
+--------------------------------------------
+
+In the above scenario we use the overall system's configuration as the backend to be used.
+We can also pass any +Configuration+ to render it into a mutable instance, e.g.
+
+[source,java]
+.Explicitly passing the backing configuration
+--------------------------------------------
+Configuration config = ...;
+MutableConfiguration config = MutableConfigurationProvider
+ .createMutableConfiguration(config);
+--------------------------------------------
+
+NOTE: If a configuration does not contain any +MutablePropertySource+ instances,
+ a +MutableConfiguration+ built from it will not be able to accept any changes.
+
+
+Following you see the options how to create a +MutableConfiguration+ using the
++MutableConfigurationProvider+ singleton:
+
+[source, java]
+---------------------------------------------
+public final class MutableConfigurationProvider {
+
+ private MutableConfigurationProvider(){}
+
+ public static MutableConfiguration createMutableConfiguration();
+ public static MutableConfiguration createMutableConfiguration(
+ ChangePropagationPolicy changePropgationPolicy);
+ public static MutableConfiguration createMutableConfiguration(Configuration configuration);
+ public static MutableConfiguration createMutableConfiguration(
+ Configuration configuration,
+ ChangePropagationPolicy changePropgationPolicy);
+
+ [...]
+}
+---------------------------------------------
+
+Hereby +MutableConfiguration+ is defined as follows:
+
+[source, java]
+---------------------------------------------
+public interface MutableConfiguration extends Configuration {
+
+ void store();
+
+ ConfigChangeRequest getConfigChangeRequest();
+ ChangePropagationPolicy getChangePropagationPolicy();
+
+ MutableConfiguration put(String key, String value);
+ MutableConfiguration putAll(Map<String, String> properties);
+ MutableConfiguration remove(Collection<String> keys);
+ MutableConfiguration remove(String... keys);
+
+}
+---------------------------------------------
+
+
+==== Targeting the right MutablePropertySources
+
+A +Configuration+ may have multiple +MutablePropertySource+ instances present. These are members of Tamaya's oredered list of
++PropertySources+ to evaluate the configuration. Nevertheless writing back changes requires additional aspects to
+be considered:
+* Should changes being written back to all mutable property sources? Or should a key that could be added or removed
+ on a more significant instance not be written/removed on less significant property source instances?
+* Should a change be applied only to a specific mutable property source, regardless its position in the
+ processing chain?
+
+Therefore a +ChangePropagationPolicy+ can be set on a +MutableConfiguration+ instance, which allows to control
+this aspect:
+
+[source,java]
+.Explicitly passing the backing configuration
+--------------------------------------------
+public interface ChangePropagationPolicy {
+ /**
+ * Method being called when a multiple key/value pairs are added or updated.
+ * @param propertySources the property sources, including readable property sources of the current configuration,
+ * never null.
+ * @param configChange the configuration change, not null.
+ */
+ void applyChange(ConfigChangeRequest configChange, Collection<PropertySource> propertySources);
+}
+--------------------------------------------
+
+By default, changes are applied to all registered +MutablePropertySources+ similarly.
+
+
+Also the +MutableConfigurationProvider+ provides access to the most commonly used change propagation policies:
+
+[source, java]
+---------------------------------------------
+public final class MutableConfigurationProvider {
+
+ [...]
+
+ public static ChangePropagationPolicy getApplyAllChangePolicy();
+ public static ChangePropagationPolicy getApplyMostSignificantOnlyChangePolicy();
+ public static ChangePropagationPolicy getApplySelectiveChangePolicy(String... propertySourceNames);
+ public static ChangePropagationPolicy getApplyNonePolicy();
+}
+---------------------------------------------
+
+
+==== Some Aspects to consider
+
+Due to Tamaya's design the effective effect of your changes to the overall configuration, cannot
+be sometimes a bit tricky to be predicted, since it depends on several aspects:
+
+. is the corresponding configuration resource configured as part of the current system's configuration?
+. what is the +PropertySource's+ priority within the configuration context? Is it overriding or overridden
+ by other sources?
+. is the change directly visible to the configuration system? E.g. injected values are normally not updated,
+ whereas injecting a +DynamicValue<T>+ instance allows to detect and react single value changes. Also the
+ +PropertySources+ implementation must be able to detect any configuration changes and adapt its values returned
+ accordingly. Finally values also can be marked as immutable or being cached.
+. Is configuration cached, or written/collected directly on access?
+. can the changes applied be committed at all?
+
+So it is part of your application configuration design to clearly define, which property sources may be read-only, which
+may be mutable, how overriding should work and to which backends finally any changes should be written back. Nevertheless
+changing or adding value is very easy:
+
+[source,java]
+.Changing a configuration
+--------------------------------------------
+MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
+config.put("newKey", "newValue");
+config.remove("mycluster.myapp.myKey");
+config.store();
+--------------------------------------------
+
+
+=== Configuration Changes
+
+This module does not handle detection of changes to the overall system's +Configuration+. This can be done in
+several ways, e.g. by:
+
+* using the _tamaya-events_ extension, which can be used to observe the system's configuration and
+ publishing events when things have been changed.
+* The SPI implementing the +MutableConfigurationBackendSpi+ may inform/update any affected +PropertySource,
+ PropertySourceProvider+ instances about the changes applied.
+
+
+=== Supported Backends
+
+Multiple backends are supported. E.g. the _etcd_ integration module of Tamaya also registers
+corresponding SPI implementations/backends. By default this module comes with
+the following +MutablePropertySource+ implementations:
+
+* +MutablePropertySource+ resources, targeting local +.properties+ files, using the +java.util.Properties+
+ format.
+* +MutableXmlPropertySource+ resources, targeting local +.xml+ property files, using the +java.util.Properties+
+ XML format.
+
+==== Refreshable Property Sources
+
+Somehow similar to configuration changes applied explicitly is the case, where values of underlying
+configuration backends change and must be reflected in the new configuration tree. Examples are:
+
+* Configuration files being edited, added or removed.
+* Changes on remote servers like etcd, consul
+* etc.
+
+For having a common API for refreshable items a +Refreshable+ interface is defined:
+
+[source,java]
+.Refreshable interface
+--------------------------------------------
+/**
+ * Interface to be implemented by items that can be refreshed. By default
+ * these are property sources, but more types may be supported at a later
+ * point in time.
+ */
+public interface Refreshable {
+
+ /**
+ * Refreshes the item by reloading its internal state.
+ */
+ void refresh();
+
+}
+--------------------------------------------
+
+
+==== Refreshable Property Sources
+
+=== SPIs
+
+The module defines +MutableConfigurationProviderSpi+, that is used as a delegate by the +MutableConfigurationProvider+
+singleton accessor:
+
+[source,java]
+.SPI: MutableConfigurationProviderSpi
+--------------------------------------------------
+public interface MutableConfigurationProviderSpi {
+ /**
+ * Creates a new {@link MutableConfiguration} with {@code autoCommit = false} as default.
+ *
+ * @param configuration the configuration, not null.
+ * @param propagationPolicy policy that defines how changes are published to the property
+ * sources.
+ * @return a new mutable configuration instance.
+ */
+ MutableConfiguration createMutableConfiguration(Configuration configuration,
+ ChangePropagationPolicy propagationPolicy);
+}
+--------------------------------------------------
+
+Implementations are registered with the current +ServiceContext+ (using by default the
+ +java.util.ServiceLoader+ service).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_optional.adoc b/content/documentation/extensions/mod_optional.adoc
new file mode 100644
index 0000000..1a4b967
--- /dev/null
+++ b/content/documentation/extensions/mod_optional.adoc
@@ -0,0 +1,54 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Optional Tamaya Configuration
+
+toc::[]
+
+
+[[Optional]]
+== Tamaya Optional Configuration (Extension Module)
+=== Overview
+
+The Tamaya optional module provides contains three types only. It is for projects that want to benefit from Tamaya
+configuration optionally only. E.g. doing an OSS project you can declare to support configuration with Tamaya as
+an optional extension. This module can be added as a hard dependency to your code, hereby adding only three artofacts.
+It automatically checks the availability of Tamaya on the classpath and only if available tries to access it for
+configuration evaluation. Additionally an EvaluationPolicy lets you define the precedence of configured values
+(yours, or Tamaya ones if present).
+
+
+=== 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-optional</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Reading configuration using the Tamaya Optional Module
+
+The optional module allows reading configuration with a small subset of functionality only. For extended of full
+featured config please consider using the Apache Tamaya as a full configuration backend.
+
+[source, java]
+-----------------------------------------------
+BigDecimal interestRate =
+ OptionalConfiguration.of(
+ EvaluationPolicy.TAMAYA_OVERRIDES_OTHER,
+ (k) -> MyConfigMechanism.get(k) // String get(String key);
+ )
+ .get("com.mycomp.ratecalculator.rate", BigDecimal.class))
+ .orElse(BigDecimal.of(0.05d));
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_osgi.adoc b/content/documentation/extensions/mod_osgi.adoc
new file mode 100644
index 0000000..3a3ffd4
--- /dev/null
+++ b/content/documentation/extensions/mod_osgi.adoc
@@ -0,0 +1,116 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extensions: OSGI Integrations
+
+toc::[]
+
+
+[[Optional]]
+== Tamaya OSGI Support
+=== Overview
+
+Tamaya provides also support for integration with OSGI. Hereby several options are available how Tamaya can be used in
+an OSGI context:
+
+. All Tamaya modules, its API and core library are actually valid OSGI bundles. So adding them into your OSGI modules
+ and using Tamaya is basically directly supported. Nevertheless OSGI works rather differently from a class- and
+ resource loading perspective. As long as you rely on Tamaya's mechanisms for resource loading things should work
+ out of the box. In the back Tamaya's core module actually comes with implicit OSGI support, which is automatically
+ activated, if Tamaya is running in an OSGI context. This support actually
+ ** Listens on deployed bundles and actively reads all resources configured as +java.util.ServiceLoader+ services and
+ registers them as OSGI services. Hereby integration is complete meaning you can also register Tamaya services
+ as normal OSGI services, e.g. your own +PropertySource+ instances.
+ ** Uses the OSGI bundle to resolve for resources, because accessing them from the classloader directly
+ typically fails in an OSGI context.
+. Adding Tamaya's OSGI integration module replaces the existing OSGI +ConfigAdmin+ service with an istance based on
+ Tamaya. Hereby several aspects can be configured using system properties:
+ ** +org.tamaya.integration.osgi.cm.ranking+ (int) allows to configure the OSGI service ranking used by the Tamaya
+ BundleActivator to register Tamaya's +ConfigAdmin+ service. In OSGI higher ranking precede lower rankings. By default
+ Tamaya's OSGI extending service registration mechanism is reusing any annotated +@Priority+ priority values as
+ corresponsing rankings.
+ ** +org.tamaya.integration.osgi.cm.override+ (boolean) allows to configure if Tamaya is overriding any existing
+ values from the default +ConfigAdmin+ instance, or only extending them. In other words this setting allows you to
+ define, which configuration subsystem has precedence for evaluating the final values, either Tamaya based
+ configuration (default) or the configuration mechanisms provided by default from your OSGI container (when this flag
+ is set to +false+).
+ ** +org.tamaya.integration.osgi.cm.inject+ allows you to deactivate injection of configuration values into your
+ OSGI services (by default injection is enabled). In all cases accessing the OSGI +ConfigAdmin+ service to
+ read your configuration is working as usual. But Tamaya adds additional injection functionality, which allows
+ to inject typed configuration as described by the Tamaya injection api.
+
+It is also possible to combine things, e.g. when you only define a low ranking for Tamaya's configuration service and
+the same time allow injection to be active, you will have Tamaya's injection support based on your default
+OSGI configuration.
+
+
+=== Compatibility
+
+All module described are based on Java 7, so it will run on Java 7 and beyond.
+The modules are built against OSGI Compendium version 5.0.
+
+
+=== Installation
+
+To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime
+environment:
+
+[source, listing]
+-----------------------------------------------
+# API and core
+org.apache.tamaya:tamaya-api:{tamaya_version}
+org.apache.tamaya:tamaya-core:{tamaya_version}
+org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0-alpha-1
+# injection API. SE injection module and dependencies
+org.apache.tamaya.ext:tamaya-injection-api:{tamaya_version}
+org.apache.tamaya.ext:tamaya-injection:{tamaya_version}
+org.apache.geronimo.specs:geronimo-atinject_1.0_spec:1.0
+org.apache.geronimo.specs:geronimo-el_2.2_spec:1.0.4
+org.apache.geronimo.specs:geronimo-interceptor_1.1_spec:1.0
+org.apache.geronimo.specs:geronimo-jcdi_1.1_spec:1.0
+# OSGI integration and dependencies
+org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
+org.apache.tamaya.ext:tamaya-functions:{tamaya_version}
+-----------------------------------------------
+
+
+=== Usage
+
+As an example, what is possible you can implement an OSGI service as a normal POJO and publish it as an OSGI service.
+Given that configuration can be injected very easily:
+
+[source, java]
+-----------------------------------------------
+public class HelloServiceImpl implements HelloService{
+
+ @Config("example.message")
+ @ConfigDefault("A Tamaya default.")
+ private String message;
+
+ @Override
+ public String sayHello() {
+ System.err.println("HELLO: " + message);
+ return message;
+ }
+}
+-----------------------------------------------
+
+
+=== SPI
+
+By default the OSGI pid or factory pid is mapped to a corresponding root section in Tamaya's configuration. We are
+well aware that this might not always be the desired approach. Therefore there as an SPI service provided that allows
+to determine this mapping:
+
+[source, java]
+.OSGIConfigRootMapper
+-----------------------------------------------
+public interface OSGIConfigRootMapper {
+
+ String getTamayaConfigRoot(String pid, String factoryPid);
+}
+-----------------------------------------------
+
+Registering your own implementation as an OSGI service allows you to redefine the key mapping.
+By default a configuration mapping for +pid/factoryPid==myBundle+ is mapped to +[bundle:myBundle]+.
+This mapping is used as a prefix when collecting the corresponding entries for the OSGI configuration.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_remote.adoc b/content/documentation/extensions/mod_remote.adoc
new file mode 100644
index 0000000..ce303ed
--- /dev/null
+++ b/content/documentation/extensions/mod_remote.adoc
@@ -0,0 +1,115 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Remote Configuration
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Remote Configuration (Extension Module)
+=== Overview
+
+The Tamaya remote module provides support for reading configuration from remote resources. It provides
+especially out-of-the-box support for reading scoped configuration from a configuration server as
+provided with the _Tamaya server module_ .
+
+
+=== 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-remote</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Reading Remote configuration from a Tamaya Configuration Server
+
+The remote module allows reading JSON formatted configuration as provided by the _Tamaya server extension_ . The JSON
+format used looks as follows:
+
+[source, json]
+-----------------------------------------------
+{
+ "java.vendor.url": "http://java.oracle.com/",
+ "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
+ "java.vm.info": "mixed mode",
+ "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
+ "java.vm.specification.name": "Java Virtual Machine Specification",
+ "java.vm.specification.vendor": "Oracle Corporation",
+ "java.vm.specification.version": "1.8",
+ "java.vm.vendor": "Oracle Corporation",
+ "java.vm.version": "25.45-b02",
+ "sun.arch.data.model": "64",
+ "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
+ "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
+ "sun.cpu.endian": "little",
+ "sun.cpu.isalist": "amd64",
+ "sun.desktop": "windows",
+ "sun.io.unicode.encoding": "UnicodeLittle",
+ "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
+ "sun.java.launcher": "SUN_STANDARD",
+ "sun.jnu.encoding": "Cp1252",
+ "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
+ "sun.os.patch.level": "",
+ "{meta}class": "org.apache.tamaya.functions.FilteredConfiguration",
+ "{meta}info.filter": "java.v,sun",
+ "{meta}info.format": "application/json",
+ "{meta}info.timestamp": "1441463200571",
+ "{meta}timestamp": "1441463200571",
+ "{meta}type": "Configuration"
+}
+-----------------------------------------------
+
+Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with
++{xxx}+ to identify meta-data entries, but this is not a required precondition.
+
+Finally such a remote configuration can be easily integrated by inheriting from the provided base
+class. Hereby a default ordinal must be defined and the +protected Collection<URL> getAccessURLs()+
+method must be implemented to define the URL from where the configuration should be accessible. Hereby
+multiple URLs can be provided, which are accesed in order as provided by the collection's iterator. The
+first URL that is successfully accessed determines the configuration read and imported into the
++PropertySource+.
+
+[source, java]
+-----------------------------------------------
+public class RemotePropertySource extends BaseRemotePropertySource{
+ /** Current remote property source default ordinal. */
+ private static final int REMOTE_ORDINAL = 15000;
+
+ @Override
+ public int getDefaultOrdinal(){
+ return REMOTE_ORDINAL;
+ }
+
+ @Override
+ protected Collection<URL> getAccessURLs() {
+ try {
+ String configServerUrl = System.getenv("CONFIG_SERVER");
+ if(configServerUrl==null){
+ configServerUrl = System.getProperty("configServer");
+ }
+ if(configServerUrl==null){
+ configServerUrl = "http://localhost:8888/config?scope=CLIENT&scopeId={clientId}&format=application/json";
+ }
+ System.out.println("Reading config from " + configServerUrl.replace("{clientId}", Client.getClientId()));
+ return Arrays.asList(new URL[]{new URL(configServerUrl.replace("{clientId}", Client.getClientId()))});
+ } catch (MalformedURLException e) {
+ Logger.getLogger(getClass().getName()).log(Level.WARNING, "Failed to configure remote config location,", e);
+ return Collections.emptySet();
+ }
+ }
+
+}
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_resolver.adoc b/content/documentation/extensions/mod_resolver.adoc
new file mode 100644
index 0000000..366c97e
--- /dev/null
+++ b/content/documentation/extensions/mod_resolver.adoc
@@ -0,0 +1,126 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Resolver
+
+[[Core]]
+== Tamaya Resolver (Extension Module)
+
+=== Overview
+
+Tamaya Resolver is an extension module. Refer to the
+// @todo Fix the link to the modules documentation
+link:modules.html[extensions documentation]
+for further details about modules.
+
+Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (+${...}+ placeholder
+expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents
+cycles to loop endlessly.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+To benefit from dynamic value resolution you only must add the corresponding dependency to your module:
+
+[source, xml, subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-resolver</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+The module automatically registers an according +PropertyFilter+ that is automatically called, whenever a value
+is accessed.
+
+=== Available Resolvers
+
+Currently the module defined the following resolvers:
+
+.Available Resolvers
+[cols="<.1,<.2,<.1"]
+|=======
+| _Expression_
+| _Description_
+| _Example_
+
+| +conf:<configKey>+
+| Reads another configKey and replaces the expression with the value found.
+| conf-ref=${conf:anotherConf.entryKey}
+
+| +resource:<resourceRef>+
+| Reads a resource from the current classpath and replaces the expression with the given text content.
+| cp-ref=${resource:Testresource.txt}
+
+| +file:<fileRef>+
+| Reads a resource from the current classpath and replaces the expression with the given text content.
+| file-ref=${file:c:\myFile.txt}
+
+|+url:<url>+
+|Reads an URL and replaces the expression with the given text content.
+| url-ref=${url:http://www.google.com}
+
+|=======
+
+=== SPI: Implementing your own Resolvers
+
+The module also provides an easy but powerful SPI for adding your own resolver implementations. Basically the
+first and most important thing to do is implementing the +ExpressionResolver+ interface:
+
+.Implementing a Custom Resolver
+[source, java]
+-----------------------------------------------
+public class PwdDecrypter implements ExpressionResolver {
+
+ @Override
+ public String getResolverPrefix() {
+ return "decrypt:";
+ }
+
+ @Override
+ public String evaluate(String expression) {
+ return decrypt(expression);
+ }
+
+ private String decrypt(String s) {
+ ...
+ }
+}
+-----------------------------------------------
+
+Basically that is all you must do, after having registered the class with the +ServiceLoader+ it will be found
+and loaded by the implementation. With that all expressions that start with the given prefix are passed to the
+resolver, so all the following expressions will be sent to the implementation:
+
+[source,listing]
+-----------------------------------------------
+blabla ${decrypt:myname}
+blabla ${decrypt:myname} foo blabla ${decrypt:myname}
+-----------------------------------------------
+
+Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop
+the evaluation is broken after a (configurable) number of cycles.
+
+
+Under the hood instances of +ExpressionResolver+ are managed by an implementation of the +ExpressionEvaluator+
+interface:
+
+[source, java]
+-----------------------------------------------
+public interface ExpressionEvaluator {
+ /**
+ * Evaluates the current expression.
+ * @param key the key, not null.
+ * @param value the value to be filtered/evaluated.
+ * @return the filtered/evaluated value, including null.
+ */
+ String evaluateExpression(String key, String value);
+}
+-----------------------------------------------
+
+Implementing and registering this interface gives you full control, but in most cases yhou should be fine with
+the default implementation in place.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_resources.adoc b/content/documentation/extensions/mod_resources.adoc
new file mode 100644
index 0000000..3081149
--- /dev/null
+++ b/content/documentation/extensions/mod_resources.adoc
@@ -0,0 +1,155 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Resources
+
+[[Core]]
+== Tamaya Resources (Extension Module)
+=== Overview
+
+Tamaya Resources is an extension module. Refer to the
+// @todo Fix the link to the modules page
+link:modules.html[extensions documentation] for further details
+about modules.
+
+Tamaya Resources defines some additional tools to locate resources in your classpath or file system based on descriptive
+ant-styled resource patterns. To use this module add the following dependency:
+
+[source, listing, subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <grooupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-resources</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class
+provides access to a +ResourceResolver+ instance:
+
+[source,java]
+-----------------------------------------------
+ResourceResolver resolver = ConfigResources.getResourceResolver();
+-----------------------------------------------
+
+[source,java]
+-----------------------------------------------
+public interface ResourceResolver {
+ Collection<URL> getResources(Collection<String> expressions) {...}
+ Collection<URL> getResources(String... expressions) {...}
+ Collection<URL> getResources(ClassLoader classLoader, String... expressions){...}
+ Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions);
+}
+-----------------------------------------------
+
+Hereby the methods allow to resolve expressions to a collection of URLs. In case the expression is also targeting the
+current classpath the target +ClassLoader+ to be used can be passed additionally.
+
+The default implementation provides resource resolution mechanism similar to the functionality offered by Spring.
+So by default resources can be looked up
+
+* from files
+* from the classpath
+* optionally ant-styled expressions can be used.
+
+=== Valid Expression Examples
+
+There are numerous ways how a resource pattern can be defined. Following the most important variants
+are listed:
+
+[source,listing]
+-----------------------------------------------
+// explicitly searching the file system
+file:myroot/aa?a/*.file
+file:myroot/b*/b?/*.file
+file:myroot/**/*.file
+
+// explicitly searching the classpath
+classpath:myroot/**/*.file
+classpath:javax/annotation/*.class
+classpath:javax/**/sql/*.class
+classpath:javax/annotation/**/R*.class
+classpath:javax/annotation/R?so*.class
+classpath:META-INF/maven/org.apache.geronimo.specs/**/*
+
+// search both classpath and files
+javax/annotation/*.class
+javax/**/sql/*.class
+javax/annotation/**/R*.class
+javax/annotation/R?so*.class
+META-INF/maven/org.apache.geronimo.specs/**/*
+myroot/**/*.file
+myroot/aa?a/*.file
+myroot/b*/b?/*.file
+-----------------------------------------------
+
+Summarizing the resources module provides useful functionality that helps to locate resources on the file system and
+in the classpath. This can be used to implement +PropertySourceProvider+ implementations that are based on
+corresponding resource path patterns instead of concrete files.
+
+
+=== Overall Usage Example
+
+Given the functionality we can easily implement a +PropertySourceProvider+ that reads all files from a classpath
+location, hereby traversing down all folders:
+
+
+[source, java]
+-------------------------------------------------------------
+public class PathBasedPropertySourceProvider implements PropertySourceProvider {
+
+ @Override
+ public Collection<PropertySource> getPropertySources() {
+ List<PropertySource> propertySources = new ArrayList<>();
+ Collection<URL> resources = Resources.getResourceResolver().getResources("META-INF/cfg/**/*.properties");
+ for(URL url:resources){
+ Properties props = new Properties();
+ try(InputStream is = url.openStream()){
+ props.load(is);
+ propertySources.add(new PropertiesBasedPropertySource(url.toString(), props));
+ }
+ catch(Exception e){
+ e.printStackTrace();
+ }
+ }
+
+ return propertySources;
+ }
+
+ private final static class PropertiesBasedPropertySource implements PropertySource {
+ private String name;
+ private Map<String,String> properties = new HashMap<>();
+
+ public PropertiesBasedPropertySource(String name, Properties props) {
+ this.name = name;
+ props.forEach((k,v) -> this.properties.put(k.toString(), v.toString()));
+ }
+
+ @Override
+ public String getName() {
+ return name;
+ }
+
+ @Override
+ public String get(String key) {
+ return properties.get(key);
+ }
+
+ @Override
+ public Map<String, String> getProperties() {
+ return properties;
+ }
+ }
+}
+-------------------------------------------------------------
+
+
+=== SPI
+
+The +ResourceResolver+ that is returned by the +ConfigResources+ singleton is determined by the
+current +ServiceContext+, by default you can replace the default implementation by registering an
+alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+.
+
+Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written
+on your own.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_server.adoc b/content/documentation/extensions/mod_server.adoc
new file mode 100644
index 0000000..025da45
--- /dev/null
+++ b/content/documentation/extensions/mod_server.adoc
@@ -0,0 +1,366 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Configuration Server
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Configuration Server (Extension Module)
+=== Overview
+
+The Tamaya server module provides support for providing scoped configuration using a http server serving JSON formatted
+configuration properties.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration server support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-server</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Providing configuration using the Tamaya Built-in Configuration Server
+
+THe most simple way for providing onfiguration ist to start the internal server:
+
+[source, java]
+-----------------------------------------------
+Server server = org.apache.tamaya.server.ConfigServer.createServer();
+server.start(port);
+-----------------------------------------------
+
+This will start a simple server instance that serves the following URL patterns:
+
+* +GET /config+ provides access to the full configuration tree.
+* +GET /config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated).
+ E.g. +/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_.
+
+Additionally the server module has the following options implemented, which can be passed as additional, optional
+parameters:
+
+* +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this
+ setting can be explicitly controlled by passing tis parameter explicitly. The value is the expected MIME type to be
+ returned. By default the service supports the following types (refer to the SPI section later in this document for
+ options to adapt this):
+ ** text/html
+ ** text/plain
+ ** application/xml
+ ** text/json
+
+* +scope,scopeId+ allows to use a server-side preconfigured filter/combination policy to be applied for
+ evaluating the entries to be returned. Hereby the +scopeId+ paramter allows to address a certain scope.
+ As an example think of a scope +?scope=CLIENT&scopeId=client1+ to be passed as request parameters. This
+ tells the server module to lookup a configured scope named 'CLIENT' and access a +ConfigOperator+ for the
+ given scopeId 'client1'. The returned operator then can filter and combine any kind of entries to the
+ required client configuration (for client1). Refer to the scopes section for more details.
+
+
+=== Using the Configuration Servlets
+
+Additionally to the fully built-in solution, it is also possible to integrate the Tamaya server module with a standard
+Java EE servlet container. Tamaya provides 2 servlet implementations:
+
+* the servlet +org.apache.tamaya.server.FilteredConfigServlet+ can be used to register access to configurations
+ that also support filtering of the keys. The URL looks like
+
+----------------------------------------------------------
+http(s)://HOST/SERVLET_CONTEXT/PATHS?params
+
+where
+ HOST = host name incl port, e.g. 127.0.0.2:234
+ SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
+ PATHS = A comma separated number of key paths to be filtered for being returned, e.g.
+ java,sun,client
+ params = the optional parameters (scope, scopeId and format)
+----------------------------------------------------------
+
+* the servlet +org.apache.tamaya.server.FullConfigServlet+ can be used to register access to configurations
+ that alwyas returns all items known. The URL looks like
+
+----------------------------------------------------------
+http(s)://HOST/SERVLET_CONTEXT?params
+
+where
+ HOST = host name incl port, e.g. 127.0.0.2:234
+ SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
+ params = the optional parameters (scope, scopeId and format)
+----------------------------------------------------------
+
+==== Formatting used by Default
+
+The server module formats the configuration returned by default in thw following variants:
+
+.Formatting for +text/json+
+
+[source, json]
+-----------------------------------------------
+{
+ "java.vendor.url": "http://java.oracle.com/",
+ "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
+ "java.vm.info": "mixed mode",
+ "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
+ "java.vm.specification.name": "Java Virtual Machine Specification",
+ "java.vm.specification.vendor": "Oracle Corporation",
+ "java.vm.specification.version": "1.8",
+ "java.vm.vendor": "Oracle Corporation",
+ "java.vm.version": "25.45-b02",
+ "sun.arch.data.model": "64",
+ "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
+ "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
+ "sun.cpu.endian": "little",
+ "sun.cpu.isalist": "amd64",
+ "sun.desktop": "windows",
+ "sun.io.unicode.encoding": "UnicodeLittle",
+ "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
+ "sun.java.launcher": "SUN_STANDARD",
+ "sun.jnu.encoding": "Cp1252",
+ "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
+ "sun.os.patch.level": "",
+ "{meta}class": "org.apache.tamaya.functions.FilteredConfiguration",
+ "{meta}info.filter": "java.v,sun",
+ "{meta}info.format": "application/json",
+ "{meta}info.timestamp": "1441463200571",
+ "{meta}timestamp": "1441463200571",
+ "{meta}type": "Configuration"
+}
+-----------------------------------------------
+
+
+.Formatting for +application/xml+
+
+[source, xml]
+-----------------------------------------------
+<configuration>
+ <entry key="java.vendor.url">http://java.oracle.com/</entry>
+ <entry key="java.vendor.url.bug">http://bugreport.sun.com/bugreport/</entry>
+ <entry key="java.vm.info">mixed mode</entry>
+ <entry key="java.vm.name">Java HotSpot(TM) 64-Bit Server VM</entry>
+ <entry key="java.vm.specification.name">Java Virtual Machine Specification</entry>
+ <entry key="java.vm.specification.vendor">Oracle Corporation</entry>
+ <entry key="java.vm.specification.version">1.8</entry>
+ <entry key="java.vm.vendor">Oracle Corporation</entry>
+ <entry key="java.vm.version">25.45-b02</entry>
+ <entry key="sun.arch.data.model">64</entry>
+ <entry key="sun.boot.class.path">C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes</entry>
+ <entry key="sun.boot.library.path">C:\apps\jdk18\jre\bin</entry>
+ <entry key="sun.cpu.endian">little</entry>
+ <entry key="sun.cpu.isalist">amd64</entry>
+ <entry key="sun.desktop">windows</entry>
+ <entry key="sun.io.unicode.encoding">UnicodeLittle</entry>
+ <entry key="sun.java.command">com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start</entry>
+ <entry key="sun.java.launcher">SUN_STANDARD</entry>
+ <entry key="sun.jnu.encoding">Cp1252</entry>
+ <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry>
+ <entry key="sun.os.patch.level"></entry>
+ <entry key="{meta}class">org.apache.tamaya.functions.FilteredConfiguration</entry>
+ <entry key="{meta}info.filter">java.v,sun</entry>
+ <entry key="{meta}info.format">application/xml</entry>
+ <entry key="{meta}info.timestamp">1441463383687</entry>
+ <entry key="{meta}timestamp">1441463383687</entry>
+ <entry key="{meta}type">Configuration</entry>
+</configuration>
+-----------------------------------------------
+
+
+.Formatting for +text/plain+
+
+[source, text]
+-----------------------------------------------
+
+Configuration:
+ java.vendor.url: http://java.oracle.com/,
+ java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
+ java.vm.info: mixed mode,
+ java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
+ java.vm.specification.name: Java Virtual Machine Specification,
+ java.vm.specification.vendor: Oracle Corporation,
+ java.vm.specification.version: 1.8,
+ java.vm.vendor: Oracle Corporation,
+ java.vm.version: 25.45-b02,
+ sun.arch.data.model: 64,
+ sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
+ sun.boot.library.path: C:\apps\jdk18\jre\bin,
+ sun.cpu.endian: little,
+ sun.cpu.isalist: amd64,
+ sun.desktop: windows,
+ sun.io.unicode.encoding: UnicodeLittle,
+ sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
+ sun.java.launcher: SUN_STANDARD,
+ sun.jnu.encoding: Cp1252,
+ sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
+ sun.os.patch.level: ,
+ {meta}class: org.apache.tamaya.functions.FilteredConfiguration,
+ {meta}info.filter: java.v,sun,
+ {meta}info.format: text/plain,
+ {meta}info.timestamp: 1441463082020,
+ {meta}timestamp: 1441463082021,
+ {meta}type: Configuration
+-----------------------------------------------
+
+
+.Formatting for +application/html+
+
+[source, html]
+-----------------------------------------------
+<html>
+<head><title>System Configuration</title></head>
+<body>
+<h1>Sysem Configuration</h1>
+<p>This view shows the system configuration of devbox-win at Sat Sep 05 16:30:59 CEST 2015.</p><pre>
+Configuration:
+ java.vendor.url: http://java.oracle.com/,
+ java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
+ java.vm.info: mixed mode,
+ java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
+ java.vm.specification.name: Java Virtual Machine Specification,
+ java.vm.specification.vendor: Oracle Corporation,
+ java.vm.specification.version: 1.8,
+ java.vm.vendor: Oracle Corporation,
+ java.vm.version: 25.45-b02,
+ sun.arch.data.model: 64,
+ sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
+ sun.boot.library.path: C:\apps\jdk18\jre\bin,
+ sun.cpu.endian: little,
+ sun.cpu.isalist: amd64,
+ sun.desktop: windows,
+ sun.io.unicode.encoding: UnicodeLittle,
+ sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
+ sun.java.launcher: SUN_STANDARD,
+ sun.jnu.encoding: Cp1252,
+ sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
+ sun.os.patch.level: ,
+ {meta}class: org.apache.tamaya.functions.FilteredConfiguration,
+ {meta}info.filter: java.v,sun,
+ {meta}info.format: text/html,
+ {meta}info.timestamp: 1441463459653,
+ {meta}timestamp: 1441463459654,
+ {meta}type: Configuration
+
+</pre>
+</body>
+</html>
+-----------------------------------------------
+
+=== SPI
+
+==== Scopes
+
+As mentioned earlier in this document scopes can be used to define the exact configuration tree to be returned, e.g.
+as a result of combining multiple sub trees. Following an example of the code to be written to return a configuration
+that combines common client default entries with client specific entries:
+
+[source, java]
+-----------------------------------------------
+public class ClientScopeProvider implements ScopeProvider{
+
+ /**
+ * Access the unique scope name.
+ * @return the unique scope name.
+ */
+ public String getScopeType(){
+ return "CLIENT";
+ }
+
+ @Override
+ public ConfigOperator getScope(String scopeId) {
+ return c ->
+ ConfigurationFunctions.combine("Scoped Config CLIENT="+scopeId,
+ c.with(ConfigurationFunctions.sectionRecursive(true, "client.default")),
+ c.with(ConfigurationFunctions.sectionRecursive(true, "client." + scopeId))
+ );
+ }
+}
+-----------------------------------------------
+
+This class can be registered using the +ServiceContext+ in place. By default the +ServiceLoader+ is used, so you will
+have to add the following to +META-INF/services/org.apache.tamaya.server.spi.ScopeProvider+:
+
+[source, listing]
+-----------------------------------------------
+my.full.packagename.ClientScopeProvider
+-----------------------------------------------
+
+==== Adapting the Way Configuration is Derived
+
+Finally the effective readong and configuration handling logic can also be replaced or improved. This can be
+done by registering your own implementation of the interface +ConfigProviderService+:
+
+[source, java]
+------------------------------------------------
+public interface ConfigProviderService {
+ String getConfigurationWithPath(String path, String format, String scope, String scopeId, HttpServletRequest request);
+ String getConfiguration(String format, String scope, String scopeId, HttpServletRequest request);
+ void updateConfiguration(String payload, HttpServletRequest request);
+ void deleteConfiguration(String paths, HttpServletRequest request);
+}
+------------------------------------------------
+
+By default the +ServiceContextManager+ uses the +java.util.ServiceLoader+ for component loading, so to replace the
+default server code you must register a higher +@Priority+ implementation.
+
+
+==== Replacing the Built-In Server
+
+We have seen earlier that starting a configuration server is pretty easy:
+
+[source, java]
+-----------------------------------------------
+Server server = org.apache.tamaya.server.ConfigServer.createServer();
+server.start(port);
+-----------------------------------------------
+
+Nevertheless one may want to replace the used implementation of +Server+. This can be done easily by simply
+registering an overriding implementation if the corresponding interface:
+
+[source, java]
+-----------------------------------------------
+public interface Server {
+ void start(int port);
+ boolean isStarted();
+ void stop();
+ void destroy();
+}
+-----------------------------------------------
+
+==== The ScopeManager Singleton
+
+Finally whe implementing your own server, you might also benefit from the +ScopeManager+ singleton. Basically this
+class loads all registered +ScopeProvider+ and manages the configured scope instances:
+
+[source, java]
+-----------------------------------------------
+public final class ScopeManager {
+ ...
+
+ private ScopeManager(){}
+
+ /**
+ * Get the scope given its name.
+ * @param scopeId the scope name
+ * @return the scope matching
+ * @throws ConfigException, if nos such scope is defined.
+ */
+ public static ConfigOperator getScope(String scopeId, String target);
+
+ /**
+ * Get the defined scope names.
+ * @return the defined scope names, never null.
+ */
+ public static Set<String> getScopes();
+
+}
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_spi-support.adoc b/content/documentation/extensions/mod_spi-support.adoc
new file mode 100644
index 0000000..7aca208
--- /dev/null
+++ b/content/documentation/extensions/mod_spi-support.adoc
@@ -0,0 +1,57 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+
+toc::[]
+
+
+[[SPISupport]]
+== Tamaya SPI Support (Extension Module)
+=== Overview
+
+The Tamaya SPI support module provides a few helpful base classes that can be used to implement some of the often
+used SPI parts in Tamaya:
+
+* +BasePropertySource+ provides an abstract base class for implementation of your own PropertySources.
+* +DefaultConfiguration+ provides you with a simple implementation of the +Configuration+ interface based on a
+ +ConfigurationContext+ provided. This is also very useful for mocking configuration during test execution, but
+ not only constraint to that use case.
+* +DefaultConfigurationContext+ provides you with a working implementation of the +ConfigurationContext+.
+* +EnumConverter+ is a converter implementation that can automatically select the currect enumeration values based
+ on a configured entry.
+* +MapPropertySource+ implements a static property source based on +java.util.Map+.
+* +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations (also handling the
+ case, where no such annotation is present).
+* +PropertiesResourcePropertySource+ is an implementation of a +PropertySource+ based on a +Properties+ instance,
+ lodable from any +URL+.
++ +PropertyConverterManager+ is a service class very useful, when implementing instances of +ConfigurationContext+.
+ It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic.
++ +PropertyFiltering+ provides another helpful class that manages +PropertyFilter+ instances and provides an
+ easy to use high level API.
++ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+
+ values and their class names.
+
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-spisupport</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+The component will not register any components but only providing portable base classes for some common SPI
+implementation tasks. It only depends on the API, so it should be safely reusable also with other implementations
+of the Tamaya API similarly.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_spring.adoc b/content/documentation/extensions/mod_spring.adoc
new file mode 100644
index 0000000..3960dc1
--- /dev/null
+++ b/content/documentation/extensions/mod_spring.adoc
@@ -0,0 +1,134 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Spring Integration
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Spring Integration (Extension Module)
+=== Overview
+
+Apache Tamaya currently provides two implementations also full integration for Spring:
+
+* A Spring +@Configuration+ implementation that also provides a Tamaya based version of
+ +org.springframework.context.support.PropertySourcesPlaceholderConfigurer+.
+* +org.apache.tamaya.integration.spring.TamayaEnvironment+ is the Tamaya based implementation of the Spring
+ +Environment+ interface.
+* +TamayaSpringPropertySource+ implements an additional Spring +PropertySource+.
+* Finally +org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor+ implements a Bean +PostProcessor+,
+ which adds all the full fledged Tamaya configuration capabilities to Spring.
+
+
+=== Compatibility
+
+Both modules are based on Java 7, so they will run on Java 7 and beyond. The extension shown here works similarly
+with Spring Framework as well as Spring Boot.
+
+
+=== Installation
+
+To benefit from Tamaya Spring integration you only must one of the following dependencies to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-spring</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Registering Tamaya Spring Configuration
+
+Basically to activate the Tamaya Spring support the most simple thing is to a enable the Tamaya package for being
+scanned for Spring components, e.g.
+
+[source, xml]
+--------------------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:context="http://www.springframework.org/schema/context"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
+
+ <context:annotation-config />
+ <context:component-scan base-package="org.apache.tamaya.integration.spring"/>
+
+ ...
+
+</beans>
+--------------------------------------------------------
+
+NOTE: Of course you can also use the newer +@ComponentScan+ annotation as described by the Spring documentation.
+
+
+Similarly if you dont want to use component scanning you can configure things using plain old XML. Simply add the
+following lines somewhere into one of your application context configuration files.
+
+[source, xml]
+--------------------------------------------------------
+<bean id="tamayaInjectionProcessor" name="tamayaInjectionProcessor" class="org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor"/>
+<bean id="tamayaConfigProvider" name="tamayaConfigProvider" class="org.apache.tamaya.integration.spring.TamayaSpringConfig"/>
+--------------------------------------------------------
+
+=== Configuring your Context
+
+Done so enables you to use Tamaya as a backend for property resolution, e.g. +propertyValue+ as illustrated below
+is resolved from the current Tamaya configuration.
+
+[source, xml]
+--------------------------------------------------------
+<bean id="configuredBean" name="configuredBean" class="org.apache.tamaya.integration.spring.ConfiguredSpringBean">
+ <property name="message" value="${propertyValue}"/>
+</bean>
+--------------------------------------------------------
+
+=== Configuring your Beans
+
+Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans:
+
+[source, java]
+--------------------------------------------------------
+**
+ * Created by Anatole on 25.09.2015.
+ */
+@ConfigDefaultSections
+public class ConfiguredSpringBean {
+
+ private String message;
+
+ @Autowired
+ private Environment env;
+
+ @Config("java.version")
+ private String javaVersion;
+
+ @Config
+ @ConfigDefault("23")
+ private int testNumber;
+
+ public String getJavaVersion(){
+ return javaVersion;
+ }
+
+ public int getTestNumber(){
+ return testNumber;
+ }
+
+ public Environment getEnv(){
+ return env;
+ }
+
+ public void setMessage(String message){
+ this.message = message;
+ }
+
+ public String getMessage() {
+ return message;
+ }
+}
+--------------------------------------------------------
+
+Summarizing you get all the nice features of Tamaya out of the box running with your Spring code.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_yaml.adoc b/content/documentation/extensions/mod_yaml.adoc
new file mode 100644
index 0000000..b7e53cb
--- /dev/null
+++ b/content/documentation/extensions/mod_yaml.adoc
@@ -0,0 +1,112 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Builder
+
+toc::[]
+
+
+[[BuilderCore]]
+== Tamaya YAML (Extension Module)
+=== Overview
+
+The Tamaya YAML module provides support for reading configuration using the YAML format (yaml.org). YAML hereby
+use intendation for expressing hierarchy, which makes yaml configuration files very easily readable and compact.
+
+
+=== Compatibility
+
+The YAML module is based on Java 7, so it will 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-yaml</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+This extension also transitively requires the +tamaya.formats+ module.
+
+=== Reading configuration in YAML
+
+For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided:
+
+[source, java]
+-----------------------------------------------
+ConfigurationData dataRead = ConfigurationFormats.readConfig(
+ getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat()));
+-----------------------------------------------
+
+=== Examples
+
+The YAML module adds instances of +ConfigurationFormat+ so YAML configuration can be read and mapped to the
+according property values. E.g. the following file is a simple and correct YAML configuration:
+
+[source,yaml]
+----------------------------------------------------------------
+invoice: 34843
+date : 2001-01-23
+bill-to: &id001
+ given : Chris
+ family : Dumars
+ address:
+ lines: |
+ 458 Walkman Dr.
+ Suite #292
+ city : Royal Oak
+ state : MI
+ postal : 48046
+ship-to: *id001
+product:
+ - sku : BL394D
+ quantity : 4
+ description : Basketball
+ price : 450.00
+ - sku : BL4438H
+ quantity : 1
+ description : Super Hoop
+ price : 2392.00
+tax : 251.42
+total: 4443.52
+comments:
+ Late afternoon is best.
+ Backup contact is Nancy
+ Billsmer @ 338-4338.
+----------------------------------------------------------------
+
+Hereby the above file, by default is mapped as follows into +Map<String,String>+ typed properties:
+
+[source,listing]
+----------------------------------------------------------------
+invoice -> 34843
+date -> Tue Jan 23 01:00:00 CET 2001
+bill-to.family -> Dumars
+bill-to.given -> Chris
+bill-to.address.state -> MI
+bill-to.address.postal -> 48046
+bill-to.address.city -> Royal Oak
+bill-to.address.lines -> 458 Walkman Dr.
+Suite #292
+
+ship-to.given -> Chris
+ship-to.address.state -> MI
+ship-to.family -> Dumars
+ship-to.address.postal -> 48046
+ship-to.address.city -> Royal Oak
+ship-to.address.lines -> 458 Walkman Dr.
+Suite #292
+
+product -> {sku=BL394D, quantity=4, description=Basketball, price=450.0},{sku=BL4438H, quantity=1, description=Super Hoop, price=2392.0}
+_product.collection-type -> List
+
+tax -> 251.42
+total -> 4443.52
+comments -> Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/quickstart.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/quickstart.adoc b/content/documentation/quickstart.adoc
new file mode 100644
index 0000000..14ab438
--- /dev/null
+++ b/content/documentation/quickstart.adoc
@@ -0,0 +1,189 @@
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Quickstart
+
+
+The fastest way to start with Tamaya is just using the _Core_ implementation,
+implementing the **API** in small, minimalistic way. For that add the following
+Maven dependency to your project:
+
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>{tamaya_mvn_group_id}</groupId>
+ <artifactId>tamaya-core</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+----
+
+Given that you can add your configuration properties to the following locations in your classpath:
+
+[source]
+----
+META-INF/javaconfiguration.properties
+----
+
+Additionally also system properties are taken into account, hereby overriding the default properties. Overall
+Tamaya by default defines the following configuration model per default (most significant first):
+
+. System Properties
+. `META-INF/javaconfiguration.properties`
+
+There many modules that extend the capabilities of Tamaya.
+These modules doe not depend on core, so alternative
+implementations of the Tamaya API should work similarly.
+
+
+=== Multiple configuration files
+
+By default you can provide multiple `javaconfig.properties` files, e.g. as part
+of multiple jars loaded into your system. The system internally creates one
+`PropertySource` for each file found on the classpath. All `PropertySource`
+instances created are ordered by their ordinal value (an int).
+
+Tamaya Core defines the following default ordinals (used, if no custom ordinal is defined):
+
+[width=70]
+[cols="3,1", option="headers"]
+|===
+| Source | Ordinal
+| System Properties | 400
+| Environment Variables | 300
+| Java Configuration Properties | 100
+|===
+
+That means that the value of a configuration variable `x` overhanded via `-Dx=yes` has
+a higher precedence then the entry for configuration variable `x` specified in a `javaconfig.properties`
+as `x=no`.
+
+These ordinal values can be either hardcoded, or be dynamically
+configurable as key within each configuration resource. The ladder can be done by defining a special
+Tamaya ordinal value as follows:
+
+
+[source]
+----
+# override default Tamaya ordinal for property files
+tamaya.ordinal=123
+----
+
+This assigns an ordinal of 123 to each entry in that configuration resource.
+
+=== Using additional features of Tamaya
+
+There many modules that extend the capabilities of
+Tamaya. These modules doe not depend on core, so alternative
+implementations of the Tamaya API should work similarly. Following a
+small extract of most important modules available (or available soon):
+
+==== Dynamic Resolution and Value Placeholders
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <artifactId>org.apache.tamaya.ext</id>
+ <artifactId>tamaya-resolver</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+----
+
+// @todo Auf Modulliste verweisen f�r vollst�ndigen �berblick
+With that it is possible to define values with Unix styled placeholders that are
+resolved on configuration access, e.g.
+`mykey=my${dynamicValue}�. For further details refer to the module documentation.
+This module also provides a `Resolver` singleton:
+
+[source,java]
+----
+String myExpression = ...;
+String resolved = Resolver.evaluateExpression(myExpression);
+----
+
+
+==== Ant-styled Path Resolution of Resources
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <artifactId>org.apache.tamaya.ext</id>
+ <artifactId>tamaya-resolution</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+----
+
+This module provides a `Resolver` singleton that allows to
+resolve configuration resources using a ant-styled resource
+description, e.g.
+
+
+[source,xml,subs="verbatim,attributes"]
+----
+Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties");
+----
+
+For further details refer to the module documentation.
+
+
+==== Configuration Injection
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <artifactId>org.apache.tamaya.ext</id>
+ <artifactId>tamaya-inject</artifactId>
+ <version>{tamaya_version_development}</version>
+</dependency>
+----
+
+With this extension you can let Tamaya inject configuration into instances of
+annotated classes or let Tamaya implement a configuration template.
+
+Corresponding configuration:
+
+[source,xml,subs="verbatim,attributes"]
+----
+public class MyType {
+ @ConfiguredProperty("name")
+ private String typeName;
+
+ public String getName() {
+ return name;
+ }
+}
+
+MyType type = new MyType();
+ConfigurationInjector.configure(type);
+----
+
+Or the same as template:
+
+[source,xml,subs="verbatim,attributes"]
+----
+public interface MyTypeTemplate {
+ @ConfiguredProperty("name")
+ public String getName();
+}
+
+MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class);
+----
+
+Currently the following resolvers are available:
+
+[width="60"]
+[cols="1,4"]
+|===
+| Conf
+| Cross-reference to another configuration entry
+
+| URL
+| Referencing a resource addressable by an URL.
+
+| File
+| Reference to a file, replacing the expression with the file's text value.
+
+| Resource
+| Reference to classpath resource, replacing the expression with the resource's text value.
+
+|===