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:45 UTC
[01/10] incubator-tamaya-site git commit: TAMAYA-178: Fix subscribe
via RSS feed.
Repository: incubator-tamaya-site
Updated Branches:
refs/heads/master e3761ad07 -> 197fbb15e
TAMAYA-178: Fix subscribe via RSS feed.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/e2de92dd
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/e2de92dd
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/e2de92dd
Branch: refs/heads/master
Commit: e2de92dd56cae050d34a476d8194cdbc338a24d6
Parents: e3761ad
Author: Phil Ottlinger <po...@apache.org>
Authored: Sun Dec 18 23:26:02 2016 +0100
Committer: Phil Ottlinger <po...@apache.org>
Committed: Sun Dec 18 23:26:02 2016 +0100
----------------------------------------------------------------------
templates/feed.thyme | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/e2de92dd/templates/feed.thyme
----------------------------------------------------------------------
diff --git a/templates/feed.thyme b/templates/feed.thyme
index 0b12abb..5ace3d4 100644
--- a/templates/feed.thyme
+++ b/templates/feed.thyme
@@ -2,20 +2,19 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:th="http://www.thymeleaf.org">
<channel>
<title>Apache Incubator Tamaya</title>
- <link th:text='${config.site_host}'>link</link>
+ <link th:text='${config.site_host}'>
<atom:link th:href='${config.site_host+"/feed.xml"}' href="link" rel="self" type="application/rss+xml" />
- <description>JBake Bootstrap Template</description>
+ <description>Apache Tamaya RSS feed template</description>
<language>en-gb</language>
<pubDate th:text='${#dates.format(published_date,"EEE, d MMM yyyy HH:mm:ss Z")}'>pubdate</pubDate>
<lastBuildDate th:text='${#dates.format(published_date,"EEE, d MMM yyyy HH:mm:ss Z")}'>lastbuilddate</lastBuildDate>
<item th:each="post: ${published_posts}">
<title th:text='${post.title}'>title</title>
- <link th:text='${config.site_host+"/"+post.uri}'>link</link>
+ <link th:text='${config.site_host+"/"+post.uri}'>
<pubDate th:text='${#dates.format(post.date,"EEE, d MMM yyyy HH:mm:ss Z")}'>pubdate</pubDate>
<guid th:text='${post.uri}' isPermaLink="false">guid</guid>
<description th:text='${#strings.escapeXml(post.body)}'>description</description>
</item>
-
</channel>
</rss>
[10/10] incubator-tamaya-site git commit: TAMAYA-178: Add release
submenu
Posted by po...@apache.org.
TAMAYA-178: Add release submenu
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/197fbb15
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/197fbb15
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/197fbb15
Branch: refs/heads/master
Commit: 197fbb15efbbe7b18cf8ad3c28111acce83a6c01
Parents: ede865e
Author: Phil Ottlinger <po...@apache.org>
Authored: Sun Dec 18 23:34:15 2016 +0100
Committer: Phil Ottlinger <po...@apache.org>
Committed: Sun Dec 18 23:34:15 2016 +0100
----------------------------------------------------------------------
templates/menu.thyme | 7 +++++++
1 file changed, 7 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/197fbb15/templates/menu.thyme
----------------------------------------------------------------------
diff --git a/templates/menu.thyme b/templates/menu.thyme
index eea628e..e9398f1 100644
--- a/templates/menu.thyme
+++ b/templates/menu.thyme
@@ -41,6 +41,13 @@
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'release-guide.html'">Release Guide</a></li>
</ul>
</li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Releases <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'download.html'">Download</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'history.html'">Release History</a></li>
+ </ul>
+ </li>
<!-- Example:
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a>
[05/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/usecases.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/usecases.adoc b/content/documentation/usecases.adoc
new file mode 100644
index 0000000..0d0d4e0
--- /dev/null
+++ b/content/documentation/usecases.adoc
@@ -0,0 +1,488 @@
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Use Cases and Requirements
+
+toc::[]
+
+== Use Cases
+
+=== Simple Access
+
+Users want to be able to access configuration in a unified way both in SE and EE. EE may provide additional
+mechanism, such as injection, but the SE mechanisms should work as well, so any code written in SE is fully
+portable to EE as well.
+This can only be achieved by providing a static accessor, e.g.
+
+[source,java]
+------------------------------------------------------------
+Configuration config = Configuration.current();
+------------------------------------------------------------
+
+The call above should work exactly the same in EE. To enable this the static call must be delegated in the
+internals of the singleton, depending on the runtime. In EE the executing component can behave contextually,
+or even be loaded within the CDI environment (at least for post loading, application runtime aspects, but not earlier).
+
+Additionally in EE it should also be possible to inject Configuration, which gives you the same results as the call
+above:
+
+[source,java]
+------------------------------------------------------------
+@Inject
+private Configuration cfg;
+------------------------------------------------------------
+
+
+=== Simple Lookup of Properties
+
+Users just want to create a configuration ad hoc, from given property files. The
+files could be locally in the file system, on the classpath.
+
+Tamaya should provide a simple Java API for accessing key/value based configuration. Hereby users want to access
+properties as simple String values.
+
+Hereby returning Java 8 Optional values must be considered as well, instead of returning +null+.
+
+
+=== Value Placeholders
+
+Users just want to to be able to add placeholders to the values of configuration (not the keys). The mechanisms for
+resolving the placeholders hereby should be not constraint to one single lanmguage like EL. Instead of different
+replacement strategies should be selectable, e.g. by prefixing an expression with the name of the resolver that
+should do the work (eg +"blabla ${env:HOME} using Java version ${sys:java.version}."+.
+This allows resolution mechanism to be isolated easily and also allows to use simpler mechanisms, if no more complex
+ones like EL are required. This is especially useful to deal with low resource environment like ME.
+
+
+=== Type Safe Properties
+
+Users just want to access properties not only as Strings, but let Tamaya do the conversion to the required
+or the configred target type. By defauklt all java.ui.lang wrapper and primitive types should be supported, but also
+other common types like date/time types, math numeric types and more.
+
+It must be possible that users can register their own custom types.
+
+Finally users also want to be able to dynamically provide or override type adaption (conversion), when reading a value,
+for a certain key/value pair.
+
+
+=== Configuration Templates
+
+Users want to be able to let Tamaya implement an interface template based on configuration.
+This use case is pretty similar to the injection use case. Basically the values are not injected,
+but cached within the template proxy returned, e.g. as +DynamicValue+.
+Similarly it could even be possible to define callback methods (default methods)
+or register listeners to DynamicValue instances returned.
+
+Templates hereby can easily be managed, but provide a excellent mechanism to provide type-safe configuration
+to clients in a very transparent way. Details can be controlled by using the same annotations as for
+normal configuration injection.
+
+
+=== Java 8 Functional Support
+
+Users want to be able to benefit from the new programming styles introduced with Java 8. Configuration
+should provide extension points for different aspects, where additional code can be hooked in easily.
+In short: were possible functional interfaces should be modelled.
+
+Examples:
+
+* code that converts a configuration to another kind of configuration: +UnaryOperator<Configuration>+
+* code that creates any kind of result based on a configuration: +Function<Configuration,T>+
+* Adapters for type conversion are defined as +Function<String,T>+
+* Key, value filters ccan be modelled as +BiFunction<String,String,String>+
+* etc.
+
+
+=== Configuration Locations
+
+Users want to be able to
+
+* read configuration from different locations.
+* By default classpath and file resources are
+ supported. But similarly remote access using a JSON ReST call should be possible.
+* Tamaya should define a JSON and XML format for configuration.
+* Configuration locations should be scannable using ant-styled resource patterns, if possible.
+* Scanning and reading logic can be modularized by using a +ConfigReader+ interface.
+
+
+=== Configuration Formats
+
+Users want to be able to use the format they prefer.
+
+* properties, xml-properties and ini-format should be supported by default
+* Other/custom formats should be easily addable by registering or providing the format on configuration evaluation (read).
+* When possible Tamaya should figure out which format to be used and how the InputStream should be correctly
+ interpreted.
+
+
+=== Multiple Configurations
+
+When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional
+aspects to be considered by a configuration system.
+
+* Different code modules, libraries, plugins or products want to have their "own" separated configuration.
+* Similar it should be possible to add fully specific additional configurations.
+
+The default configuration hereby should always be present, whereas additional configurations are optional.
+Users want to be able to check the availability of such an additional configuration.
+
+Of course, additional configuration must be identifiable. The best way to do is to be discussed, nevertheless the
+mechanism must not depend on Java EE and the identifying keys must be serializable easily.
+Basically simple names are sufficient and woukld provide exact this required functionality.
+
+
+=== External Configuration
+
+Users want to be able to replace, override, extend or adapt any parts or all of an existing configuration from
+external sources.
+This also must be the case for multi-context environments, where the context identifiers are
+the only way to link to the correct remote configuration.
+
+
+=== Context Dependent Configuration
+
+In multi tenancy setups or complex systems a hierarchical/graph model of contexts for configurations is required, or different runtime contexts are executed in parallel
+within the same VN. What sounds normal for EE also may be the case for pure SE environments:
+
+* Users want to be able to model different layers of runtime context
+* Users want to identify the current layer, so configuration used may be adapted.
+
+
+
+=== Dynamic Provisioning (UC8)
+
+In Cloud Computing, especially the PaaS and SaaS areas a typical use case would be that an application (or server)
+is deployed, configured and started dynamically. Typically things are controlled by some "active controller components",
+which are capable of
+
+* creating new nodes (using IaaS services)
+* deploying and starting the required runtime platform , e.g. as part of a PaaS solution.
+* deploying and starting the application modules.
+
+All these steps require some kind of configuration. As of today required files are often created on the target node
+before the systems are started, using proprietary formats and mechanism. Similarly accessing the configuration in place
+may require examining the file system or using again proprietary management functions. Of course, a configuration
+solution should not try to solve that, but it can provide a significant bunch of functionality useful in such scenarios:
+
+* provide remote capabilities for configuration
+* allow configuration to be updated remotely.
+* allow client code to listen for configuration changes and react as needed.
+
+
+=== Minimal Property Source SPI
+
+Users expect that implementing an additional configuration property source is as easy as possible.
+So there should be an SPI defined that allows any kind of data source to be used for providing configuration data.
+The interface to be implemented is expected to be minimal to reduce the implementation burden. Default
+methods should be used where possible, so only a few methods are expected to be required to implement.
+
+
+=== Scannable Properties
+
+If possible configuration should be scannable, meaning it should be possible to evaluate the keys available.
+The corresponding capabilities should be accessible by a +isScannable()+ method.
+
+
+=== Combine Configurations
+
+Users want to be able to combine different configurations to a new configuration instance.
+Hereby the resulting configuration can be
+
+* a union of both, ignoring duplicates (and optionally log them)
+* a union of both, duplicates are ignored
+* a union of both, conflicts are thrown as ConfigException
+* an intersection of both, containing only keys present and equal in both configurations
+* an arbitrary mapping or filter, modelled by an +CombinationPolicy+, which basically can be modelled
+ as +BiFunction<String, String, String>+, hereby
+ ** a result of +null+ will remove the key
+ ** any other result will use the value returned as final value of the combination.
+
+
+=== MX/ReST Management
+
+Users want to be have comprehensive management support, which should allow
+
+* to change configuration
+* to remove configuration
+* to view configuration and its provider details
+
+
+=== Adaptable Service Context
+
+Tamaya should support an adaptable +ServiceContext+ to resolve any kind of implememntation services, both API services as core
+framework services. The +ServiceContext+ should be dynamically replecable by configuring an alternate instance of
+using the Java *ServiceContet+.
+
+This decouples component usage from its load and management part and als greatly simplifies integration with
+new/alternate runtime environments.
+The service context is exptected to provide
+
+* single singleton instances: these service can be cached.
+* access to multiple instances which implement some commons SPI interface.
+* as useful priorization of components is done by the model itself.
+
+
+=== Configuration Injection
+
+Users want to be able to polulate configured items by injecting configured values. Hereby
+
+* the lifecycle of the instances is not managed by Tamaya
+* all references to items configured are managed as weak references, to prevent memoryleaks.
+* Injection should if possible evaluate the properties by defaults. Even properties without
+ any annotations are possible.
+* Users expect to exclude certain properties from calculation
+* Beside injection of properties it is also possible to call setter methods with one parameter similarly.
+* Basically injection is performed, when the instance is passed to the Tamaya configuration system. It should also
+ be possible to inject/provide final values, especially Strings. Changes on configured values should be
+ reflected in the current value. Setters methods similarly can be called again, with the new values, on changes.
+* Users expect to control dynamic values and recall of setter methods, basically the following strategies should be
+ supported:
+ ** inject only once and ignore further changes.
+ ** reinject/reinitialize on each change
+
+* Dynamic Values can easily be modeled as +ConfiguredValue+ instances, which should have the following functionality:
+ ** access the current value
+ ** access the new value
+ ** access the latest value access time in ms
+ ** access the latest value update time in ms
+ ** evaluate easily if the value has changed since the last access
+ ** accept the change
+ *** as a shortcut it should be possible to accept the change on access of the value implicitly, hereby always accessing
+ the latest valid value.
+ ** ignore the change
+ ** register +Consumer<DynamicValue>+ liasteners to listen on the changes (ans also removing them later again).
+
+All observing functionality can be done completely asynchronously and in parallel.
+
+
+[[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-site/blob/ede865e4/content/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/extensions.adoc b/content/extensions.adoc
deleted file mode 100644
index a95f22f..0000000
--- a/content/extensions.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-== Apache Tamaya: Extension Modules
-
-toc::[]
-
-=== Mature Extensions
-
-Mature extensions have a stable API and SPI, similar to the API and Implementations provided.
-
-[width="100%",frame="1",options="header",grid="all"]
-|=======
-|_Artifact_ |_Description_ |_Links_
-| | N/A: currently no extensions have reached that maturity level. | -
-|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. | link:extensions/mod_filter.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-injection-cdi-se+ | Java EE/standalone compliant CDI integration using Tamaya SE injection mechanism. | link:extensions/mod_cdi.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation]
-|=======
-
-
-=== Extensions Sandbox
-
-Extensions in _draft state_ rather experimental or not yet very mature. API changes may occurr at any time
-and the may also have severe issues. So use at your own risk or join and help us getting them stable and
-well tested!
-
-NOTE: All extensions currently run on Java 7 as well as on Java 8.
-
-[width="100%",frame="1",options="header",grid="all"]
-|=======
-|_Artifact_ |_Description_ |_Links_
-|+org.apache.tamaya.ext:tamaya-commons+ |Combines Tamaya's Format Abstraction with Apache Commons. | -
-|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-metamodel+ |Provides support defining configuration using XML based meta-configuration. |link:extensions/mod_metamodel.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-validation+ |Provides support for XML based meta-configuration allowing to validate configuration read. |link:extensions/mod_validation.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-usagetracker+ |Provides support tracking of configuration usage and the consumer locations consuming configuration. |link:extensions/mod_usagetracker.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-consul+ | Integration with consul clusters. | link:extensions/mod_consul.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-etcd+ | Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-configured-sysprops+ | Allows Tamaya to integrate with +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-ui+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation]
-|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_builder.adoc b/content/extensions/mod_builder.adoc
deleted file mode 100644
index a589374..0000000
--- a/content/extensions/mod_builder.adoc
+++ /dev/null
@@ -1,83 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Builder
-
-[[BuilderCore]]
-== Tamaya Builder (Extension Module)
-=== Overview
-
-The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
-e.g. as follows:
-
-[source,java]
----------------------------------------------------------------
-ConfigurationBuilder builder = new ConfigurationBuilder();
-// do something
-Configuration config = builder.build();
----------------------------------------------------------------
-
-Basically the builder allows to create configuration instances completely independent of the current configuration
-setup. This gives you full control on the +Configuration+ setup.
-
-=== Compatibility
-
-The module is based on Java 7, so it will run on Java 7 and does
-not require Java 8. The +ConfigurationProvider+
-as defined by the API, provides a builder instance for +ConfigurationContext+
-in a similar way. A +Configuration+ can also be created by passing an instance of a +ConfigurationContext+:
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding
-dependency to your module:
-
-[source,xml,subs="verbatim,attributes"]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-builder</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-=== Supported Functionality
-
-The builder allows you to add +PropertySource+ instances:
-
-[source,java]
-----------------------------------------------------------------
-ConfigurationBuilder builder = new ConfigurationBuilder();
-builder.addPropertySources(sourceOne).addPropertySources(sourceTwo);
-Configuration config = builder.build();
-----------------------------------------------------------------
-
-Similarly you can add filters:
-
-[source,java]
-----------------------------------------------------------------
-builder.addPropertyFilters(new MyConfigFilter());
-----------------------------------------------------------------
-
-...or +PropertySourceProvider+ instances:
-
-[source,java]
-----------------------------------------------------------------
-builder.addPropertySourceProvider(new MyPropertySourceProvider());
-----------------------------------------------------------------
-
-Also the builder module allows to include/exclude any filters and property source already known to the current
-+ConfigurationContext+:
-
-[source,java]
-----------------------------------------------------------------
-builder.disableProvidedPropertyConverters();
-builder.enableProvidedPropertyConverters();
-
-builder.disableProvidedPropertyFilters();
-builder.enableProvidedPropertyFilters();
-
-builder.disableProvidedPropertySources();
-builder.enableProvidedPropertySources();
-----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_camel.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_camel.adoc b/content/extensions/mod_camel.adoc
deleted file mode 100644
index 9690dda..0000000
--- a/content/extensions/mod_camel.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Integration with Apache Camel
-
-toc::[]
-
-
-[[Optional]]
-== Integration with Apache Camel (Extension Module)
-=== Overview
-
-The Tamaya Camel integration module provides different artifacts which allows integration of Apachae Tamaya
-configuration with Apache Camel.
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-camel</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The Extensions Provided
-
-Camel integration comes basically with three artifacts:
-
-* A Camel +ResolverFunction+ implementation adding explicit property resolution
- (+org.apache.tamaya.integration.camel.TamayaPropertyResolver+).
-* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and
- additionally allows using Tamaya configuration as Camel _overrides_
- (+org.apache.tamaya.integration.camel.TamayaPropertiesComponent+).
-
-
-=== Configuring using Camel Java DSL
-
-Camel integration using Java DSL is basically simple:
-
-[source, java]
------------------------------------------------
-import org.apache.tamaya.integration.camel.TamayaPropertiesComponent;
-
-camelContext.addComponent("properties", new TamayaPropertiesComponent());
------------------------------------------------
-
-Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows:
-
-[source, java]
------------------------------------------------
-RouteBuilder builder = new RouteBuilder() {
- public void configure() {
- from("direct:hello1").transform().simple("{{cfg:message}}");
- }
-};
-camelContext.addRoutes(builder);
-builder = new RouteBuilder() {
- public void configure() {
- from("direct:hello2").transform().simple("{{tamaya:message}}");
- }
-};
-camelContext.addRoutes(builder);
------------------------------------------------
-
-
-Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used
-as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel
-+PropertiesComponent+:
-
-[source, java]
------------------------------------------------
-TamayaPropertiesComponent props = new TamayaPropertiesComponent();
-props.setTamayaOverrides(true);
------------------------------------------------
-
-
-=== Configuring using Camel XML DSL
-
-Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean
-as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we
-again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback:
-
-[source, xml]
------------------------------------------------
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
- http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
- ">
-
- <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring">
- <route id="r1">
- <from uri="direct:hello1"/>
- <transform>
- <simple>{{message}}</simple>
- </transform>
- </route>
- <route id="r2">
- <from uri="direct:hello2"/>
- <transform>
- <simple>{{cfg:message}}</simple>
- </transform>
- </route>
- <route id="r3">
- <from uri="direct:hello3"/>
- <transform>
- <simple>{{tamaya:message}}</simple>
- </transform>
- </route>
- </routeContext>
-
- <bean id="properties" class="org.apache.tamaya.integration.camel.TamayaPropertiesComponent">
- <property name="tamayaOverrides" value="true"/>
- </bean>
-
-</beans>
------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_cdi.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_cdi.adoc b/content/extensions/mod_cdi.adoc
deleted file mode 100644
index c49a61c..0000000
--- a/content/extensions/mod_cdi.adoc
+++ /dev/null
@@ -1,217 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Classloader Isolation Support
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya CDI Integration (Extension Modules)
-=== Overview
-
-Apache Tamaya currently provides two implementations for integration with CDI extensions implementing similar
-functionality as described in this document:
-
-* Loading of CDI managed SPI components as configuration extensions such as +PropertySources, PropertySourceProviders,
- PropertyFilters, etc+. This also includes SPI defined by any Tamaya submodules.
-* Implement and enable Tamaya's configuration injection services with CDI.
-
-Hereby there are two implementations provided:
-
-* +tamaya-cdi-ee+ implements injection by using CDI's injection mechanism to inject configuration values into the
- beans managed by the CDI systems.
-* +tamaya-cdi-se+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used
- for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas
- beans and injection control overall are still managed by CDI.
-* One difference, of course, is that +tamaya-se+ also provides an SE compatible API (+ConfigurationInjection,
- ConfigurationInjector+), which is not available, when using the purely Java EE based variant.
-
-The annotations used for all injection functionality in Tamaya is defined as a separate module. This allows you to
-code against the injection API without dependency on the concrete injection implementation. As a consequence your
-components will be compatible regardless if deployed in a pure SE, a Java EE (CDI) or OSGI or Spring environment:
-
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-injection-api</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== Compatibility
-
-Both modules are based on Java 7, so they will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from Tamaya CDI integration you only must one of the following dependencies to your module. Ensure that
-you never have installed both CDI extensions at the same time because this may be lead to unforseen side-effects.
-
-.CDI Pure Application Configuration
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-cdi-ee</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-.CDI enhanced with Tamaya SE Application Configuration
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-cdi-se</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they
-register CDI extensions that implement Configuration injection as described before.
-
-IMPORTANT: Never install Tamaya's +tamaya-cdi-se+ and +tamaya-cdi-ee+ on the same system, since unpredictable side
- effects could occur.
-
-=== Registering CDI managed components into the Application's ConfigurationContext
-
-As mentioned both modules allow to provide Tamaya SPI extensions modules as ordinary CDI managed beans. By default
-extensions should be registered using +@Singleton+ or +@ApplicationScoped+ scope annotations. So you can define/deploy
-additional application specific +PropertySources+ and other artifacts simply by defining a CDI managed bean implementing
-the required SPI interface:
-
-[source, java]
---------------------------------------------------------
-@Singleton
-public class TestPropertySource implements PropertySource{
-
- final Map<String,String> config = new HashMap<>();
-
- public TestPropertySource(){
- config.put("a.b.c.key1", "keys current a.b.c.key1");
- config.put("a.b.c.key2", "keys current a.b.c.key2");
- config.put("{"+getName()+"}source", getClass().getName());
- }
-
- @Override
- public int getOrdinal() {
- return 10;
- }
-
- @Override
- public String getName() {
- return getClass().getName();
- }
-
- @Override
- public String get(String key) {
- return config.get(key);
- }
-
- @Override
- public Map<String, String> getProperties() {
- return config;
- }
-
- @Override
- public boolean isScannable() {
- return true;
- }
-}
---------------------------------------------------------
-
-Note that for many SPI's there is a priority mechanism using +@Priority+ annotations in place.
-The +ServiceContext+ implementation combines the components registered with the ones loaded from the +ServiceLoader+
-mechanism hereby considering classloaser hierarchies.
-
-
-=== Annotating your Classes
-
-Basically annotating your classes is stright forward. +@Config+ defines an additional CDI qualifier that is, depending
-on the module deployed, handled by a CDI producer (+tamaya-cdi-ee+) or the Tamaya SE injection mechanism $
-(+tamaya-cdi-se+). All types injected by this module are injected using _dependent scope_.
-
-
-[source, java]
---------------------------------------------------------
-@RequestScoped
-public class ConfiguredClass{
-
- @Config
- private String testProperty;
-
- @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"})
- @ConfigDefault("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
- String value1;
-
- @Config({"foo","a.b.c.key2"})
- private String value2;
-
- @Config
- @ConfigDefault("N/A")
- private String runtimeVersion;
-
- @Config
- @ConfigDefault("${sys:java.version}")
- private String javaVersion2;
-
- @Config
- @ConfigDefault("5")
- private Integer int1;
-
- ...
-
-}
---------------------------------------------------------
-
-=== Advanced Use Cases
-
-Beside basic configuration Tamaya also covers additional requirements:
-
-* _Reading multiple keys, where the first successful one is determining the value of the configuration, is
- simply possible, by adding multiple keys to the +@Configy+ annotation.
- E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows:
-
-[source,java]
---------------------------------------------------------------------------------------
-@Config({"a.b", "new.b"}
-private String value;
---------------------------------------------------------------------------------------
-
-* When you must apply a +ConfigOperator+ to your config, before reading the configuration, you can
- configure one as follows:
-
-[source,java]
---------------------------------------------------------------------------------------
-@Config({"a.b", "new.b"}
-@WithConfigOperator(MyOperator.class)
-private String value;
---------------------------------------------------------------------------------------
-
-* When you must apply a some special conversion, or you use a type that is not registered
- for conversion, you can configure a custom converter to be applied as follows:
-
-[source,java]
---------------------------------------------------------------------------------------
-@Config({"a.b", "new.b"}
-@WithPropertyConverter(MyConverter.class)
-private MySpecialFooType value;
---------------------------------------------------------------------------------------
-
-* Often multiple keys in a class belong to the same root section. So instead of copying this to
- every entry you can define the most common root sections in the type's header:
-
-[source,java]
---------------------------------------------------------------------------------------
-@ConfigDefaultSections({"aaaa", "new"});
-public class MyType{
-
-@Config({"b", "[legacy.bKey]"} // lookups: "aaaa.b", "new.b", legacy.bKey
-private String value;
---------------------------------------------------------------------------------------
-
-In the example above +legacy.bKey+ defines an absolute key, which is not combined with any defined
-default section parts.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_classloader_support.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_classloader_support.adoc b/content/extensions/mod_classloader_support.adoc
deleted file mode 100644
index 9a2d0df..0000000
--- a/content/extensions/mod_classloader_support.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Classloader Isolation Support
-
-toc::[]
-
-[[Remote]]
-== Tamaya Classloader Aware ServiceContext (Extension Module)
-=== Overview
-
-The Tamaya classloader support provides an alternative implementation of +java.util.ServiceLoader+, which is aware
-of classloaders, hereby preventing multiple loading of components within a classloader hierarchy.
-
-
-=== 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-classloader-support</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-The component will auto.register its components and override the default +ServicceContext+ in use by default
-with an instance of type +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+. This implementation returns
-a priority of +10+.
-
-=== How it works
-
-Basically the component manages a +Map+ of all classloaders encountered. When services are accessed, the component
-will evaluate the services as follows:
-
-* the component walks up the class loader hierarchy.
-* in a next step the hierarchy is traversed down from the parent to the current classloader. Hereby it is checked
- if the service list for the required type has been loaded already. If not the service configuration files are
- evaluated.
-* This configuration file evaluation will ignore all resources already loaded by any of the already traversed parent
- classloaders.
-* For each configuration file newly visible to the classloader currently traversed, the corresponding services are
- loaded unleyy, the same service class already has been loaded by one its parent classloaders or another file
- loaded with this classloader.
-* Finally all services found are returned as the full collection of services valid for the given context (classloader).
-
-This ensures no service is loaded multiple times, even when it is referenced multiple times in several service
-configurations. Additionally every service is loaded on the classloader where it is also declared the first time.
-
-
-=== Control Logging
-
-The service component by default only logs errors. But it is possible to change this by reconfiguring the logging
-levels on the following logging names/path: +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+
-
-* _INFO_ logs additional info on the services accessed.
-* _FINEST_ logs additional info on the services scanned and selected.
-
-
-=== Classloader Aware Configuration
-
-The mechanism above is used to provide a classloader aware implementation of +ConfigurationContext+
-(+org.apache.tamaya.clsupport.internal.CLAwareConfigurationContext+). Similarly to the service variants
-this class provides a context implementation that manages the core configuration aspects considering classloading
-hierarchies:
-
-* +PropertySource+, +PropertySourceProviders+
-* +PropertyFilters+, +PropertyCombinationPolicy+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_collections.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_collections.adoc b/content/extensions/mod_collections.adoc
deleted file mode 100644
index e758756..0000000
--- a/content/extensions/mod_collections.adoc
+++ /dev/null
@@ -1,232 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Collection Support
-
-toc::[]
-
-[[Optional]]
-== Tamaya Collection Support (Extension Module)
-=== Overview
-
-All configuration in Tamaya is expressed as simple key, value pairs. Nevertheless this concept allows similarly
-the modelling of collection typed values such as lists, sets, maps or simple collections of things. The Tamaya
-Collections extension adds this functionality to the Tamaya eco-system.
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To use Tamaya collection support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-collections</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== Overview
-
-Tamaya Collections adds +PropertyConverter+ implementations that are able to access configuration data
-as lists, maps or sets. By default this works out of the box as easy as accessing any other type of
-configuration data, e.g.
-
-[source, java]
------------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
-
-// Without any content specification, a list of String is returned.
-List<String> simpleList = config.get("my.list.config.entry", List.class);
-
-// Using a TypeLiteral allows to use every convertible sub type supported by the system.
-List<Integer> intList = config.get("my.list.config.entry", new TypeLiteral<List<Integer>>(){});
------------------------------------------------
-
-Configuration in that case, by default, is a simple comma-separated list of entries, e.g.
-
-[source, properties]
------------------------------------------------
-my.list.config.entry=1,34454,23,344545,3445
------------------------------------------------
-
-Additionally the module allows adding additional meta-entries, which allows to tweak some of the
-inner-workings, e.g.
-
-* using your own +PropertyConverter+ implementation for parsing entries.
-* specifying a custom separator String to be used to split the items (default is {{','}}.
-* specifying a custom separator String to be used to split key/value paris when parsing map entries.
-* specifying the implementation type of the collection instance to be returned.
-* specifying if the resulting collection should be returned as a modifiable collection.
-
-=== Supported Types
-
-This module supports the following types:
-
-* +java.util.Collection+
-* +java.util.List+
-* +java.util.ArrayList+
-* +java.util.LinkedList+
-* +java.util.Set+
-* +java.util.SortedSet+
-* +java.util.TreeSet+
-* +java.util.HashSet+
-* +java.util.Map+
-* +java.util.SortedMap+
-* +java.util.HashMap+
-* +java.util.TreeMap+
-
-Hereby the type is determined primarly by the parameter type accessed, e.g.
-+config.get("mylist", ArrayList.class)+ will always return an +ArrayList+
-as result.
-
-==== Configuring the target implementation type
-
-Tamaya Collections allows you to configure the target collection type by adding the
-following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+
-can be ommitted:
-
-[ source, properties]
------------------------------------------------
-mylist=a,b,c
-_mylist.collection-type=LinkedList
------------------------------------------------
-
-When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still
-get an +ArrayList+ as a result. However when you call +config.get("mylist", List.class)+ you will
-get a +LinkedList+ as implementation type.
-
-This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation
-type returned when accessing +List+, +Map+ or +Collection+.
-
-
-=== Collecting Configuration Entries instead of Overriding
-
-By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for
-the most significant configuration entry is used. In case of collections (and maybe also other use cases),
-overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your
-configuration to be *combined* to a new entry containing all values provided by any property sources.
-
-Therefore Tamaya Collections also provides a more sophistiated +CombinationPolicy+ (automatically configured)
-that allows to adapt the way how configuration entries are combined. All you must do is declaring
-the mechanism to be applied by an according meta-configuration parameter, e.g. for +my.list+ your config may
-look as follows:
-
-[source, properties]
------------------------------------------------
-# from PropertSource 1
-my.list=1,2,3
-
-# from PropertSource 2
-my.list=4,5,6
-
-# without any additional meta-info these entries would be combined to
-my.list=4,5,6
------------------------------------------------
-
-With Tamaya Collections you can now configure the combination policy as follows:
-
-[source, properties]
------------------------------------------------
-# use one of the default policies: override / collect
-_my.list.combination-policy=collect
-
-# use an custom CombinationPolicy to combine the values
-_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy
------------------------------------------------
-
-So declaring the +collect+ policy the resulting raw output of the entry looks as follows:
-
-[source, properties]
------------------------------------------------
-# result when applying the collect policy:
-my.list=1,2,3,4,5,6
------------------------------------------------
-
-The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration
-parameter explained later in this document.
-
-
-=== Format of Collection Configuration
-
-By default collections are modelled as simple String values, that are tokenized into individual parts using a
-defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3".
-If the target context type is something different than String the smae conversion logic is used as when mapping
-configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed
-within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types,
-with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+.
-The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas
-for values the same logic is applied as for non-map collection types.
-
-[source, properties]
------------------------------------------------
-# a list, using the default format
-list=1,2,3,4,5,6
-
-# a map, using the default format
-map=a::b, c::d
------------------------------------------------
-
-==== Trimming of entries
-
-By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is
-also the case for key/value entries. So the following configuration results in the identical values for
-+list1,list2+ and +map1,map2+:
-
-[source, properties]
------------------------------------------------
-# a list, using the default format
-list1=1,2,3,4,5,6
-list2=1, 2, 3, 4, 5, 6
-
-# a map, using the default format
-map1=a::b, c::d
-map2=a :: b, c :: d
------------------------------------------------
-
-Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
-space character as value:
-
-[source, properties]
------------------------------------------------
-# a list, with a ' ' value at the end
-list3=1, 2, 3, 4, 5, [ ]
-
-# a map, with a ' ' value for key '0'
-map3=1 :: a, 2 :: b, 0::[ ]
------------------------------------------------
-
-Hereby +\[+ escapes the sequence.
-
-
-==== Customizing the format
-
-The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data
-entries as follows, resulting in the same values as in the prevoius listing:
-
-[source, properties]
------------------------------------------------
-# a list, with a ' ' value at the end
-list3=1__2__3__ 4__ 5__[ ]
-_list3.item-separator=__
-
-# a map, with a ' ' value for key '0'
-map3=1->a, 2->b, 0->[ ]
-_map3.map-entry-separator=->
------------------------------------------------
-
-Of course these settings also can be combined:
-
-[source, properties]
------------------------------------------------
-# a reformatted map
-redefined-map=0==none | 1==single | 2==any
-_redefined-map.map-entry-separator===
-_redefined-map.item-separator=|
------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_consul.adoc b/content/extensions/mod_consul.adoc
deleted file mode 100644
index 4407ed3..0000000
--- a/content/extensions/mod_consul.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Integration with consul (Hashicorp)
-
-toc::[]
-
-
-[[Optional]]
-== Integration with consul (Extension Module)
-=== Overview
-
-The Tamaya consul integration module provides different artifacts which allows integration of Apachae Tamaya
-configuration with consul. Basically the module supports read-only integration (as a +ConsulPropertySource+ as well
-as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension 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-consul</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The Extensions Provided
-
-Consul integration comes basically with 2 artifacts:
-
-* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
- 'consul', which is automatically registered.
-* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
- by accessing a +MutableConfiguration+ using the URI +config:consul+.
-
-
-=== The ConsulPropertySource
-
-The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This
-enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
-in microservice containers to connect with the according consul cluster:
-
-* The property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible etcd servers
- (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
- configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
- server can be established a warning will be logged, but deployment will not fail.
-* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed
- context. This can be activated by setting the +-Dtamaya.consul.prefix=<PREFIX>+ system property. E.g. when the prefix is
- set to +cluster-config.+ a consul key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_environment.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_environment.adoc b/content/extensions/mod_environment.adoc
deleted file mode 100644
index c0224a1..0000000
--- a/content/extensions/mod_environment.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Classloader Isolation Support
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Environment Model (Extension Module)
-=== Overview
-
-The Tamaya Environment extension adds a simple PropertySourceProvider that evaluates a List of environment context and
-combines them in the given order into an (optional) root context within the system's configuration.
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from Tamaya Environment Model you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-envionment</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== How it Works
-
-tbd
-
-=== Reusable Base Classes
-
-tbd
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_etcd.adoc b/content/extensions/mod_etcd.adoc
deleted file mode 100644
index 149d843..0000000
--- a/content/extensions/mod_etcd.adoc
+++ /dev/null
@@ -1,189 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Integration with etcd (Core OS)
-
-toc::[]
-
-
-[[Optional]]
-== Integration with etcd (Extension Module)
-=== Overview
-
-The Tamaya etcd integration module provides different artifacts which allows integration of Apachae Tamaya
-configuration with etcd. Basically the module supports read-only integration (as a +EtcdPropertySource+ as well
-as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension 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-etcd</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The Extensions Provided
-
-ETcd integration comes basically with 2 artifacts:
-
-* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint root.
- (+org.apache.tamaya.etcd.EtcdAccessor+). The accessor basically provides a simple Java API for communicating
- with etcd server. The accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
- atomic write methods are implemented.
-* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
- 'etcd', which is automatically registered.
-* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster,
- by accessing a +MutableConfiguration+ using the URI +config:etcd+.
-
-=== The EtcdAccessor
-
-The accessor mentioned implements the basic read and write API for communicating with an etcd configuration cluster.
-Hereby the accessor also provides etcd specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
-returned. Hereby the concept of etcd is used where keys starting with an '_' will be hidden from the overall
-properties map, being only directly/explicitly accessible:
-
-[source, java]
------------------------------------------------
-public class EtcdAccessor {
-
- /**
- * Creates a new instance with the basic access url.
- * @param server server url, e.g. {@code http://127.0.0.1:4001}.
- * @throws MalformedURLException
- */
- public EtcdAccessor(String server) throws MalformedURLException;
-
- /**
- * Get the etcd server version.
- * @return the etcd server version, never null.
- */
- public String getVersion();
-
- /**
- * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
- * <pre>
- * key=value
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34 // optional
- * _key.ttl=300 // optional
- * _key.expiration=... // optional
- * </pre>
- * @param key the requested key
- * @return the mapped result, including meta-entries.
- */
- public Map<String,String> get(String key);
-
- /**
- * Creates/updates an entry in etcd without any ttl set.
- * The response is as follows:
- * <pre>
- * key=value
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34 // optional
- * _key.prevNode.createdIndex=12 // optional
- * _key.prevNode.modifiedIndex=34 // optional
- * </pre>
- * @param key the property key, not null
- * @param value the value to be set
- * @return the result map as described above.
- */
- public Map<String,String> set(String key, String value);
-
- /**
- * Creates/updates an entry in etcd. The response is as follows:
- * <pre>
- * key=value
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34 // optional
- * _key.ttl=300 // optional
- * _key.expiry=... // optional
- * _key.prevNode.createdIndex=12 // optional
- * _key.prevNode.modifiedIndex=34 // optional
- * _key.prevNode.ttl=300 // optional
- * _key.prevNode.expiration=... // optional
- * </pre>
- * @param key the property key, not null
- * @param value the value to be set
- * @param ttlSeconds the ttl in seconds (optional)
- * @return the result map as described above.
- */
- public Map<String,String> set(String key, String value, Integer ttlSeconds);
-
-
- /**
- * Deletes a given key. The response is as follows:
- * <pre>
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34
- * _key.ttl=300 // optional
- * _key.expiry=... // optional
- * _key.prevNode.createdIndex=12 // optional
- * _key.prevNode.modifiedIndex=34 // optional
- * _key.prevNode.ttl=300 // optional
- * _key.prevNode.expiration=... // optional
- * _key.prevNode.value=... // optional
- * </pre>
- * @param key the key to be deleted.
- * @return the response mpas as described above.
- */
- public Map<String,String> delete(String key);
-
-
- /**
- * Access regular Tamaya properties map as follows:
- * <pre>
- * key1=myvalue
- * _key1.source=[etcd]http://127.0.0.1:4001
- * _key1.createdIndex=12
- * _key1.modifiedIndex=34 // optional
- * _key1.ttl=300 // optional
- * _key1.expiration=... // optional
- *
- * key2=myvaluexxx
- * _key2.source=[etcd]http://127.0.0.1:4001
- * _key2.createdIndex=12
- *
- * key3=val3
- * _key3.source=[etcd]http://127.0.0.1:4001
- * _key3.createdIndex=12
- * _key3.modifiedIndex=2
- * </pre>
- */
- public Map<String,String> getProperties(String directory, boolean recursive);
-
-}
------------------------------------------------
-
-
-=== The EtcdPropertySource
-
-The +EtcdPropertySource+ is automatically registered and allows to configure the etcd servers to be used. This
-enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
-in microservice containers to connect with the according etcd cluster:
-
-* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers
- (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
- configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
- server can be established a warning will be logged, but deployment will not fail.
-* Additinoally also the
- accessor allows to configure the socket/connection timeouts by setting +tamaya.etcd.timeout+ in seconds either as
- system or environment property.
-* The +EtcdPropertySource+ finally also allows the values read from the etcd cluster to be mapped to prefixed
- context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
- set to +cluster-config.+ a etcd key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_events.adoc b/content/extensions/mod_events.adoc
deleted file mode 100644
index c0a3809..0000000
--- a/content/extensions/mod_events.adoc
+++ /dev/null
@@ -1,278 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Events
-
-toc::[]
-
-
-[[Core]]
-== Tamaya Events (Extension Module)
-=== Overview
-
-Tamaya Events is an extension module. Refer to the link:modules.html[extensions documentation] for further details
-about modules.
-
-Tamaya Events provides an abstraction for events like change events, when configuration has been changed.
-
-=== Compatibility
-
-The module is based on Java 7, so it can be used with Java 7 and beyond.
-
-=== Installation
-
-To benefit from configuration event support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-events</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-=== Core Architecture
-
-The core of the module are the +ConfigEventListener+ interface and the +ConfigEvent+ class, which defines an abstraction
-for event handling and observation:
-
-[source,java]
-.ConfigEvent
---------------------------------------------
-public final interface ConfigEvent<T> {
-
- Class<T> getResourceType();
- T getResource();
- String getVersion();
- long getTimestamp();
-}
-
-// @FunctionalInterface
-public interface ConfigEventListener {
-
- void onConfigEvent(ConfigEvent<?> event);
-
-}
---------------------------------------------
-
-This mechanism can now be used to propagate configuration changes to all interested stakeholders. Hereby the payload
-can be basically arbitrary as long as it implements the +ConfigEvent+ interface. The next sections
-give more details on the the provided event types and their usage.
-
-
-=== Modelling Configuration Changes
-
-This module provides a serializable and thread-safe abstraction modlling a configuration change. A change hereby may
-be
-
-* additional configuration entries
-* removed configuration entries
-* changes on entries
-
-
-The most important event modelled is the +ConfigurationChange+ class, which implements the event sent for a changed
-+Configuration+:
-
-[source,java]
--------------------------------------------------------
-public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{
-
- public static ConfigurationChange emptyChangeSet(Configuration configuration);
-
- @Override
- public Configuration getResource();
- @Override
- public Class<Configuration> getResourceType();
- @Override
- public String getVersion();
- @Override
- public long getTimestamp();
-
- // Event specific methods
-
- public Collection<PropertyChangeEvent> getChanges();
- public int getRemovedSize();
- public int getAddedSize();
- public int getUpdatedSize();
-
- public boolean isKeyAffected(String key);
- public boolean isRemoved(String key);
- public boolean isAdded(String key);
- public boolean isUpdated(String key);
- public boolean containsKey(String key);
- public boolean isEmpty();
-}
-
--------------------------------------------------------
-
-New instances of this class hereby can be created using a fluent builder:
-
-[source,java]
--------------------------------------------------------
-Configuration config = ...;
-ConfigurationChange change = ConfigurationChangeBuilder.of(config)
- .addChange("MyKey", "newValue")
- .removeKeys("myRemovedKey").build();
--------------------------------------------------------
-
-Also it is possible to directly compare 2 instances of configurations to create +ConfigurationChange+ that
-reflect the differences between the two configurations:
-
-[source,java]
-Comparing 2 configurations
--------------------------------------------------------
-Configuration config = ...;
-Configuration changedConfig = ...;
-ConfigurationChange change = ConfigurationChangeBuilder.of(config)
- .addChanges(changedConfig).build();
--------------------------------------------------------
-
-So a +ConfigurationChange+ allows you to evaluate the changes on a configuration. This allows you to listen to changes
-and react in your client code as useful, once you encounter changes that are relevant to you, e.g. by reconfiguring
-your component. For listening to configuration changes you must implement the
-+ConfigEventListener+ functional interface:
-
-[source,java]
-.Implementing a ConfigChangeListener
--------------------------------------------------------
-public final class MyConfigChangeListener implements ConfigChangeListener<ConfigurationChange>{
-
- private Configuration config = ConfigurationProvider.getConfiguration();
-
- public void onConfigEvent(ConfigEvent<?> event){
- if(event.getResourceTspe()==Configuration.class){
- if(event.getConfiguration()==config){
- // do something
- }
- }
- }
-
-}
--------------------------------------------------------
-
-You can *register* your implementation in 2 ways:
-
-. Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+
-. Automatically by registering your listener using the +ServiceLoader+ under
- +META-INF/services/org.apache.tamaya.events.ConfigEventListener+
-
-
-=== Modelling PropertySource Changes
-
-Beside that a whole configuration changes, also +PropertySource+ instances can change, e.g. by a configuration file
-edited on the fly. This is similarly to a +ConfigurationChange+ reflected by the classes +PropertySourceChange,
-PropertySourceChangeBuilder+.
-
-
-=== The ConfigEventManager Singleton
-
-Main entry point of the events module is the +ConfigEventManager+ singleton class, which provides static accessor
-methods to the extension's functionality:
-
-* Adding/removing of +ConfigChangeListener+ instances, either globally or per event type.
-* Firing configuration events synchronously or asyncronously (mostly called by framework code).
-* Configuring the monitor that periodically checks for changes on the global +Configuration+ provided
- by +ConfigurationProvider.getConfiguration()+.
-
-[source,java]
--------------------------------------------------------
-public final class ConfigEventManager {
-
- private ConfigEventManager() {}
-
- public static void addListener(ConfigEventListener l);
- public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
- public static void removeListener(ConfigEventListener l);
- public static <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
- public static <T extends ConfigEvent>
- Collection<? extends ConfigEventListener> getListeners();
- public static <T extends ConfigEvent>
- Collection<? extends ConfigEventListener> getListeners(Class<T> type);
-
- public static <T> void fireEvent(ConfigEvent<?> event);
- public static <T> void fireEventAsynch(ConfigEvent<?> event);
-
- public static void enableChangeMonitoring(boolean enable);
- public static boolean isChangeMonitoring();
- public long getChangeMonitoringPeriod();
- public void setChangeMonitoringPeriod(long millis);
-
-}
--------------------------------------------------------
-
-
-==== Monitoring of configuration changes
-
-The +ConfigEventManager+ also supports active monitoring of the current configuration to trigger corresponding change
-events to listeners registered. This feature is deactivated by default, but can be enabled by calling
-+ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling your local +Configuration+ for
-any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding
-+ConfigurationChange+ events automatically.
-
-
-=== Freezing Configurations and PropertySources
-
-+Configuration+ instances as well as +PropertySources+ are explicitly not required to be serializable. To enable easy
-serialization of these types a +Configuration+'s *current state can be frozen* (e.g. for later comparison with a newly
-loaded version). Freezing hereby means
-
-* all key/values are read-out by calling the +getProperties()+ method.
-* a meta data entry is added of the form +_frozenAt=223273777652325677+, whichdefines the UTC timestamp in
- milliseconds when this instance was frozen.
-* if not already defined an +_id+ property will be added to the +Configuration+ containing the
- identifier of the configuration.
-
-In code freezing is a no-brainer:
-
-[source,java]
-.Freezing the current Configuration
---------------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
-Configuration frozenConfig = FrozenConfiguration.of(config);
---------------------------------------------------
-
-... and similarly for a +PropertySource+:
-
-[source,java]
-.Freezing the current Configuration
---------------------------------------------------
-PropertySource propertySource = ...;
-PropertySource frozenSource = FrozenPropertySource.of(propertySource);
---------------------------------------------------
-
-
-
-=== SPIs
-
-This component also defines an additional SPI, which allows to adapt the implementation of the main +ConfigEventManager+
-singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided
-simple SE based implementation. As normal, implementation must be registered using the current +ServiceContext+
-active, by default using the Java +ServiceLoader+ mechanism.
-
-[source,java]
-.SPI: ConfigEventSpi
---------------------------------------------------
-public interface ConfigEventManagerSpi {
-
- <T> void addListener(ConfigEventListener l);
- <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
- void removeListener(ConfigEventListener l);
- <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
- Collection<? extends ConfigEventListener> getListeners();
- Collection<? extends ConfigEventListener> getListeners(Class<? extends ConfigEvent> eventType);
-
- void fireEvent(ConfigEvent<?> event);
- void fireEventAsynch(ConfigEvent<?> event);
-
- long getChangeMonitoringPeriod();
- void setChangeMonitoringPeriod(long millis);
- boolean isChangeMonitorActive();
- void enableChangeMonitor(boolean enable);
-}
---------------------------------------------------
-
-
-Summarizing with the events module you can easily observe configuration changes, record the
-state of any configuration and compare configuration states to create and publish related
-change events.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_filter.adoc b/content/extensions/mod_filter.adoc
deleted file mode 100644
index 670faa0..0000000
--- a/content/extensions/mod_filter.adoc
+++ /dev/null
@@ -1,119 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: User Filtering
-
-toc::[]
-
-
-[[Optional]]
-== User Filtering (Extension Module)
-=== Overview
-
-The Tamaya filter module provides a simple singleton accessor that allows to explicitly add +PropertyFilter+ instances
-active on the current thread only. This can be very useful in many scenarios. Additionally this module adds
-standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed
-explicitily no filtering is applied and everything is visible.
-
-=== 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-filter</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The Extensions Provided
-
-Tamaya Filter comes basically with 3 artifacts:
-
-* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +PropertyFilter+
-instances on the current thread.
-* The +org.apache.tamaya.filter.DefaultMetdataFilter+ is a +PropertyFilter+ with hides all entries starting with
- an underscore ('_'), when a full property map is accessed.
-
-
-=== The ConfigurationFilter
-
-The accessor mentioned implements the API for for adding +PropertyFilters+ to the current thread (as thread local):
-
-[source, java]
------------------------------------------------
-public final class ConfigurationFilter implements PropertyFilter{
-
- ...
-
- /**
- * Seactivates metadata filtering also on global map access for this thread.
- * @see #clearFilters()
- * @param active true,to enable metadata filtering (default).
- */
- public static void setFilterMetadata(boolean active);
-
- /**
- * Access the filtering configuration that is used for filtering single property values accessed.
- * @return the filtering config, never null.
- */
- public static FilterContext getSingleFilterContext();
-
- /**
- * Access the filtering configuration that is used for filtering configuration properties accessed as full
- * map.
- * @return the filtering config, never null.
- */
- public static FilterContext getMapFilters();
-
- /**
- * Removes all programmable filters active on the current thread.
- */
- public static void clearFilters();
-
- ...
-
-}
------------------------------------------------
-
-For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+
-is part of this module, So you can add a customized filter as follows:
-
-[source, java]
------------------------------------------------
-try {
- ConfigurationFilter.getMapFilters().addFilter(new myFilter());
-
- // do your code with filtering active
-}
-finally {
- // cleanup
- ConfigurationFilter.clearFilters();
-}
------------------------------------------------
-
-The +FilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local
-managed filters:
-
-[source, java]
------------------------------------------------
-public final class FilterContext implements PropertyFilter {
-
- public void addIncludes(PropertyFilter filter);
- public void addExcludes(int pos, PropertyFilter filter);
- public PropertyFilter removeFilter(int pos);
- public void clearFilters();
- public void setIncludes(PropertyFilter... filters);
- public void setExcludes(Collection<PropertyFilter> filters);
- public List<PropertyFilter> getFilters();
-
-}
------------------------------------------------
[07/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_etcd.adoc b/content/documentation/extensions/mod_etcd.adoc
new file mode 100644
index 0000000..149d843
--- /dev/null
+++ b/content/documentation/extensions/mod_etcd.adoc
@@ -0,0 +1,189 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Integration with etcd (Core OS)
+
+toc::[]
+
+
+[[Optional]]
+== Integration with etcd (Extension Module)
+=== Overview
+
+The Tamaya etcd integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with etcd. Basically the module supports read-only integration (as a +EtcdPropertySource+ as well
+as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension 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-etcd</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+ETcd integration comes basically with 2 artifacts:
+
+* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint root.
+ (+org.apache.tamaya.etcd.EtcdAccessor+). The accessor basically provides a simple Java API for communicating
+ with etcd server. The accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
+ atomic write methods are implemented.
+* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
+ 'etcd', which is automatically registered.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster,
+ by accessing a +MutableConfiguration+ using the URI +config:etcd+.
+
+=== The EtcdAccessor
+
+The accessor mentioned implements the basic read and write API for communicating with an etcd configuration cluster.
+Hereby the accessor also provides etcd specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
+returned. Hereby the concept of etcd is used where keys starting with an '_' will be hidden from the overall
+properties map, being only directly/explicitly accessible:
+
+[source, java]
+-----------------------------------------------
+public class EtcdAccessor {
+
+ /**
+ * Creates a new instance with the basic access url.
+ * @param server server url, e.g. {@code http://127.0.0.1:4001}.
+ * @throws MalformedURLException
+ */
+ public EtcdAccessor(String server) throws MalformedURLException;
+
+ /**
+ * Get the etcd server version.
+ * @return the etcd server version, never null.
+ */
+ public String getVersion();
+
+ /**
+ * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.ttl=300 // optional
+ * _key.expiration=... // optional
+ * </pre>
+ * @param key the requested key
+ * @return the mapped result, including meta-entries.
+ */
+ public Map<String,String> get(String key);
+
+ /**
+ * Creates/updates an entry in etcd without any ttl set.
+ * The response is as follows:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * </pre>
+ * @param key the property key, not null
+ * @param value the value to be set
+ * @return the result map as described above.
+ */
+ public Map<String,String> set(String key, String value);
+
+ /**
+ * Creates/updates an entry in etcd. The response is as follows:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.ttl=300 // optional
+ * _key.expiry=... // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * _key.prevNode.ttl=300 // optional
+ * _key.prevNode.expiration=... // optional
+ * </pre>
+ * @param key the property key, not null
+ * @param value the value to be set
+ * @param ttlSeconds the ttl in seconds (optional)
+ * @return the result map as described above.
+ */
+ public Map<String,String> set(String key, String value, Integer ttlSeconds);
+
+
+ /**
+ * Deletes a given key. The response is as follows:
+ * <pre>
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34
+ * _key.ttl=300 // optional
+ * _key.expiry=... // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * _key.prevNode.ttl=300 // optional
+ * _key.prevNode.expiration=... // optional
+ * _key.prevNode.value=... // optional
+ * </pre>
+ * @param key the key to be deleted.
+ * @return the response mpas as described above.
+ */
+ public Map<String,String> delete(String key);
+
+
+ /**
+ * Access regular Tamaya properties map as follows:
+ * <pre>
+ * key1=myvalue
+ * _key1.source=[etcd]http://127.0.0.1:4001
+ * _key1.createdIndex=12
+ * _key1.modifiedIndex=34 // optional
+ * _key1.ttl=300 // optional
+ * _key1.expiration=... // optional
+ *
+ * key2=myvaluexxx
+ * _key2.source=[etcd]http://127.0.0.1:4001
+ * _key2.createdIndex=12
+ *
+ * key3=val3
+ * _key3.source=[etcd]http://127.0.0.1:4001
+ * _key3.createdIndex=12
+ * _key3.modifiedIndex=2
+ * </pre>
+ */
+ public Map<String,String> getProperties(String directory, boolean recursive);
+
+}
+-----------------------------------------------
+
+
+=== The EtcdPropertySource
+
+The +EtcdPropertySource+ is automatically registered and allows to configure the etcd servers to be used. This
+enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
+in microservice containers to connect with the according etcd cluster:
+
+* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers
+ (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
+ configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
+ server can be established a warning will be logged, but deployment will not fail.
+* Additinoally also the
+ accessor allows to configure the socket/connection timeouts by setting +tamaya.etcd.timeout+ in seconds either as
+ system or environment property.
+* The +EtcdPropertySource+ finally also allows the values read from the etcd cluster to be mapped to prefixed
+ context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
+ set to +cluster-config.+ a etcd key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_events.adoc b/content/documentation/extensions/mod_events.adoc
new file mode 100644
index 0000000..c0a3809
--- /dev/null
+++ b/content/documentation/extensions/mod_events.adoc
@@ -0,0 +1,278 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Events
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Events (Extension Module)
+=== Overview
+
+Tamaya Events is an extension module. Refer to the link:modules.html[extensions documentation] for further details
+about modules.
+
+Tamaya Events provides an abstraction for events like change events, when configuration has been changed.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+To benefit from configuration event support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-events</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+=== Core Architecture
+
+The core of the module are the +ConfigEventListener+ interface and the +ConfigEvent+ class, which defines an abstraction
+for event handling and observation:
+
+[source,java]
+.ConfigEvent
+--------------------------------------------
+public final interface ConfigEvent<T> {
+
+ Class<T> getResourceType();
+ T getResource();
+ String getVersion();
+ long getTimestamp();
+}
+
+// @FunctionalInterface
+public interface ConfigEventListener {
+
+ void onConfigEvent(ConfigEvent<?> event);
+
+}
+--------------------------------------------
+
+This mechanism can now be used to propagate configuration changes to all interested stakeholders. Hereby the payload
+can be basically arbitrary as long as it implements the +ConfigEvent+ interface. The next sections
+give more details on the the provided event types and their usage.
+
+
+=== Modelling Configuration Changes
+
+This module provides a serializable and thread-safe abstraction modlling a configuration change. A change hereby may
+be
+
+* additional configuration entries
+* removed configuration entries
+* changes on entries
+
+
+The most important event modelled is the +ConfigurationChange+ class, which implements the event sent for a changed
++Configuration+:
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{
+
+ public static ConfigurationChange emptyChangeSet(Configuration configuration);
+
+ @Override
+ public Configuration getResource();
+ @Override
+ public Class<Configuration> getResourceType();
+ @Override
+ public String getVersion();
+ @Override
+ public long getTimestamp();
+
+ // Event specific methods
+
+ public Collection<PropertyChangeEvent> getChanges();
+ public int getRemovedSize();
+ public int getAddedSize();
+ public int getUpdatedSize();
+
+ public boolean isKeyAffected(String key);
+ public boolean isRemoved(String key);
+ public boolean isAdded(String key);
+ public boolean isUpdated(String key);
+ public boolean containsKey(String key);
+ public boolean isEmpty();
+}
+
+-------------------------------------------------------
+
+New instances of this class hereby can be created using a fluent builder:
+
+[source,java]
+-------------------------------------------------------
+Configuration config = ...;
+ConfigurationChange change = ConfigurationChangeBuilder.of(config)
+ .addChange("MyKey", "newValue")
+ .removeKeys("myRemovedKey").build();
+-------------------------------------------------------
+
+Also it is possible to directly compare 2 instances of configurations to create +ConfigurationChange+ that
+reflect the differences between the two configurations:
+
+[source,java]
+Comparing 2 configurations
+-------------------------------------------------------
+Configuration config = ...;
+Configuration changedConfig = ...;
+ConfigurationChange change = ConfigurationChangeBuilder.of(config)
+ .addChanges(changedConfig).build();
+-------------------------------------------------------
+
+So a +ConfigurationChange+ allows you to evaluate the changes on a configuration. This allows you to listen to changes
+and react in your client code as useful, once you encounter changes that are relevant to you, e.g. by reconfiguring
+your component. For listening to configuration changes you must implement the
++ConfigEventListener+ functional interface:
+
+[source,java]
+.Implementing a ConfigChangeListener
+-------------------------------------------------------
+public final class MyConfigChangeListener implements ConfigChangeListener<ConfigurationChange>{
+
+ private Configuration config = ConfigurationProvider.getConfiguration();
+
+ public void onConfigEvent(ConfigEvent<?> event){
+ if(event.getResourceTspe()==Configuration.class){
+ if(event.getConfiguration()==config){
+ // do something
+ }
+ }
+ }
+
+}
+-------------------------------------------------------
+
+You can *register* your implementation in 2 ways:
+
+. Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+
+. Automatically by registering your listener using the +ServiceLoader+ under
+ +META-INF/services/org.apache.tamaya.events.ConfigEventListener+
+
+
+=== Modelling PropertySource Changes
+
+Beside that a whole configuration changes, also +PropertySource+ instances can change, e.g. by a configuration file
+edited on the fly. This is similarly to a +ConfigurationChange+ reflected by the classes +PropertySourceChange,
+PropertySourceChangeBuilder+.
+
+
+=== The ConfigEventManager Singleton
+
+Main entry point of the events module is the +ConfigEventManager+ singleton class, which provides static accessor
+methods to the extension's functionality:
+
+* Adding/removing of +ConfigChangeListener+ instances, either globally or per event type.
+* Firing configuration events synchronously or asyncronously (mostly called by framework code).
+* Configuring the monitor that periodically checks for changes on the global +Configuration+ provided
+ by +ConfigurationProvider.getConfiguration()+.
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigEventManager {
+
+ private ConfigEventManager() {}
+
+ public static void addListener(ConfigEventListener l);
+ public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
+ public static void removeListener(ConfigEventListener l);
+ public static <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
+ public static <T extends ConfigEvent>
+ Collection<? extends ConfigEventListener> getListeners();
+ public static <T extends ConfigEvent>
+ Collection<? extends ConfigEventListener> getListeners(Class<T> type);
+
+ public static <T> void fireEvent(ConfigEvent<?> event);
+ public static <T> void fireEventAsynch(ConfigEvent<?> event);
+
+ public static void enableChangeMonitoring(boolean enable);
+ public static boolean isChangeMonitoring();
+ public long getChangeMonitoringPeriod();
+ public void setChangeMonitoringPeriod(long millis);
+
+}
+-------------------------------------------------------
+
+
+==== Monitoring of configuration changes
+
+The +ConfigEventManager+ also supports active monitoring of the current configuration to trigger corresponding change
+events to listeners registered. This feature is deactivated by default, but can be enabled by calling
++ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling your local +Configuration+ for
+any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding
++ConfigurationChange+ events automatically.
+
+
+=== Freezing Configurations and PropertySources
+
++Configuration+ instances as well as +PropertySources+ are explicitly not required to be serializable. To enable easy
+serialization of these types a +Configuration+'s *current state can be frozen* (e.g. for later comparison with a newly
+loaded version). Freezing hereby means
+
+* all key/values are read-out by calling the +getProperties()+ method.
+* a meta data entry is added of the form +_frozenAt=223273777652325677+, whichdefines the UTC timestamp in
+ milliseconds when this instance was frozen.
+* if not already defined an +_id+ property will be added to the +Configuration+ containing the
+ identifier of the configuration.
+
+In code freezing is a no-brainer:
+
+[source,java]
+.Freezing the current Configuration
+--------------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+Configuration frozenConfig = FrozenConfiguration.of(config);
+--------------------------------------------------
+
+... and similarly for a +PropertySource+:
+
+[source,java]
+.Freezing the current Configuration
+--------------------------------------------------
+PropertySource propertySource = ...;
+PropertySource frozenSource = FrozenPropertySource.of(propertySource);
+--------------------------------------------------
+
+
+
+=== SPIs
+
+This component also defines an additional SPI, which allows to adapt the implementation of the main +ConfigEventManager+
+singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided
+simple SE based implementation. As normal, implementation must be registered using the current +ServiceContext+
+active, by default using the Java +ServiceLoader+ mechanism.
+
+[source,java]
+.SPI: ConfigEventSpi
+--------------------------------------------------
+public interface ConfigEventManagerSpi {
+
+ <T> void addListener(ConfigEventListener l);
+ <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
+ void removeListener(ConfigEventListener l);
+ <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
+ Collection<? extends ConfigEventListener> getListeners();
+ Collection<? extends ConfigEventListener> getListeners(Class<? extends ConfigEvent> eventType);
+
+ void fireEvent(ConfigEvent<?> event);
+ void fireEventAsynch(ConfigEvent<?> event);
+
+ long getChangeMonitoringPeriod();
+ void setChangeMonitoringPeriod(long millis);
+ boolean isChangeMonitorActive();
+ void enableChangeMonitor(boolean enable);
+}
+--------------------------------------------------
+
+
+Summarizing with the events module you can easily observe configuration changes, record the
+state of any configuration and compare configuration states to create and publish related
+change events.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_filter.adoc b/content/documentation/extensions/mod_filter.adoc
new file mode 100644
index 0000000..670faa0
--- /dev/null
+++ b/content/documentation/extensions/mod_filter.adoc
@@ -0,0 +1,119 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: User Filtering
+
+toc::[]
+
+
+[[Optional]]
+== User Filtering (Extension Module)
+=== Overview
+
+The Tamaya filter module provides a simple singleton accessor that allows to explicitly add +PropertyFilter+ instances
+active on the current thread only. This can be very useful in many scenarios. Additionally this module adds
+standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed
+explicitily no filtering is applied and everything is visible.
+
+=== 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-filter</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Tamaya Filter comes basically with 3 artifacts:
+
+* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +PropertyFilter+
+instances on the current thread.
+* The +org.apache.tamaya.filter.DefaultMetdataFilter+ is a +PropertyFilter+ with hides all entries starting with
+ an underscore ('_'), when a full property map is accessed.
+
+
+=== The ConfigurationFilter
+
+The accessor mentioned implements the API for for adding +PropertyFilters+ to the current thread (as thread local):
+
+[source, java]
+-----------------------------------------------
+public final class ConfigurationFilter implements PropertyFilter{
+
+ ...
+
+ /**
+ * Seactivates metadata filtering also on global map access for this thread.
+ * @see #clearFilters()
+ * @param active true,to enable metadata filtering (default).
+ */
+ public static void setFilterMetadata(boolean active);
+
+ /**
+ * Access the filtering configuration that is used for filtering single property values accessed.
+ * @return the filtering config, never null.
+ */
+ public static FilterContext getSingleFilterContext();
+
+ /**
+ * Access the filtering configuration that is used for filtering configuration properties accessed as full
+ * map.
+ * @return the filtering config, never null.
+ */
+ public static FilterContext getMapFilters();
+
+ /**
+ * Removes all programmable filters active on the current thread.
+ */
+ public static void clearFilters();
+
+ ...
+
+}
+-----------------------------------------------
+
+For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+
+is part of this module, So you can add a customized filter as follows:
+
+[source, java]
+-----------------------------------------------
+try {
+ ConfigurationFilter.getMapFilters().addFilter(new myFilter());
+
+ // do your code with filtering active
+}
+finally {
+ // cleanup
+ ConfigurationFilter.clearFilters();
+}
+-----------------------------------------------
+
+The +FilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local
+managed filters:
+
+[source, java]
+-----------------------------------------------
+public final class FilterContext implements PropertyFilter {
+
+ public void addIncludes(PropertyFilter filter);
+ public void addExcludes(int pos, PropertyFilter filter);
+ public PropertyFilter removeFilter(int pos);
+ public void clearFilters();
+ public void setIncludes(PropertyFilter... filters);
+ public void setExcludes(Collection<PropertyFilter> filters);
+ public List<PropertyFilter> getFilters();
+
+}
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_formats.adoc b/content/documentation/extensions/mod_formats.adoc
new file mode 100644
index 0000000..401a755
--- /dev/null
+++ b/content/documentation/extensions/mod_formats.adoc
@@ -0,0 +1,206 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Formats
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Formats (Extension Module)
+=== Overview
+
+Tamaya Formats is an extension module. Refer to the link:modules.html[extensions documentation] for further details.
+
+Tamaya Formats provides an abstraction for configuration formats provding the following benefits:
+
+* Parsing of resources in can be implemented separately from interpreting the different aspects/parts parsed. As an
+ example a file format can define different sections. Depending on the company specific semantics of the sections
+ a different set of +PropertySource+ instances must be created.
+* Similarly the configuration abstraction can also be used as an interface for integrating Tamaya with alternate
+ frameworks that provide logic for reading configuration files, such as Apache commons.configuration.
+
+=== 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]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-formats</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Idea
+
+Formats should be reusable, meaning you should have to write a format parser only once and then be able to map the data read into whatever
+data structure (in our cases: property sources).
+
+==== ConfigurationData
+
+Configuration formats can be very different. Some are simple key/value pairs, whereas other also consist of multiple sections (e.g. ini-files) or
+hierarchical data (e.g. yaml, xml). This is solved in Tamaya by mapping the configuration read into a normalized intermediary format called
++ConfigurationData+:
+
+[source,java]
+.ConfigurationData
+-------------------------------------------------------
+public final class ConfigurationData {
+
+ public ConfigurationFormat getFormat();
+ public String getResource();
+
+ public Set<String> getSectionNames();
+ public Map<String,String> getSection(String name);
+
+ public boolean hasDefaultProperties();
+ public Map<String,String> getDefaultProperties();
+ public Map<String,String> getCombinedProperties();
+
+ public boolean isEmpty();
+}
+-------------------------------------------------------
+
+In detail the data read from a file is organized into _sections_ as follows:
+
+* with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed.
+* properties can be owned by
+ ** named sections
+ ** an (unnamed) default section
+* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple
+ named sections, depending on the configuration format.
+* The method +getSectionNames()+ returns a set of all section names.
+* With +getSection(String name)+ a named section can be accessed.
+* With +getDefaultSection()+ the 'default' section can be accessed. This is a convenience method.
+* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of
+ ** all entries from the default section, without any changes.
+ ** all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.
+* The configuration format used determines the mapping of configuration data read into this structure. The format
+ implementation can as well provide alternate implementations of how the data read should be mapped into the
+ combined properties map.
+
+
+==== ConfigurationFormat
+
+A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and
+creates a corresponding +ConfigurationData+ instance.
+
+[source,java]
+-------------------------------------------------------
+public interface ConfigurationFormat {
+
+ String getName();
+ boolean accepts(URL url);
+ ConfigurationData readConfiguration(String resource, InputStream inputStream);
+}
+-------------------------------------------------------
+
+
+=== How to tranform ConfigurationData into a PropertySource
+
+For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful:
+
+. The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties
+ or/and as default properties. The most simple cases is, where all properties have been added as 'default'
+ properties. In this case the default properties can be used as the property sources properties without any change.
+. If the format did also add section based properties, the combined properties returned can be used, hereby
+ replacing the '::' separator with a '.' separator.
+. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataPropertySource+
+ and overriding the +Map<String,String> populateData(ConfigurationData data)+ method.
+
+In most cases the usage of a +FlattenedDefaultPropertySource+, is a good choice to start. This class
+provides a convenient default mapping and also allows to customized the mapping easily:
+
+[source,java]
+-------------------------------------------------------
+ConfigurationData data = ...;
+FlattenedDefaultPropertySource ps = new FlattenedDefaultPropertySource(data){
+ protected Map<String, String> populateData(ConfigurationData data) {
+ ...
+ }
+};
+-------------------------------------------------------
+
+Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
+resulting properties can have different semnatics, especially different priorities. Also section
+names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats
+with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping
+can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the
+appropriate collection of +PropertySource+ instances must be implemented.
+
+
+=== Examples
+
+==== Mapping ini-Files
+
+Consider the following ini-file:
+
+[source,listing]
+.Example.ini
+-------------------------------------------------------
+a=valA
+a.b=valB
+
+[section1]
+aa=sectionValA
+aa.b.c=SectionValC
+
+[section2]
+a=val2Section2
+-------------------------------------------------------
+
+This file content coud be mapped to the following structure:
+
+[source,listing]
+.Mapping of Example.ini
+-------------------------------------------------------
+a=valA
+a.b=valB
+section1::valA=sectionValA
+section1::a.b.c=SectionValC
+section2::a=val2Section2
+-------------------------------------------------------
+
+Nevertheless from the +ConfigurationData+ instance a more complex algorithm can access all the different parts:
+
+* the_default_ properties (a, a.b)
+* the section +section1+, with properties +aa, aa.b.c+
+* the section +section2+, qith properties +a+
+
+
+==== Mapping xml-Files
+
+The same concept can also be applied to xml-files. Consider the following configuration file:
+
+[source,xml]
+.Example.conf
+-------------------------------------------------------
+<config>
+ <default>
+ <a>valA</a>
+ <a.b>valB</a.B>
+ </default>
+
+ <section id="section1">
+ <param id="aa">sectionValA</aa>
+ <param id="aa.b.c">SectionValC</aa.b.c>
+ </section>
+ <section id="section2">
+ <param id="a">val2Section2</aa>
+ </section>
+</config>
+-------------------------------------------------------
+
+This file basically describes the same configuration as the ini-based version we have seen before. The formats
+module hereby ships with 3 format classes:
+
+* +PropertiesFormat+ providing support for .properties files.
+* +PropertiesXmlFormat+ providing support for xml.property files.
+* +IniConfiguratonFormat+ providing support for xml.property files.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_functions.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_functions.adoc b/content/documentation/extensions/mod_functions.adoc
new file mode 100644
index 0000000..6e2c172
--- /dev/null
+++ b/content/documentation/extensions/mod_functions.adoc
@@ -0,0 +1,108 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Functions
+
+toc::[]
+
+[[Core]]
+== Tamaya Functions (Extension Module)
+=== Overview
+
+Tamaya Functions is an extension module. Refer to the link:modules.html[extensions documentation] for further details.
+
+Tamaya Functions provides several functional extensions using the +ConfigOperator,ConfigQuery+ extension points. Most
+functional extension are accessible from the +ConfigurationFunction+ singleton. When importing its methods statically
+one can use the methods to achieve some interesting effects, e.g.
+
+[source,java]
+-------------------------------------------------------------------
+import static org.apache.tamaya.functions.ConfigurationFunctions.*;
+
+Set<String> sections = ConfigurationProvider.getConfiguration().with(areas("a", false).with(transitiveAreas());
+-------------------------------------------------------------------
+
+The expression above returns all fully qualified section names that are child sections of the root section 'a'.
+So given the entries +a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4+ the reult would be +a, a.a, a.b, a.b.c+.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+For using the functionality shown in this document you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-functions</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Provided Functions
+
+==== Functions on +ConfigurationFunctions+
+
+The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton.
+
+* *ConfigOperator filter(PropertyMatcher matcher)* creates a +ConfigOperator+ that creates a +Configuration+
+ containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only
+ the _key_, but also the _value_.
+* *ConfigOperator map(KeyMapper keyMapper)* creates a +ConfigOperator+ that maps the keys as defined
+ by the given _keyMapper_.
+* *ConfigOperator section(String section)* creates a +ConfigOperator+ that creates a +Configuration+ containing only
+ entries that are direct or indirect members of the given section.
+* *ConfigOperator section(String areaKey, boolean stripKeys)* creates a +ConfigOperator+ that creates a +Configuration+
+ containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine
+ if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.
+* *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member
+ of a given section.
+* *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given
+ _key_ is a direct or indirect member of at least one of the given _sectionKeys_.
+* *ConfigQuery<Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
+ also have parameters present).
+* *ConfigQuery<Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
+ including the transitive closure of sections.
+* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
+ qualified section names that are selected by the given _predicate_.
+* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
+ qualified section names that are selected by the given _predicate_, including the transitive closure of sections
+ identified.
+* *ConfigOperator sectionsRecursive(String... sectionKeys)* provides a +ConfigOperator+ that filters all sections identified
+ by the given _sectionKeys_ and its child sections.
+* *ConfigOperator sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +ConfigOperator+
+ that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to
+ determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or
+ absolute (filtering only).
+* *ConfigQuery<String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
+ representation.
+
+
+==== Functions on +PropertySourceFunctions+
+
+The following sections explain the provided functions defined by +PropertySourceFunctions+ singleton.
+
+* *PropertySource addMetaData(PropertySource propertySource, Map<String,String> metaData)* Creates a new +PropertySource+
+ with the given metadata added.
+* *boolean isKeyInSection(String key, String sectionKey)* Checks if the given _key_ is a direct or indirect member of
+ one of the given _sectionKey_.
+* *boolean isKeyInSections(String key, String... sectionKeys)* Checks if the given _key_ is a direct or indirect member of
+ one of one of the given _sectionKeys_.
+* *Set<String> sections(Map<String, String> properties)* Extracts the sections from the given properties.
+* *Set<String> transitiveSections(Map<String, String> properties)* Extracts the transitive sections from the given
+ properties.
+* *Set<String> sections(Map<String, String> properties, final Predicate<String> predicate)* Extracts the sections
+ from the given properties, also filtering with the given predicate.
+* *Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate)* Extracts the transitive
+ sections from the given properties, also filtering with the given predicate.
+* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +PropertySource+
+ only containing the sections that a direct or indirect children of the given _sectionKeys_.
+* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +PropertySource+
+ only containing the sections that a direct or indirect children of the given _sectionKeys_. With _stripKeys_ one can
+ select of the returned values should be relative to its selection of be fully qualified.
+* *String stripSectionKeys(String key, String... sectionKeys)* This function strips away the matching section key as given
+ in _sectionKeys_ from a given _key_.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_injection.adoc b/content/documentation/extensions/mod_injection.adoc
new file mode 100644
index 0000000..941351e
--- /dev/null
+++ b/content/documentation/extensions/mod_injection.adoc
@@ -0,0 +1,430 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Injection
+
+toc::[]
+
+
+[[Core]]
+== Tamaya Injection (Extension Module)
+=== Overview
+
+Tamaya Injection is an extension module. Refer to the link:modules.html[extensions documentation] for further details
+about modules.
+
+Tamaya Injection provides functionality for injecting configured values into beans, or creating configuration
+template instances.
+
+Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate
+code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a
+built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the
+according injection services. This module adds this functionality to Tamaya.
+
+=== Compatibility
+
+The module is based on Java 7, so it can be used with Java 7 and beyond.
+
+=== Installation
+
+Basically Tamaya's injection API is deployed as API artifact:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection-api</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+To use injection with Java SE you must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+Similarly there are other injection implementations available, targetig platforms such as
+
+* Spring, Spring Boot
+* Java EE/CDI
+* OSGI, Apache Felix/Apache Karaf
+
+
+=== Core Concepts
+
+Basically you annotate fields or methods in your beans with +@Config+ to enable configuration injection. Tamaya
+additionally defines further annotations that allo you to define additional aspects such as default values, custom
+converters etc. The following example illustrates the basic functionality:
+code snippet:
+
+[source,java]
+.Annotated Example Class
+--------------------------------------------
+package foo.bar;
+
+public class ConfiguredClass {
+
+ // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
+ private String testProperty;
+
+ // Trying to resolve mutiple keys, with a default value, if none could be resolved
+ @Config({"a.b.c.key1","a.b.legacyKey",area1.key2"}, defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
+ String value1;
+
+ // Typical case
+ @Config("a.b.c.key2")
+ private int value2;
+
+ // resolved by default as foo.bar.ConfiguredClass.accessUrl
+ // Using a (default) String -> URL converter
+ @Config(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
+ private URL accessUrl;
+
+ // Config injection disabled for this property
+ @NoConfig
+ private Integer int1;
+
+ // Overriding the String -> BigDecimal converter with a custom implementation.
+ @Config("BD")
+ @WithPropertyConverter(MyBigDecimalRoundingAdapter.class)
+ private BigDecimal bigNumber;
+
+ ...
+}
+--------------------------------------------
+
+
+When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
+this feature a class must be annotated with +@ConfigAutoInject+:
+
+[source, java]
+. An autoinjected bean class
+--------------------------------------------
+package a.b;
+
+@ConfigAutoInject
+public final class Tenant {
+ private int id;
+ private String name;
+ private String description;
+ @NoConfig // prevents auto injection for this field
+ private String id2;
+
+ public int getId(){
+ return id;
+ }
+ public String getName(){
+ return name;
+ }
+ public String getDescription(){
+ return description;
+ }
+}
+--------------------------------------------
+
+These examples do not show all possibilities provided. Configuring instance of these
+class using Tamaya is very simple: Just pass the instance to Tamaya to let
+Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible):
+
+[source,java]
+.Configuring the +ConfiguredClass+ Instance
+--------------------------------------------
+ConfiguredClass classInstance = new ConfiguredClass();
+ConfigurationInjector.configure(configuredClass);
+
+Tenant tenant = new Tenant();
+ConfigurationInjector.configure(tenant);
+--------------------------------------------
+
+NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
+with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
+documentation.
+
+
+=== The Annotations in detail
+==== The ConfigurationInjector
+
+The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured
+by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed
+hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
+tries to determine configuration for each property of an instance passed, using the following resolution policy:
+
+Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
+[source, listing]
+--------------------------------------------
+a.b.MyClass.myField
+a.b.MyClass.my-field
+MyClass.myField
+MyClass.my-field
+myField
+my-field
+--------------------------------------------
+
+So given the following properties:
+
+[source, properties]
+--------------------------------------------
+a.b.Tenant.id=1234
+Tenant.description=Any kind of tenant.
+name=<unnamed>
+--------------------------------------------
+
+
+==== Accessing Supplier instances
+
+In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
+by the current context. This can be done using +Suppliers+:
+
+[source, java]
+--------------------------------------------
+Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
+ new Supplier<Tenant>(){
+ public Tenant get(){
+ return new Tenant();
+ }
+});
+--------------------------------------------
+
+With Java 8 it's even more simple:
+
+[source, java]
+--------------------------------------------
+Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
+ Tenant::new);
+--------------------------------------------
+
+Hereby this annotation can be used in multiple ways and combined with other annotations such as
++@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+.
+
+==== Minimal Example
+
+To illustrate the mechanism below the most simple variant of a configured class is given:
+
+[source,java]
+.Most simple configured class
+--------------------------------------------
+pubic class ConfiguredItem{
+ @Config
+ private String aValue;
+}
+--------------------------------------------
+
+When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
+the following is happening:
+
+* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
+* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
+ keys are possible).
+* if not successful, an error is thrown (+ConfigException+)
+* On success, since no type conversion is involved, the value is injected.
+
+==== Using @DefaultValue
+
+In the next example we explicitly define the property value:
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
+
+ @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
+ private String aValue;
+}
+--------------------------------------------
+
+==== Inject a DynamicValue Property
+
+Within this example we evaluate a dynamic value. This mechanism allows you to listen for configuration changes and to
+commit new values exactly, when convenient for you.
+
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
+
+ @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
+ private DynamicValue aValue;
+}
+--------------------------------------------
+
+The +DynamicValue+ provides you the following functionality:
+
+[source,java]
+--------------------------------------------
+public interface DynamicValue<T> {
+
+ enum UpdatePolicy{
+ IMMEDIATE,
+ EXPLCIT,
+ NEVER,
+ LOG_AND_DISCARD
+ }
+
+ T get();
+ T getNewValue();
+ T evaluateValue();
+ T commitAndGet();
+ void commit();
+ void discard();
+ boolean updateValue();
+
+ void setUpdatePolicy(UpdatePolicy updatePolicy);
+ UpdatePolicy getUpdatePolicy();
+ void addListener(PropertyChangeListener l);
+ void removeListener(PropertyChangeListener l);
+
+ boolean isPresent();
+ T orElse(T other);
+ // Enabled with Java 8
+ // T orElseGet(ConfiguredItemSupplier<? extends T> other);
+ // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
+
+}
+--------------------------------------------
+
+Summarizing this class looks somehow similar to the new +Optional+ class added with Java 8. It provides
+a wrapper class around a configured instance. Additionally this class provides functionality that gives
+active control, to manage a configured value based on a ++LoadingPolicy+:
+
+* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
+ is automatically applied without any further notice.
+* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
+ returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
+ hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
+ +discard()+.
+* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
+* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
+
+Summarizing a +DynamicValue+ allows you
+
+* to reload actively updates of configured values.
+* update implicitly or explicitly all changes on the value.
+* add listeners that observe changes of a certain value.
+
+Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+. Hereby the value of the
+instance is not changed.
+
+
+==== Ommitting Injection using @NoConfig
+
+Adding the @NoConfig annotation prevents a field or method to be auto-injected from
+configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with auto-confiuration
+turned on as follows:
+
+[source,java]
+--------------------------------------------
+@ConfigAutoInject
+pubic class ConfiguredItem{
+
+ @NoConfig
+ private transient int sum;
+
+ private String a;
+ private String b;
+ Private String c;
+}
+--------------------------------------------
+
+In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
+configuration.
+
+==== Adding custom operators using @WithConfigOperator
+
+The @WithConfigOperator annotation allows you define a class of type +ConfigOperator+, to being applied
+to the final +Configuration+, BEFORE the value is injected. This can be used for various use cases, e.g.
+filtering or validating the visible properties for a certain use case.
+
+[source,java]
+--------------------------------------------
+
+@WithConfigOperator(MyConfigView.class)
+pubic class ConfiguredItem{
+
+ @Config
+ private String a;
+
+}
+--------------------------------------------
+
+
+==== Adding custom property converters using @WithPropertyConverter
+
+The @WithPropertyConverter annotation allows you to define a class of type +PropertyConverter+, to be applied
+on a property configured to convert the String value to the expected injected type. This can be used for
+various use cases, e.g. adding custom formats, config models, decryption.
+
+[source,java]
+--------------------------------------------
+
+pubic class ConfiguredItem{
+
+ @WithPropertyConverter(MyPropertyConverter.class)
+ @Config
+ private String a;
+
+}
+--------------------------------------------
+
+
+==== Defining the loading policy to be applied to configured values using @WithLoadPolicy
+
+The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The +LoadPolicy+
+enum hereby defines the various loading modes.
+
+[source,java]
+--------------------------------------------
+
+@WithLoadPolicy(LoadPolicy.NEVER)
+pubic class BootTimeStableConfig{
+
+ @WithPropertyConverter(MyPropertyConverter.class)
+ @Config
+ private String a;
+
+}
+--------------------------------------------
+
+
+=== Configuration Events
+
+Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
+event backend in use, if and how events are published:
+
+* when you have the CDI extension active events are published using the default CDI event mechanism.
+* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
+* if no event delegation is available no events are published.
+
+The event published is very simple:
+
+[source,java]
+--------------------------------------------
+public interface ConfiguredType {
+ Class getType();
+ String getName();
+ Collection<ConfiguredField> getConfiguredFields();
+ Collection<ConfiguredMethod> getConfiguredMethods();
+ void configure(Object instance, Configuration config);
+}
+
+
+public interface ConfiguredField {
+ Class<?> getType();
+ Collection<String> getConfiguredKeys();
+ String getName();
+ String getSignature();
+ Field getAnnotatedField();
+ void configure(Object instance, Configuration config);
+}
+
+public interface ConfiguredMethod {
+ Collection<String> getConfiguredKeys();
+ Class<?>[] getParameterTypes();
+ Method getAnnotatedMethod();
+ String getName();
+ String getSignature();
+ void configure(Object instance, Configuration config);
+}
+----------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_jodatime.adoc b/content/documentation/extensions/mod_jodatime.adoc
new file mode 100644
index 0000000..4ebae7a
--- /dev/null
+++ b/content/documentation/extensions/mod_jodatime.adoc
@@ -0,0 +1,48 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: JodaTime
+
+toc::[]
+
+[[Core]]
+== Tamaya JodaTime (Extension Module)
+
+=== Overview
+
+Tamaya JodaTime is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time]
+in conjunction with Tamaya. Tamaya JodaTime defines some additional property
+converters to retrieve Joda-Time types from a given configuration.
+
+Refer to the link:modules.html[extensions documentation] for further details
+about modules.
+
+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]
+-----------------------------------------------
+<dependency>
+ <grooupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-jodatime</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+After adding this dependency to your project you can retrieve
+Joda-Time based values directly from a given configuration.
+
+[source,java]
+-----------------------------------------------
+Configuration configuration = ConfigurationProvider.getConfiguration();
+
+DateTime pit = configuration.get("pointInTime", DateTime.class)
+-----------------------------------------------
+
+=== Specifying date and time values
+
+To be written.
+
+=== Specifing periods and durations
+
+To be written.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_json.adoc b/content/documentation/extensions/mod_json.adoc
new file mode 100644
index 0000000..66c12fa
--- /dev/null
+++ b/content/documentation/extensions/mod_json.adoc
@@ -0,0 +1,62 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Builder
+
+toc::[]
+
+
+[[BuilderCore]]
+== Tamaya JSON (Extension Module)
+=== Overview
+
+The Tamaya json module provides support for reading configuration using JSON format:
+
+
+=== Compatibility
+
+The 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-json</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+This extension also transitively requires the +tamaya.formats+ module.
+
+=== Reading configuration in JSON
+
+For reading JSON based onfiguration most easily a +JSONFormat+ can be provided:
+
+[source, java]
+-----------------------------------------------
+ConfigurationData dataRead = ConfigurationFormats.readConfig(
+ getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
+-----------------------------------------------
+
+=== Examples
+
+The JSON module adds instances of +ConfigurationFormat+ so JSON configuration can be read and mapped to the
+according property maps. E.g. the following file is a simple and correct JSON configuration:
+
+[source,listing]
+----------------------------------------------------------------
+{
+ "a" : "A",
+ "b" : "B",
+ "c" : "C",
+ "d" : {
+ "o" : "O",
+ "p" : "P"
+ }
+}
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_management.adoc b/content/documentation/extensions/mod_management.adoc
new file mode 100644
index 0000000..b912747
--- /dev/null
+++ b/content/documentation/extensions/mod_management.adoc
@@ -0,0 +1,92 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: JMX Management Access
+
+toc::[]
+
+
+[[ExtModel]]
+== Tamaya Management (JMX Support) (Extension Module)
+=== Overview
+
+The Tamaya management module provides support for registering a JMX management bean for accessing configuration.
+
+=== Compatibility
+
+The 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-management</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The ManagedConfigMBean bean
+
+The management model defines the MBean of type +ManagedConfigMBean+ as follows:
+
+
+[source,java]
+-----------------------------------------------------------------------------
+public interface ManagedConfigMBean {
+ String getJsonConfigurationInfo();
+ String getXmlConfigurationInfo();
+ Map<String, String> getConfiguration();
+ Map<String, String> getSection(String area, boolean recursive);
+ Set<String> getSections();
+ Set<String> getTransitiveSections();
+ boolean isSectionExisting(String area);
+ default boolean isSectionEmpty(String area);
+}
+-----------------------------------------------------------------------------
+
+* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the
+current configuration.
+* +getConfiguration+ access the current configuration properties.
+* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query
+ will not only return direct children, but also recursively walk down all subsection of the
+ given section key.
+* +getSections+ returns all current known section names.
+* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single
+ entries to the set as well.
+* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
+ section keys.
+
+=== Registering the ManagedConfigMBean
+
+For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the
+following static methods are available:
+
+[source,java]
+-----------------------------------------------------------------------------
+public final class ConfigManagementSupport{
+
+ private JMXSupport(){}
+
+ public static ObjectName registerMBean();
+ public static ObjectName registerMBean(String context);
+ public static ObjectName unregisterMBean();
+ public static ObjectName unregisterMBean(String context);
+}
+-----------------------------------------------------------------------------
+
+* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+
+ and registers it. Optionally an additional _context_ parameter can be passed, which allows
+ to register the management bean for different classloaders, e.g. for different
+ ears.
+* +unregisterMBean+ does the oppsite than registering obviously.
+
+NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the
+ +ServiceContextManager+. So you can replace the bean implementation by registering your
+ overriding implementation using the current +ServiceContext+ (by default using
+ +java.util.ServiceLoader+ and +@Priority+ annotation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_metamodel-staged.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_metamodel-staged.adoc b/content/documentation/extensions/mod_metamodel-staged.adoc
new file mode 100644
index 0000000..cf02806
--- /dev/null
+++ b/content/documentation/extensions/mod_metamodel-staged.adoc
@@ -0,0 +1,58 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Staged PropertySources
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Metamodel: Staged PropertySources (Extension Module)
+=== Overview
+
+The Tamaya Staged PropertySources extension provides a base class and default implementation for loading
+multistaged configuration easily from a common configuration location.
+
+
+=== 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.metamodels</groupId>
+ <artifactId>tamaya-metamodel.staged</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+The component will not register any components. The component basically provides the following options:
+
+* Use it as default configuration extension. Hereby you should define your stages in use by setting the
+ +env.STAGE+ system property with the stages to be loaded in order of precedence (most significant last),
+ e.g. +sys-env,DEFAULTS,TEST,DEVELOPMENT. _Additionally_ you must register
+ +org.apache.tamaya.staged.StagedConfigPropertiesProvider+ as in
+
+--------------------------------------------------------------
+META-INF
+|_service
+ |_org.apache.tamaya.spi.PropertySourceProvider
+--------------------------------------------------------------
+
+Tamaya will then load .properties files from +System.getenv(),
+classpath:DEFAULTS.properties, classpath:TEST.properties+ and
++classpath:DEVELOPMENT.properties+
+
+* For more advanced requirements, such as alternate locations, patterns or formats, you can also extend one of the
+ provided classes (+org.apache.tamaya.staged.StagedConfigPropertiesProvider+,
+ ** +BaseStagedPropertySourceProvider+). Extending provides features such as:
+
+ ** Defining a prefix for all entries provided/loaded.
+ ** Using alternate locations or formats.
+ ** Defining the ordinals used.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_model.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_model.adoc b/content/documentation/extensions/mod_model.adoc
new file mode 100644
index 0000000..e454eb1
--- /dev/null
+++ b/content/documentation/extensions/mod_model.adoc
@@ -0,0 +1,451 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Model Documentation and Validation
+
+toc::[]
+
+
+[[ExtModel]]
+== Tamaya Model Documentation and Validation (Extension Module)
+=== Overview
+
+The Tamaya model module provides support for documenting configuration and validating configuration read and processed
+against this model. Documentation and config models can be provided in different ways:
+
+* as separate meta-model documents
+* by providers that check classes/packages for configuration annotations (planned)
+
+
+=== 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-model</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Describing the Configuration Meta-Model
+
+Basically configuration is modelled using key, value-pairs. Looking at a keys
++a.b.c.param1+ and +a.b.c.param2+ the following concepts can be used to defined/describe
+configuration:
+
+. the _configuration section:_ In our case this equals to +a.b.c+, which itself also includes the
+ transitive entries +a.b+ and +a+.
+. the _configuration parameter:_ Basically parameters are adressed using their fully qualified names,
+ which equals to the containing section name and the relative parameter name, separated by the dor separator.
+ In the above example +a.b.c.param1+ and +a.b.c.param2+ are the fully qualified parameter names.
+
+Now with only these 2 concepts a simple configuration meta-model can be defined as
+
+* a meta-model's name, used just for grouping different meta-models and entries to better separate
+ descriptions, e.g. in a management console or generated configuration documentation site.
+* a set of sections.
+* a set of parameters.
+* Both, sections (+.model.target=Section+) as well as parameter models (+.model.target=Parameter+)
+ ** can be modelled by a meta-data entry, by default +_my.config.key.model+.
+ ** may be required, or optional (+.model.required=true|false+)
+ ** may have an optional description
+* Parameters additionally have
+ ** a _type_ (+.model.type=Classname+), described by the fully qualified class name, into which any configured (String)
+ value must be convertable into. If no type is configured +java.ui.lang.String+ is assumed as default.
+ ** an optional regular expression that can be used to validate the +String+ values returned from a
+ configuration (+.model.expression=regexpression+).
+
+Given these concepts a configuration can be fully described. Entries that are not contained in one of the given
+sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of
+a section), are called _undefined_. Undefined parameters should be grouped with its parent section. Each section, as
+well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and
+only if
+
+. the section itself is (directly) _undefined_
+. the section is not a _super section_ of a defined section.
+
+As en example the section definition of +a.b.c+ also implicitly includes the sections +a.b+ and +a+ to be defined
+sections, despite the fact that section properties, such as description and custom configModels are not inherited to
+its parent, or child section.
+
+
+=== Defining Meta-Configuration Model
+
+The configuration meta-model is defined by simple configuration meta-data entries. The section for all model
+configuration by default is called +model+, which results in entries such as +_my.config.key.model.target=Section+.
+Within this section fully qualified configuration keys defines
+which part of the configuration is targeted by certain entries.
+
+==== Defining Sections
+
+First we start to define some configuration sections, the example below starts with the most important
+variants supported:
+
+[source,listing]
+-------------------------------------------------------------------------------
+# Metamodel information
+_model.provider=ConfigModel Extension
+
+# org.mycompany.root (optional section)
+_org.mycompany.root.model.target=Section
+_org.mycompany.root.model.description=Root section defining my company configuration.
+
+# org.mycompany.security (required section)
+_org.mycompany.security.model.target=Section
+_org.mycompany.security.model.required=true
+_org.mycompany.security.model.description=Security related settings.\
+ refer for further details to XXX.
+
+# minmal section
+_minimal.model.target=Section
+
+# custom validated section
+_validated.model.target=Section
+_validated.model.validator=org.apache.tamaya.model.TestValidator
+-------------------------------------------------------------------------------
+
+Above +org.mycompany.root+ transitively defines 3 sections:
+
+* org
+* org.mycompany
+* org.mycompany.root
+
+All sections are optional. Additionally the model above also defines a required section +org.mycompany.security+.
+Required sections are checked so the section is not empty. It is not checked for any specific parameter hereby,
+only the existance of any child parameter is validated.
+
+The _class_ attribute has to be defined for any section definition, because if not set a model entry is, by default,
+defined to be a parameter configModel entry. Given above the entry for the section +minimal+ shows such a minimal
+entry.
+
++validated+ defines a section, which is validated through a customizable validator. Hereby an ordered list of validators
+can be provided, separated by commas.
+
+
+==== Defining Parameters
+
+Similarly parameters also can be defined:
+
+[source,listing]
+-------------------------------------------------------------------------------
+# org.mycompany.root.name (required parameter)
+_org.mycompany.root.name.model.target=Parameter
+_org.mycompany.root.name.model.required=true
+_org.mycompany.root.name.model.description=The company's name, also used in the application's main header.
+
+# org.mycompany.security (required parameters)
+_org.mycompany.security.uid.model.required=true
+_org.mycompany.security.uid.model.description=The user id.
+_org.mycompany.security.realm.model.required=true
+_org.mycompany.security.realm.model.validator=org.apache.tamaya.model.RealmValidator
+_org.mycompany.security.realm.model.description=The security realm required.
+_org.mycompany.security.tokenid.model.description=The token id, if the token service is used (optional).
+
+# A minmal parameter
+_minimalClass.model.target=Class
+-------------------------------------------------------------------------------
+
+Similarly as when defining section also parameter entries define transitively its containing sections. E.g.
+the entry above for +org.mycompany.security.realm+ also defines the following sections (as optional).
+
+* org
+* org.mycompany
+* org.mycompany.security
+
+Additional entries for section, e.g. configModels to be done, can be added as described in the previous section,
+but are optional.
+
+Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it's
+parameter type to be defined. In the example above we define a parameter +minimalClass+ of type +Class+.
+Types hereby are fully qualified class names, whereas as 'java.ui.lang' for built-in language types can be
+ommitted.
+
+==== Model Locations
+
+By default the configuration model can be defined at the following locations:
+
+* +classpath*:META-INF/configmodel.properties+, separate to the current +Configuration+. This functionality is enabled
+ by default, but can be disabled by adding +org.apache.tamaya.model.default.enabled=false+ to your current
+ +Configuration+.
+* +implicitly as part of the current +Configuration+. THis can be disabled by setting
+ the +org.apache.tamaya.model.integrated.enabled+ configuration poarameter to +false+.
+* customized by configuring the +org.apache.tamaya.model.resources+ in the current +Configuration+. This
+ parameter allows to define the locations from where the model extension is trying to read the
+ model configuration. If the _resources extension_ is available in your system it is used to
+ evaluate the locations. If not the default +Classloader.getResources+ command is issued. Also it
+ is required that the _formats extension_ is available, since this is used to effectively read the
+ data. This extension also allows you to use alternate representation formats such as +ini, xml, yml, json+.
+
+
+=== Tracking Configuration Access
+
+The model module also allows tracking which code accesses configuration properties or configuration parameters.
+It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly
+ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length.
+The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+
+instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage
+statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+.
+
+Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+.
++ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status.
+
+The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing:
+
+* the access point (+fqn.ClassName#method(line: xxx)+).
+* the number of accesses
+* the first an last access
+* the values read
+* the access stacktrace (filtered by ignored packages).
+
+[source,java]
+-----------------------------------------------------------
+public final class Usage {
+ [...]
+ public String getKey();
+ public void clearMetrics();
+ public int getReferenceCount();
+ public int getUsageCount();
+ public Collection<AccessDetail> getAccessDetails(Class type);
+ public Collection<AccessDetail> getAccessDetails(Package pack);
+ public Collection<AccessDetail> getAccessDetails(String lookupExpression);
+ public Collection<AccessDetail> getAccessDetails();
+ public void trackUsage(String value);
+ public void trackUsage(String value, int maxTraceLength);
+
+
+ public static final class AccessDetail {
+ [...]
+ public void clearStats();
+ public long trackAccess(String value);
+ public long getAccessCount();
+ public String getAccessPoint();
+ public long getFirstAccessTS();
+ public long getLastAccessTS();
+ public String[] getStackTrace();
+ public Map<Long, String> getTrackedValues();
+ }
+
+}
+-----------------------------------------------------------
+
+With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main
+singleton for configuration statistics is defined as follows:
+
+[source,java]
+-----------------------------------------------------------
+public final class ConfigUsageStats{
+ public static Set<String> getIgnoredUsagePackages();
+ public static void addIgnoredUsagePackages(String... packageName);
+ public static void enableUsageTracking(boolean enabled);
+ public static Usage getUsage(String key);
+ public static Collection<Usage> getUsages();
+ public static void clearUsageStats();
+ public static Usage getUsageAllProperties();
+ public static boolean isUsageTrackingEnabled();
+ public static String getUsageInfo();
+}
+-----------------------------------------------------------
+
+==== Customizing the Stacktrage for Usage Reporting
+
+The stacktrace tracked by the system can be customized in several ways:
+
+* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names.
+* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a
+ negative value will disable stacktrace logging completelely.
+
+
+=== Accessing Usage Statistics
+
+Bascially usage statistics are available in two forms:
+
+* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+
+ singleton.
+* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics
+ can be obtained, as illustrated below (a snipped from the current test output):
+
+[source,listing]
+-----------------------------------------------------------
+Apache Tamaya Configuration Usage Metrics
+=========================================
+DATE: Sat Apr 30 21:51:09 CEST 2016
+
+220 <<all>>:
+ - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+3 java.version:
+ - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+ - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
+
+-----------------------------------------------------------
+
+
+==== Programmatic API
+
+Basically the configModel module provides a simple API to access the defined +ConfigModel+ instances and
+validating the current +Configuration+ against the models as follows:
+
+[source,java]
+-----------------------------------------------------------
+public final class ConfigModelManager {
+
+ private ConfigModelManager() {}
+
+ public static Collection<ConfigModel> getModels();
+ public static Collection<ConfigModel> findModels(ModelType type, String namePattern);
+ public static <T extends ConfigModel> T getModel(String name, Class<T> modelType);
+ public static Collection<ConfigModel> findModels(String namePattern);
+
+ public static Collection<ValidationResult> validate();
+ public static Collection<ValidationResult> validate(boolean showUndefined);
+ public static Collection<ValidationResult> validate(Configuration config);
+ public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined);
+
+ public static void registerMBean();
+ public static void registerMBean(String context);
+
+}
+-----------------------------------------------------------
+
+This singleton allows to validate the current or any +Configuration+ instance. All the ConfigModels read also are
+available from the +getModels+ method. This models can be used to provide documentation, e.g. as part of a CLI interface
+or shown on a documentation web server.
+
+A +ConfigModel+ hereby is defined as one single part of configuration, typically corresponding to a specific concern
+of your system. As an example you can define different models for different modules or products plugged together.
+With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a
+single configuration source (e.g. for configuring the machine's IP address and subnet settings only once.
+
+[source,java]
+-----------------------------------------------------------
+public interface ConfigModel {
+
+ ModelTarget getType();
+ String getName();
+ String getProvider();
+ boolean isRequired();
+ String getDescription();
+ Collection<ValidationResult> validate(Configuration config);
+}
+-----------------------------------------------------------
+
+
+Hereby +ModelTarget+ defines more details on the kind of model:
+
+[source,java]
+-----------------------------------------------------------
+public enum ModelTarget {
+ /**
+ * A configuration section.
+ */
+ Section,
+ /**
+ * A configuration paramter.
+ */
+ Parameter,
+ /**
+ * ConfigModel that is a container of other validations.
+ */
+ Group
+}
+-----------------------------------------------------------
+
+A +ValidationResult+ models one validation executed by a +ConfigModel+ on a certain +Configuration+ instance:
+
+[source,java]
+-----------------------------------------------------------
+public final class ValidationResult {
+
+ public static ValidationResult ofValid(ConfigModel configModel);
+ public static ValidationResult ofMissing(ConfigModel configModel);
+ public static ValidationResult ofMissing(ConfigModel configModel, String message);
+ public static ValidationResult ofError(ConfigModel configModel, String error);
+ public static ValidationResult ofWarning(ConfigModel configModel, String warning);
+ public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage);
+ public static ValidationResult ofDeprecated(ConfigModel configModel);
+ public static ValidationResult ofUndefined(final String key);
+ public static ValidationResult of(ConfigModel configModel, ValidationState result, String message);
+
+ public ConfigModel getConfigModel();
+ public ValidationState getResult();
+ public String getMessage(),
+}
+-----------------------------------------------------------
+
+The result of a complete validation on a concrete +Configuration+ instance finally is mapped as a
++Collection<ValidationResult>+, refer to the methods on +ConfigModelManager+.
+
+
+=== Auto-Documentation of Classes with Configuration Injection
+
+A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
+(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
+models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
+time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
+behaviour. Nevertheless this means that after your system has been started you should have access to a complete
+set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
+(through injection).
+
+
+== Model SPI
+=== Registering Configuration Models
+
+The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is
+the +ModelProviderSpi+ interface, which allows any kind of additional config models to be added to the system:
+
+[source,java]
+-----------------------------------------------------------
+public interface ModelProviderSpi {
+
+ Collection<ConfigModel> getConfigModels();
+
+}
+-----------------------------------------------------------
+
+New instances implementing this interface must be registered into the current +ServiceContext+, by default the
++ServiceLoader+ is used.
+
+
+=== The ConfigUsageStatsSpi
+
+The methods for managing and tracking of configuration changes are similarly delegated to an
+implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI.
+By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking
+logic can be adapted or replaced.
+
+=== Other Utility Classes
+
+The module also provides further utility classes that may be useful for implementing models or testing:
+
+* +AbstractModel+ provides a base class that can be extended, when implementing +ConfigModel+.
+* +AreaConfigModel+ provides a +ConfigModel+ implementation (with a corresponding +Builder+) to model the
+ requirement of certain configuration sections being present, or opionally present, in the model.
+* +ParameterModel+ provides an implementation base class for validating parameters on existence and compliance
+ with a regular expression.
+* +ConfigDocumentationMBean+ is the MBean registered that models similar functionality as +ConfigModelManager+.
+* +ConfigModelGroup+ provides a +ConfigModel+ that groups several child models.
+* +ConfigModelReader+ allows to read +ConfigModels+ from properties files as described at the beginning of this
+ document.
+
+
+=== Switches to enable/disable functionality
+
+The model module provides different switches that can be used to activate or deactivate features:
+
+* +tamaya.model.integrated.enabled+ allows to deactivate reading inline metaconfiguration delivered with
+ the normal Tamaya Configuration. By default inline entries (+_.abcd.model.*+) are evaluated.
+* +tamaya.model.default.enabled+ allows to deactivate reading metamodel information from
+ +classpath:META-INF/configmodel.properties+. By default it is active.
+* +tamaya.model.resources+ allows to define additional resources (loaded through the resources extension),
+ that can be used to read metamodel information in any format using Tamaya's format module.
+* the system property +tamaya.model.autoModelEvents+ allows to activate/deactivate the automatic
+ documentation of classes configured and published by Tamaya +ConfiguredType+ event instances (e.g. published by
+ Tamaya's injection modules).
[02/10] incubator-tamaya-site git commit: TAMAYA-177: Add basic about
contents.
Posted by po...@apache.org.
TAMAYA-177: Add basic about contents.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/c74a60dc
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/c74a60dc
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/c74a60dc
Branch: refs/heads/master
Commit: c74a60dc79bc707347faf4ba8d15ae6578286773
Parents: e2de92d
Author: Phil Ottlinger <po...@apache.org>
Authored: Sun Dec 18 23:26:31 2016 +0100
Committer: Phil Ottlinger <po...@apache.org>
Committed: Sun Dec 18 23:26:31 2016 +0100
----------------------------------------------------------------------
content/about.html | 30 +++++++++++++++++++++---------
1 file changed, 21 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/c74a60dc/content/about.html
----------------------------------------------------------------------
diff --git a/content/about.html b/content/about.html
index 5c9e36d..617e7fb 100644
--- a/content/about.html
+++ b/content/about.html
@@ -1,14 +1,26 @@
title=About
-date=2013-09-24
+date=2016-12-18
type=page
status=published
~~~~~~
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vel diam purus. Curabitur ut nisi lacus.
-Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu,
-mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo
-ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet
-ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus,
-id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In
-consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere
-libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat.
+Tamaya provides a flexible and powerful Configuration Solution for Java developers using Java SE as well as for more complex usage scenarios like Cloud or Java EE. It provides a modern type-safe property based Configuration API combined with a powerful environment model and a flexible SPI.
+
+Rationale
+Configuration is one of the most prominent cross-cutting concerns similar to logging. Most of us already have been writing similar code again and again in each of our projects. Sometimes in a similar way but mostly always slightly different, but certainly with high coupling to your configuration backends. Given your code is reused or integrated some how, or deployed by some customers, struggling starts: not supported backends, different policies, missing combination and validation mechanisms and so on. Tamaya solves all this by defining a common API and backend SPI. Your code is decoupled from the configuration backend. There is no difference if your code is deployed on your dev box or in a clustered Docker environment in production, it stays the same!
+
+Features
+Unified Configuration API
+Pluggable Configuration Backends
+Enforceable Configuration Policies
+Configuration Validation and Documentation
+Seemless Enterprise Integration
+
+Quickstart
+Using Apache Tamaya is simple:
+
+Add org.apache.tamaya:tamaya-core:0.2-incubating to your dependencies.
+Add your config to META-INF/javaconfiguration.properties
+Access your configuration by ConfigurationProvider.getConfiguration() and use it.
+Look at the extension modules to customize your setup!
+Enjoy!
[03/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_resolver.adoc b/content/extensions/mod_resolver.adoc
deleted file mode 100644
index 366c97e..0000000
--- a/content/extensions/mod_resolver.adoc
+++ /dev/null
@@ -1,126 +0,0 @@
-: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/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_resources.adoc b/content/extensions/mod_resources.adoc
deleted file mode 100644
index 3081149..0000000
--- a/content/extensions/mod_resources.adoc
+++ /dev/null
@@ -1,155 +0,0 @@
-: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/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_server.adoc b/content/extensions/mod_server.adoc
deleted file mode 100644
index 025da45..0000000
--- a/content/extensions/mod_server.adoc
+++ /dev/null
@@ -1,366 +0,0 @@
-: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/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_spi-support.adoc b/content/extensions/mod_spi-support.adoc
deleted file mode 100644
index 7aca208..0000000
--- a/content/extensions/mod_spi-support.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-: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/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_spring.adoc b/content/extensions/mod_spring.adoc
deleted file mode 100644
index 3960dc1..0000000
--- a/content/extensions/mod_spring.adoc
+++ /dev/null
@@ -1,134 +0,0 @@
-: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/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_yaml.adoc b/content/extensions/mod_yaml.adoc
deleted file mode 100644
index b7e53cb..0000000
--- a/content/extensions/mod_yaml.adoc
+++ /dev/null
@@ -1,112 +0,0 @@
-: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/quickstart.adoc
----------------------------------------------------------------------
diff --git a/content/quickstart.adoc b/content/quickstart.adoc
deleted file mode 100644
index 14ab438..0000000
--- a/content/quickstart.adoc
+++ /dev/null
@@ -1,189 +0,0 @@
-: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.
-
-|===
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/source.adoc
----------------------------------------------------------------------
diff --git a/content/source.adoc b/content/source.adoc
deleted file mode 100644
index 441bec8..0000000
--- a/content/source.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-:sectnums: yes
-
-= Apache Tamaya: Sources
-
-== Source Code Repositories
-
-The current source code can be found at:
-
- - http://git-wip-us.apache.org/repos/asf/incubator-tamaya.git (read-only)
- - https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git
-
-Alternatively there is also a GitHub read-only mirror at
-https://github.com/apache/incubator-tamaya[https://github.com/apache/incubator-tamaya^].
-
-The GitHub mirror also provides the project as downloadable zip archive.
-
-== Contributions
-
-If you like to contribute to Apache Tamaya please also refer also to our
-<<devguide.adoc#contributing-workflow,section on contributing to Apache Tamaya>>.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/usecases.adoc
----------------------------------------------------------------------
diff --git a/content/usecases.adoc b/content/usecases.adoc
deleted file mode 100644
index 0d0d4e0..0000000
--- a/content/usecases.adoc
+++ /dev/null
@@ -1,488 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-== Apache Tamaya: Use Cases and Requirements
-
-toc::[]
-
-== Use Cases
-
-=== Simple Access
-
-Users want to be able to access configuration in a unified way both in SE and EE. EE may provide additional
-mechanism, such as injection, but the SE mechanisms should work as well, so any code written in SE is fully
-portable to EE as well.
-This can only be achieved by providing a static accessor, e.g.
-
-[source,java]
-------------------------------------------------------------
-Configuration config = Configuration.current();
-------------------------------------------------------------
-
-The call above should work exactly the same in EE. To enable this the static call must be delegated in the
-internals of the singleton, depending on the runtime. In EE the executing component can behave contextually,
-or even be loaded within the CDI environment (at least for post loading, application runtime aspects, but not earlier).
-
-Additionally in EE it should also be possible to inject Configuration, which gives you the same results as the call
-above:
-
-[source,java]
-------------------------------------------------------------
-@Inject
-private Configuration cfg;
-------------------------------------------------------------
-
-
-=== Simple Lookup of Properties
-
-Users just want to create a configuration ad hoc, from given property files. The
-files could be locally in the file system, on the classpath.
-
-Tamaya should provide a simple Java API for accessing key/value based configuration. Hereby users want to access
-properties as simple String values.
-
-Hereby returning Java 8 Optional values must be considered as well, instead of returning +null+.
-
-
-=== Value Placeholders
-
-Users just want to to be able to add placeholders to the values of configuration (not the keys). The mechanisms for
-resolving the placeholders hereby should be not constraint to one single lanmguage like EL. Instead of different
-replacement strategies should be selectable, e.g. by prefixing an expression with the name of the resolver that
-should do the work (eg +"blabla ${env:HOME} using Java version ${sys:java.version}."+.
-This allows resolution mechanism to be isolated easily and also allows to use simpler mechanisms, if no more complex
-ones like EL are required. This is especially useful to deal with low resource environment like ME.
-
-
-=== Type Safe Properties
-
-Users just want to access properties not only as Strings, but let Tamaya do the conversion to the required
-or the configred target type. By defauklt all java.ui.lang wrapper and primitive types should be supported, but also
-other common types like date/time types, math numeric types and more.
-
-It must be possible that users can register their own custom types.
-
-Finally users also want to be able to dynamically provide or override type adaption (conversion), when reading a value,
-for a certain key/value pair.
-
-
-=== Configuration Templates
-
-Users want to be able to let Tamaya implement an interface template based on configuration.
-This use case is pretty similar to the injection use case. Basically the values are not injected,
-but cached within the template proxy returned, e.g. as +DynamicValue+.
-Similarly it could even be possible to define callback methods (default methods)
-or register listeners to DynamicValue instances returned.
-
-Templates hereby can easily be managed, but provide a excellent mechanism to provide type-safe configuration
-to clients in a very transparent way. Details can be controlled by using the same annotations as for
-normal configuration injection.
-
-
-=== Java 8 Functional Support
-
-Users want to be able to benefit from the new programming styles introduced with Java 8. Configuration
-should provide extension points for different aspects, where additional code can be hooked in easily.
-In short: were possible functional interfaces should be modelled.
-
-Examples:
-
-* code that converts a configuration to another kind of configuration: +UnaryOperator<Configuration>+
-* code that creates any kind of result based on a configuration: +Function<Configuration,T>+
-* Adapters for type conversion are defined as +Function<String,T>+
-* Key, value filters ccan be modelled as +BiFunction<String,String,String>+
-* etc.
-
-
-=== Configuration Locations
-
-Users want to be able to
-
-* read configuration from different locations.
-* By default classpath and file resources are
- supported. But similarly remote access using a JSON ReST call should be possible.
-* Tamaya should define a JSON and XML format for configuration.
-* Configuration locations should be scannable using ant-styled resource patterns, if possible.
-* Scanning and reading logic can be modularized by using a +ConfigReader+ interface.
-
-
-=== Configuration Formats
-
-Users want to be able to use the format they prefer.
-
-* properties, xml-properties and ini-format should be supported by default
-* Other/custom formats should be easily addable by registering or providing the format on configuration evaluation (read).
-* When possible Tamaya should figure out which format to be used and how the InputStream should be correctly
- interpreted.
-
-
-=== Multiple Configurations
-
-When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional
-aspects to be considered by a configuration system.
-
-* Different code modules, libraries, plugins or products want to have their "own" separated configuration.
-* Similar it should be possible to add fully specific additional configurations.
-
-The default configuration hereby should always be present, whereas additional configurations are optional.
-Users want to be able to check the availability of such an additional configuration.
-
-Of course, additional configuration must be identifiable. The best way to do is to be discussed, nevertheless the
-mechanism must not depend on Java EE and the identifying keys must be serializable easily.
-Basically simple names are sufficient and woukld provide exact this required functionality.
-
-
-=== External Configuration
-
-Users want to be able to replace, override, extend or adapt any parts or all of an existing configuration from
-external sources.
-This also must be the case for multi-context environments, where the context identifiers are
-the only way to link to the correct remote configuration.
-
-
-=== Context Dependent Configuration
-
-In multi tenancy setups or complex systems a hierarchical/graph model of contexts for configurations is required, or different runtime contexts are executed in parallel
-within the same VN. What sounds normal for EE also may be the case for pure SE environments:
-
-* Users want to be able to model different layers of runtime context
-* Users want to identify the current layer, so configuration used may be adapted.
-
-
-
-=== Dynamic Provisioning (UC8)
-
-In Cloud Computing, especially the PaaS and SaaS areas a typical use case would be that an application (or server)
-is deployed, configured and started dynamically. Typically things are controlled by some "active controller components",
-which are capable of
-
-* creating new nodes (using IaaS services)
-* deploying and starting the required runtime platform , e.g. as part of a PaaS solution.
-* deploying and starting the application modules.
-
-All these steps require some kind of configuration. As of today required files are often created on the target node
-before the systems are started, using proprietary formats and mechanism. Similarly accessing the configuration in place
-may require examining the file system or using again proprietary management functions. Of course, a configuration
-solution should not try to solve that, but it can provide a significant bunch of functionality useful in such scenarios:
-
-* provide remote capabilities for configuration
-* allow configuration to be updated remotely.
-* allow client code to listen for configuration changes and react as needed.
-
-
-=== Minimal Property Source SPI
-
-Users expect that implementing an additional configuration property source is as easy as possible.
-So there should be an SPI defined that allows any kind of data source to be used for providing configuration data.
-The interface to be implemented is expected to be minimal to reduce the implementation burden. Default
-methods should be used where possible, so only a few methods are expected to be required to implement.
-
-
-=== Scannable Properties
-
-If possible configuration should be scannable, meaning it should be possible to evaluate the keys available.
-The corresponding capabilities should be accessible by a +isScannable()+ method.
-
-
-=== Combine Configurations
-
-Users want to be able to combine different configurations to a new configuration instance.
-Hereby the resulting configuration can be
-
-* a union of both, ignoring duplicates (and optionally log them)
-* a union of both, duplicates are ignored
-* a union of both, conflicts are thrown as ConfigException
-* an intersection of both, containing only keys present and equal in both configurations
-* an arbitrary mapping or filter, modelled by an +CombinationPolicy+, which basically can be modelled
- as +BiFunction<String, String, String>+, hereby
- ** a result of +null+ will remove the key
- ** any other result will use the value returned as final value of the combination.
-
-
-=== MX/ReST Management
-
-Users want to be have comprehensive management support, which should allow
-
-* to change configuration
-* to remove configuration
-* to view configuration and its provider details
-
-
-=== Adaptable Service Context
-
-Tamaya should support an adaptable +ServiceContext+ to resolve any kind of implememntation services, both API services as core
-framework services. The +ServiceContext+ should be dynamically replecable by configuring an alternate instance of
-using the Java *ServiceContet+.
-
-This decouples component usage from its load and management part and als greatly simplifies integration with
-new/alternate runtime environments.
-The service context is exptected to provide
-
-* single singleton instances: these service can be cached.
-* access to multiple instances which implement some commons SPI interface.
-* as useful priorization of components is done by the model itself.
-
-
-=== Configuration Injection
-
-Users want to be able to polulate configured items by injecting configured values. Hereby
-
-* the lifecycle of the instances is not managed by Tamaya
-* all references to items configured are managed as weak references, to prevent memoryleaks.
-* Injection should if possible evaluate the properties by defaults. Even properties without
- any annotations are possible.
-* Users expect to exclude certain properties from calculation
-* Beside injection of properties it is also possible to call setter methods with one parameter similarly.
-* Basically injection is performed, when the instance is passed to the Tamaya configuration system. It should also
- be possible to inject/provide final values, especially Strings. Changes on configured values should be
- reflected in the current value. Setters methods similarly can be called again, with the new values, on changes.
-* Users expect to control dynamic values and recall of setter methods, basically the following strategies should be
- supported:
- ** inject only once and ignore further changes.
- ** reinject/reinitialize on each change
-
-* Dynamic Values can easily be modeled as +ConfiguredValue+ instances, which should have the following functionality:
- ** access the current value
- ** access the new value
- ** access the latest value access time in ms
- ** access the latest value update time in ms
- ** evaluate easily if the value has changed since the last access
- ** accept the change
- *** as a shortcut it should be possible to accept the change on access of the value implicitly, hereby always accessing
- the latest valid value.
- ** ignore the change
- ** register +Consumer<DynamicValue>+ liasteners to listen on the changes (ans also removing them later again).
-
-All observing functionality can be done completely asynchronously and in parallel.
-
-
-[[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-site/blob/ede865e4/templates/menu.thyme
----------------------------------------------------------------------
diff --git a/templates/menu.thyme b/templates/menu.thyme
index 036d68c..eea628e 100644
--- a/templates/menu.thyme
+++ b/templates/menu.thyme
@@ -19,15 +19,29 @@
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Home</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'quickstart.html'">Quickstart</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Documentation</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'/apidocs/index.html'">API</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Development</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Releases</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'about.html'">About</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'sitemap.xml'">Sitemap</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+${config.feed_file}">Subscribe</a></li>
-<!--
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/usecases.html'">Use Cases and Requirements</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/quickstart.html'">Quickstart</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/api.html'">API</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/core.html'">Core</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/extensions.html'">Extension Guide</a></li>
+ <li class="divider"></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'apidocs/index.html'">Javadoc ${tamaya_version} (external)</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'development/source.html'">Sources</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'development/community.html'">Community</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'devguide.html'">Development Guide</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'release-guide.html'">Release Guide</a></li>
+ </ul>
+ </li>
+<!-- Example:
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a>
<ul class="dropdown-menu">
@@ -41,6 +55,8 @@
</ul>
</li>
-->
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'sitemap.xml'">Sitemap</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+${config.feed_file}">Subscribe</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
[06/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
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.
+
+|===
[09/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
TAMAYA-178: Fix menu structure
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/ede865e4
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/ede865e4
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/ede865e4
Branch: refs/heads/master
Commit: ede865e4d7623bd7622e1f6c03312a8ee0e11752
Parents: c74a60d
Author: Phil Ottlinger <po...@apache.org>
Authored: Sun Dec 18 23:26:49 2016 +0100
Committer: Phil Ottlinger <po...@apache.org>
Committed: Sun Dec 18 23:26:49 2016 +0100
----------------------------------------------------------------------
content/api.adoc | 687 -------------------
content/blog/2016/fourth-post.adoc | 17 +-
content/blog/2016/third-post.adoc | 16 +-
content/community.adoc | 123 ----
content/core.adoc | 214 ------
content/development/community.adoc | 123 ++++
content/development/source.adoc | 23 +
content/documentation/api.adoc | 687 +++++++++++++++++++
content/documentation/core.adoc | 214 ++++++
content/documentation/extensions.adoc | 62 ++
.../documentation/extensions/mod_builder.adoc | 83 +++
content/documentation/extensions/mod_camel.adoc | 129 ++++
content/documentation/extensions/mod_cdi.adoc | 217 ++++++
.../extensions/mod_classloader_support.adoc | 75 ++
.../extensions/mod_collections.adoc | 232 +++++++
.../documentation/extensions/mod_consul.adoc | 59 ++
.../extensions/mod_environment.adoc | 42 ++
content/documentation/extensions/mod_etcd.adoc | 189 +++++
.../documentation/extensions/mod_events.adoc | 278 ++++++++
.../documentation/extensions/mod_filter.adoc | 119 ++++
.../documentation/extensions/mod_formats.adoc | 206 ++++++
.../documentation/extensions/mod_functions.adoc | 108 +++
.../documentation/extensions/mod_injection.adoc | 430 ++++++++++++
.../documentation/extensions/mod_jodatime.adoc | 48 ++
content/documentation/extensions/mod_json.adoc | 62 ++
.../extensions/mod_management.adoc | 92 +++
.../extensions/mod_metamodel-staged.adoc | 58 ++
content/documentation/extensions/mod_model.adoc | 451 ++++++++++++
.../extensions/mod_mutable_config.adoc | 267 +++++++
.../documentation/extensions/mod_optional.adoc | 54 ++
content/documentation/extensions/mod_osgi.adoc | 116 ++++
.../documentation/extensions/mod_remote.adoc | 115 ++++
.../documentation/extensions/mod_resolver.adoc | 126 ++++
.../documentation/extensions/mod_resources.adoc | 155 +++++
.../documentation/extensions/mod_server.adoc | 366 ++++++++++
.../extensions/mod_spi-support.adoc | 57 ++
.../documentation/extensions/mod_spring.adoc | 134 ++++
content/documentation/extensions/mod_yaml.adoc | 112 +++
content/documentation/quickstart.adoc | 189 +++++
content/documentation/usecases.adoc | 488 +++++++++++++
content/extensions.adoc | 62 --
content/extensions/mod_builder.adoc | 83 ---
content/extensions/mod_camel.adoc | 129 ----
content/extensions/mod_cdi.adoc | 217 ------
content/extensions/mod_classloader_support.adoc | 75 --
content/extensions/mod_collections.adoc | 232 -------
content/extensions/mod_consul.adoc | 59 --
content/extensions/mod_environment.adoc | 42 --
content/extensions/mod_etcd.adoc | 189 -----
content/extensions/mod_events.adoc | 278 --------
content/extensions/mod_filter.adoc | 119 ----
content/extensions/mod_formats.adoc | 206 ------
content/extensions/mod_functions.adoc | 108 ---
content/extensions/mod_injection.adoc | 430 ------------
content/extensions/mod_jodatime.adoc | 48 --
content/extensions/mod_json.adoc | 62 --
content/extensions/mod_management.adoc | 92 ---
content/extensions/mod_metamodel-staged.adoc | 58 --
content/extensions/mod_model.adoc | 451 ------------
content/extensions/mod_mutable_config.adoc | 267 -------
content/extensions/mod_optional.adoc | 54 --
content/extensions/mod_osgi.adoc | 116 ----
content/extensions/mod_remote.adoc | 115 ----
content/extensions/mod_resolver.adoc | 126 ----
content/extensions/mod_resources.adoc | 155 -----
content/extensions/mod_server.adoc | 366 ----------
content/extensions/mod_spi-support.adoc | 57 --
content/extensions/mod_spring.adoc | 134 ----
content/extensions/mod_yaml.adoc | 112 ---
content/quickstart.adoc | 189 -----
content/source.adoc | 23 -
content/usecases.adoc | 488 -------------
templates/menu.thyme | 32 +-
73 files changed, 6205 insertions(+), 6192 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/api.adoc
----------------------------------------------------------------------
diff --git a/content/api.adoc b/content/api.adoc
deleted file mode 100644
index 1dd1d41..0000000
--- a/content/api.adoc
+++ /dev/null
@@ -1,687 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-[[CoreDesign]]
-== Apache Tamaya: API
-
-Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
-that are 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.
- ** +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.
- ** +ConfigurationContext+, which provides a container for all the artifacts needed to build up a +Configuration+.
- For example a context contains the property sources, property filters, converters and combination policy used.
- Also the ordering of the property sources is defined by the context. A context instance given a
- +Configuration+ can be created by calling +ConfigurationProvider.createConfiguration(context);+.
- ** Similarly a +ConfigurationContext+ can be created using a +ConfigurationContextBuilder+. This builder can be
- obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+.
- ** +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 Type Conversion
-
-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 created from a +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 artifacts that determine the final +Configuration+ and
-also defines the ordering of the property sources, filters and converters contained:
-
-* +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
-
-A +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed. 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 changed, 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
-
-* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the
- current +ConfigurationContext+.
-* calling +ConfigurationProvider.getConfigurationContextBuilder()+.
-
-[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+
---------------------------------------------
-ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext()
- .toBuilder();
- .addPropertySources(new MyPropertySource())
- .addPropertyFilter(new MyFilter())
- .build();
---------------------------------------------
-
-Hereby the builder provides several methods for adding, removing of property sources and also operations
-for programmatically change the property sourcepriorities, e.g.
-
-[source,java]
-.Chain manipulation using +ConfigurationContextBuilder+
---------------------------------------------
-PropertySource propertySource = builder.getPropertySource("sourceId");
-
-// changing the priority of a property source. The ordinal value hereby is not considered.
-// Instead the position of the property source within the chain is changed.
-builder.decreasePriority(propertySource);
-
-// Alternately a comparator expression can be passed to establish the defined ordering...
-builder.sortPropertyFilters(MyFilterComparator::compare);
---------------------------------------------
-
-Finally if the new context is ready a new configuration can be created, or the context is applied to the
-current configuration.
-
-[source,java]
-.Creating and applying a new +ConfigurationContext+
---------------------------------------------
-ConfigurationContext context = builder.build();
-
-// Creates a new matching Configuration instance
-Configuration newConfig = ConfigurationProvider.createConfiguration(context);
-
-// Apply the new context to replace the current configuration:
-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+.
-
-= Interface ConfigurationContextBuilder
-
-include::temp-properties-files-for-site/attributes.adoc[]
-
-[[BuilderCore]]
-== Interface ConfigurationContextBuilder
-=== Overview
-
-The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
-e.g. as follows:
-
-[source,java]
----------------------------------------------------------------
-ConfigurationBuilder builder = new ConfigurationBuilder();
-// do something
-Configuration config = builder.build();
----------------------------------------------------------------
-
-Basically the builder allows to create configuration instances completely independent of the current configuration
-setup. This gives you full control on the +Configuration+ setup.
-
-
-=== Supported Functionality
-
-The builder allows you to add +PropertySource+ instances:
-
-[source,java]
-----------------------------------------------------------------
-ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder();
-builder.addPropertySources(sourceOne, sourceTwo, sourceThree
-Configuration config = ConfigurationProvider.createConfiguration(builder.build());
-----------------------------------------------------------------
-
-Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided
-by the property sources. This allows alternate ordering policies easily being implemented because
-creating a configuration based on a configuration context is already implemented and provided by the core
-API.
-
-Similarly you can add filters:
-
-[source,java]
-----------------------------------------------------------------
-builder.addPropertyFilters(new MyConfigFilter());
-----------------------------------------------------------------
-
-...or +PropertySourceProvider+ instances:
-
-[source,java]
-----------------------------------------------------------------
-builder.addPropertySourceProvider(new MyPropertySourceProvider());
-----------------------------------------------------------------
-
-
-
-[[ServiceContext]]
-==== The ServiceContext
-
-The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya.
-The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the
-+ServiceContextManager+ singleton:
-
-[source,java]
-.Accessing the +ServiceContext+
---------------------------------------------
-ServiceContext serviceContext = ServiceContextManager.getServiceContext();
-
-public interface ServiceContext{
- int ordinal();
- <T> T getService(Class<T> serviceType);
- <T> List<T> getServices(Class<T> serviceType);
-}
---------------------------------------------
-
-With the +ServiceContext+ a component can be accessed in two different ways:
-
-. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally
- the most significant instance is returned only.
-. access all items given its type. This will return (by default) all instances loadedable from the current
- runtime context, ordered by priority, hereby the most significant components added first.
-
-
-## Examples
-### Accessing Configuration
-
-_Configuration_ is obtained from the ConfigurationProvider singleton:
-
-[source,java]
-.Accessing +Configuration+
---------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
---------------------------------------------
-
-Many users in a SE context will probably only work with _Configuration_, since it offers all functionality
-needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is
-very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _Optional_ is supported:
-
-[source,java]
---------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
-String myKey = config.get("myKey"); // may return null
-int myLimit = config.get("all.size.limit", int.class);
---------------------------------------------
-
-
-### Environment and System Properties
-
-By default environment and system properties are included into the _Configuration_. So we can access the current
-_PROMPT_ environment variable as follows:
-
-[source,java]
---------------------------------------------
-String prompt = ConfigurationProvider.getConfiguration().get("PROMPT");
---------------------------------------------
-
-Similary the system properties are directly applied to the _Configuration_. So if we pass the following system
-property to our JVM:
-
-[source,java]
---------------------------------------------
-java ... -Duse.my.system.answer=yes
---------------------------------------------
-
-we can access it as follows:
-
-[source,java]
---------------------------------------------
-boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class);
---------------------------------------------
-
-
-### Adding a Custom Configuration
-
-Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
-_tamaya-spi-support_ module you just have to perform a few steps:
-
-. Define a PropertySource as follows:
-
-[source,java]
---------------------------------------------
- public class MyPropertySource extends PropertiesResourcePropertySource{
-
- public MyPropertySource(){
- super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL);
- }
- }
---------------------------------------------
-
-Then register +MyPropertySource+ using the +ServiceLoader+ by adding the following file:
-
-[source,listing]
---------------------------------------------
-META-INF/services/org.apache.tamaya.spi.PropertySource
---------------------------------------------
-
-...containing the following line:
-
-[source,listing]
---------------------------------------------
-com.mypackage.MyPropertySource
---------------------------------------------
-
-
-[[APIImpl]]
-== API Implementation
-
-The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for
-further details.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/blog/2016/fourth-post.adoc
----------------------------------------------------------------------
diff --git a/content/blog/2016/fourth-post.adoc b/content/blog/2016/fourth-post.adoc
index f22ec22..1e395f3 100644
--- a/content/blog/2016/fourth-post.adoc
+++ b/content/blog/2016/fourth-post.adoc
@@ -1,6 +1,5 @@
= Fourth Post
-Jonathan Bullock
-2013-10-17
+2016-12-18
:jbake-type: post
:jbake-status: published
:jbake-tags: blog, asciidoc
@@ -11,10 +10,10 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vel diam purus.
* http://example.org
* http://example.org[Example.org]
-Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu,
-mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo
-ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet
-ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus,
-id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In
-consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere
-libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat.
\ No newline at end of file
+Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu,
+mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo
+ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet
+ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus,
+id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In
+consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere
+libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/blog/2016/third-post.adoc
----------------------------------------------------------------------
diff --git a/content/blog/2016/third-post.adoc b/content/blog/2016/third-post.adoc
index c334f5a..46376fc 100644
--- a/content/blog/2016/third-post.adoc
+++ b/content/blog/2016/third-post.adoc
@@ -5,18 +5,16 @@ tags=blog, asciidoc
status=published
~~~~~~
= Third Post
-Jonathan Bullock
-2013-10-17
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vel diam purus. Curabitur ut nisi lacus.
* http://example.org
* http://example.org[Example.org]
-Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu,
-mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo
-ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet
-ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus,
-id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In
-consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere
-libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat.
\ No newline at end of file
+Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu,
+mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo
+ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet
+ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus,
+id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In
+consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere
+libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/community.adoc
----------------------------------------------------------------------
diff --git a/content/community.adoc b/content/community.adoc
deleted file mode 100644
index ad9e1dc..0000000
--- a/content/community.adoc
+++ /dev/null
@@ -1,123 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya: Community
-
-:sectnums:
-
-// Document properties
-:twitterhandle: tamayaconf
-
-== Users
-
-If you are a new user and you would like to participate in Tamaya
-(would be great!), you can have a look at the current
-project documentation. Apache Tamaya currently does
-not yet have a users mailing list. If you want discuss your use cases
-we encourage you to mailto:dev-subscribe@tamaya.incubator.apache.org[subscribe]
-to our mailto:dev@tamaya.incubator.apache.org[mailing list for developers].
-Furthermore, you can check our xref:a_mailing_lists[mail-archives].
-
-Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^]
-please ask on the mailing list if it's a known issue in case of a
-bug or if there is an ongoing discussion in case of a feature.
-
-You are very welcome to follow our twitter account
-https://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word
-of Tamaya with tweets, blog entries,...
-
-== Getting Involved
-
-Everybody is welcome to get involved with our community. You can find general
-information at https://apache.org/foundation/getinvolved.html and
-https://apache.org/foundation/how-it-works.html.
-The following sections provides some details about the different levels of getting involved.
-
-If you want to contribute to the
-documentation of Apache Tamaya, please
-read the instructions about the Documentation
-that addresses how to contribute, render and publish it.
-
-
-=== Contributors
-
-Before you get a committer you have to contribute to our effort.
-E.g. you can help users, participate in discussions on the dev list,
-submit patches,... . Therefore, it's essential to file
-a https://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^]
-or https://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^]
-and send it to secretary at apache dot org (or fax it) as early as possible.
-
-If you would like to submit a patch through Jira, you can have a look at the
-link:devguide.html[suggested Git approach].
-
-The lists of current contributors and committers can be found
-on the link:team-list.html[team and contributers page^].
-
-
-=== Committers
-
-Before you read this section, please ensure that you have read
-the contributor section. All of you are welcome to join our development effort.
-mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe] to our
-mailto:dev@tamaya.incubator.apache.org[mailing list for developers] and
-start contributing and help users.
-
-// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12
-Optionally mailto:commits-subscribe@tamaya.incubator.apache.org[subscribe] to our
-mailto:commits@tamaya.incubator.apache.org[mailing list for commits].
-Furthermore, you can check our link:community.html#mailing-lists[mail-archives].
-
-Further details are available at https://www.apache.org/dev/[https://www.apache.org/dev/^].
-
-=== Mailing lists
-
-The table below lists all mailings used by the Tamaya project.
-
-[width="70"]
-[cols="5*.<", options="header"]
-|===
-| List
-| Subscribe
-| Unsubscribe
-| Archive
-| Mirrors
-//-- next row
-| Developer List
-| mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe]
-| mailto:dev-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
-| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^]
-|
-//-- next row
-| Committer List
-| mailto:commits-subscribe@tamaya.incubator.apache.org[Subscribe]
-| mailto:commits-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
-| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^]
-|
-|===
-
-=== JIRA
-
-Any kind of issue has to be filed in our
-https://issues.apache.org/jira/browse/TAMAYA[issue tracker^].
-If you have any question, you can ask us
-(e.g. via the mailing list for developers).
-
-=== Spread the word
-
-You are very welcome e.g. to write blog entries, mention our twitter handle
- @{twitterhandle} if you tweet about the project or just follow our twitter
-account https://twitter.com/{twitterhandle}[@{twitterhandle}^]
-
-=== IRC
-
-Usually discussions happen on the mailing list. Some informal discussions take
-place in our IRC-Channel irc://irc.freenode.net/apache-tamaya.
-
-----
-// with the irssi command-line client:
-$ irssi
-
-> /connect irc.freenode.net
-> /join #apache-tamaya
-----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/core.adoc
----------------------------------------------------------------------
diff --git a/content/core.adoc b/content/core.adoc
deleted file mode 100644
index 139eade..0000000
--- a/content/core.adoc
+++ /dev/null
@@ -1,214 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-[[Core]]
-== Tamaya Core Implementation
-=== Overview
-
-Tamaya Core provides an implementation of the link:API.html[Tamaya Configuration API] and adds additional functionality
-and building blocks for supporting SPI implementations.
-
-Tamaya Core contains the following artifacts:
-
-* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+
-* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based
- on the +@Priority+ annotations.
-* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances
-hereby providing type conversion for all important types.
-* A simple default configuration setup using the current classpath and an optional staging variable.
-* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and
- registers them in the global +ConfigurationContext+
-* It provides a +ConfigurationContextBuilder+ implementation (class +DefaultConfigurationContextBuilder+) and allows
- changing the current +ConfigurationContext+.
-
-The overall size of the library is very small. All required components are implemented and registered, so basically the
-Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible
-enough to be extended/accommodated with additional features as needed, such as
-
-* placeholder and resolution mechanisms
-* dynamic resource path lookup, e.g. with ant styled patterns
-* configuration injection and configuration templates
-* abstraction for reusable formats
-* integration with other existing solutions
-* configuration and configuration isolation targeting Java EE
-* dynamic configuration and configuration updates
-* Configuration management extensions
-* remote configuration
-* and more
-
-For details about the extension modules available and their functionality refer to the link:modules.html[extension user guide].
-
-
-[[CorePropertyConverters]]
-=== Default PropertyConverters in Core
-
-As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the
-listing of converters automatically registered with the Core module:
-
-[width="100%",frame="1",options="header",grid="all"]
-|=======
-|_Target Type_ |_Class Name_ |_Supported Formats_
-|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF
-|java.math.BigInteger |BigIntegerConverter |0xFF, 1234
-|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
-|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
-|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123
-|java.ui.lang.Class |ClassConverter |<fully qualified class name>
-|java.util.Currency |CurrencyConverter |CHF, 123
-|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
-|_Enums_ |EnumConverter |<Enum item name>
-|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
-|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
-|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
-|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
-|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
-|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
-|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
-|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
-|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
-|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
-|ZoneId |ZoneIdConverter |Europe/Zurich
-|=======
-
-
-=== Registering PropertyConverters
-
-Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+,
-meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified
-class names of the converters to be registered (one line per each).
-
-Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically.
-
-NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically.
-
-
-[[ComponentLoadingAndPriorization]]
-=== Component Loading and Priorization
-
-Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components
-must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified
-implementation class names of the components to be registered (one line per each).
-The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya
-core adds this functionality by the possibility to add +@Priority+ annotations to the components registered.
-By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning
-
-* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value
- effectively _overrides/replaces_ any component with lower values.
-* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the
- ones with higher priority are before components with lower priority.
-* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is
- still defined and predictable in almost all scenarios.
-
-NOTE: Sorting the property sources based on their ordinal value is only the default ordering principle applied. By implementing
- your own implementation of +ConfigurationProviderSpi+ you can apply a different logic:
-
-
-[[RegisteringPropertySources]]
-=== Registering Property Sources
-
-PropertySources that provide configuration properties are registered as ordinary components as described in the previous
-section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit
-+int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful
-due to several reasons:
-
-* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being
- added easily.
-* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or
- whatever may be appropriate.
-
-
-[[CorePropertySources]]
-== Configuration Setup in Core
-
-Tamaya Core provides a minimal configuration setting, that allows you to configure SE
-applications already easily. Basically configuration is built up by default as follows:
-
-. Read environment properties and add them prefixed with +env.+
-. Read all files found at +META-INF/javaconfiguration.properties+
- and +META-INF/javaconfiguration.xml+
-
-
-=== Overview of Registered Default Property Sources and Providers
-
-The Tamaya Core implementation provides a couple of default +PropertySource+ implementations, which are automatically
-registered. They are all in the package +org.apache.tamaya.core.propertysource+ and
-+org.apache.tamaya.core.provider+:
-
-[width="100%",frame="1",options="header",grid="all"]
-|=======
-|_Type_ |_Class Name_ |_Ordinal Used_
-|META-INF/javaconfiguration.properties |JavaConfigurationProvider |0
-|META-INF/javaconfiguration.xml |JavaConfigurationProvider |0
-|Environment Properties |EnvironmentPropertySource |300
-|System Properties |SystemPropertySource |400
-|=======
-
-
-=== Abstract Class PropertiesFilePropertySource
-
-The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+
-instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor:
-
-[source,java]
---------------------------------------------
-PropertiesFilePropertySource(URL url);
---------------------------------------------
-
-
-==== Abstract Class PropertiesPropertySource
-
-The abstract class +PropertiesPropertySource+ can be used for implementing a +PropertySource+ based on a +Properties+
-instance. It requires a +PropertySource+ to be passed on the constructor:
-
-[source,java]
---------------------------------------------
-PropertiesPropertySource(Properties properties);
---------------------------------------------
-
-
-==== Abstract Class BasePropertySource
-
-The abstract class +BasePropertySource+ can be used for implementing custom +PropertySource+ classes. It requires only
-one method to implemented:
-
-[source,java]
-.Implementing a PropertySource using BasePropertySource
---------------------------------------------
-public class MyPropertySource extends BasePropertySource{
-
- public String getName(){
- // return a unique name for the property source, e.g. based on the underlying resource. This name also
- // allows to access the property source later
- }
-
- public Map<String, String> getProperties(){
- // Get a map with all properties provided by this property source
- // If the property source is not scannable, the map returned may be empty.
- // In the ladder case the +boolean isScannale()+ must be overridden, since
- // by default property sources are assumed to be scannable.
- }
-
-}
---------------------------------------------
-
-By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in
-+PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override
-the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+.
-
-
-[[CorePropertySourceProviders]]
-=== Default PropertySourceProvider in Core
-
-With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+
-present that loads all .properties files found at +META-INF/javaconfiguration.properties+
-and +META-INF/javaconfiguration.xml+.
-
-
-[[Extensions]]
-== Adding Extensions
-
-The Core module only implements the link:API.html[API]. Many users require/wish additional functionality from a
-configuration system. Fortunately there are numerous extensions available that add further functionality.
-Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath.
-
-For detailed information on the extensions available refer to the link:extensions.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/development/community.adoc
----------------------------------------------------------------------
diff --git a/content/development/community.adoc b/content/development/community.adoc
new file mode 100644
index 0000000..ad9e1dc
--- /dev/null
+++ b/content/development/community.adoc
@@ -0,0 +1,123 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya: Community
+
+:sectnums:
+
+// Document properties
+:twitterhandle: tamayaconf
+
+== Users
+
+If you are a new user and you would like to participate in Tamaya
+(would be great!), you can have a look at the current
+project documentation. Apache Tamaya currently does
+not yet have a users mailing list. If you want discuss your use cases
+we encourage you to mailto:dev-subscribe@tamaya.incubator.apache.org[subscribe]
+to our mailto:dev@tamaya.incubator.apache.org[mailing list for developers].
+Furthermore, you can check our xref:a_mailing_lists[mail-archives].
+
+Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^]
+please ask on the mailing list if it's a known issue in case of a
+bug or if there is an ongoing discussion in case of a feature.
+
+You are very welcome to follow our twitter account
+https://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word
+of Tamaya with tweets, blog entries,...
+
+== Getting Involved
+
+Everybody is welcome to get involved with our community. You can find general
+information at https://apache.org/foundation/getinvolved.html and
+https://apache.org/foundation/how-it-works.html.
+The following sections provides some details about the different levels of getting involved.
+
+If you want to contribute to the
+documentation of Apache Tamaya, please
+read the instructions about the Documentation
+that addresses how to contribute, render and publish it.
+
+
+=== Contributors
+
+Before you get a committer you have to contribute to our effort.
+E.g. you can help users, participate in discussions on the dev list,
+submit patches,... . Therefore, it's essential to file
+a https://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^]
+or https://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^]
+and send it to secretary at apache dot org (or fax it) as early as possible.
+
+If you would like to submit a patch through Jira, you can have a look at the
+link:devguide.html[suggested Git approach].
+
+The lists of current contributors and committers can be found
+on the link:team-list.html[team and contributers page^].
+
+
+=== Committers
+
+Before you read this section, please ensure that you have read
+the contributor section. All of you are welcome to join our development effort.
+mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe] to our
+mailto:dev@tamaya.incubator.apache.org[mailing list for developers] and
+start contributing and help users.
+
+// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12
+Optionally mailto:commits-subscribe@tamaya.incubator.apache.org[subscribe] to our
+mailto:commits@tamaya.incubator.apache.org[mailing list for commits].
+Furthermore, you can check our link:community.html#mailing-lists[mail-archives].
+
+Further details are available at https://www.apache.org/dev/[https://www.apache.org/dev/^].
+
+=== Mailing lists
+
+The table below lists all mailings used by the Tamaya project.
+
+[width="70"]
+[cols="5*.<", options="header"]
+|===
+| List
+| Subscribe
+| Unsubscribe
+| Archive
+| Mirrors
+//-- next row
+| Developer List
+| mailto:dev-subscribe@tamaya.incubator.apache.org[Subscribe]
+| mailto:dev-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
+| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^]
+|
+//-- next row
+| Committer List
+| mailto:commits-subscribe@tamaya.incubator.apache.org[Subscribe]
+| mailto:commits-unsubscribe@tamaya.incubator.apache.org[Unsubscribe]
+| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^]
+|
+|===
+
+=== JIRA
+
+Any kind of issue has to be filed in our
+https://issues.apache.org/jira/browse/TAMAYA[issue tracker^].
+If you have any question, you can ask us
+(e.g. via the mailing list for developers).
+
+=== Spread the word
+
+You are very welcome e.g. to write blog entries, mention our twitter handle
+ @{twitterhandle} if you tweet about the project or just follow our twitter
+account https://twitter.com/{twitterhandle}[@{twitterhandle}^]
+
+=== IRC
+
+Usually discussions happen on the mailing list. Some informal discussions take
+place in our IRC-Channel irc://irc.freenode.net/apache-tamaya.
+
+----
+// with the irssi command-line client:
+$ irssi
+
+> /connect irc.freenode.net
+> /join #apache-tamaya
+----
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/development/source.adoc
----------------------------------------------------------------------
diff --git a/content/development/source.adoc b/content/development/source.adoc
new file mode 100644
index 0000000..441bec8
--- /dev/null
+++ b/content/development/source.adoc
@@ -0,0 +1,23 @@
+:jbake-type: page
+:jbake-status: published
+
+:sectnums: yes
+
+= Apache Tamaya: Sources
+
+== Source Code Repositories
+
+The current source code can be found at:
+
+ - http://git-wip-us.apache.org/repos/asf/incubator-tamaya.git (read-only)
+ - https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git
+
+Alternatively there is also a GitHub read-only mirror at
+https://github.com/apache/incubator-tamaya[https://github.com/apache/incubator-tamaya^].
+
+The GitHub mirror also provides the project as downloadable zip archive.
+
+== Contributions
+
+If you like to contribute to Apache Tamaya please also refer also to our
+<<devguide.adoc#contributing-workflow,section on contributing to Apache Tamaya>>.
[04/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_formats.adoc b/content/extensions/mod_formats.adoc
deleted file mode 100644
index 401a755..0000000
--- a/content/extensions/mod_formats.adoc
+++ /dev/null
@@ -1,206 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Formats
-
-toc::[]
-
-
-[[Core]]
-== Tamaya Formats (Extension Module)
-=== Overview
-
-Tamaya Formats is an extension module. Refer to the link:modules.html[extensions documentation] for further details.
-
-Tamaya Formats provides an abstraction for configuration formats provding the following benefits:
-
-* Parsing of resources in can be implemented separately from interpreting the different aspects/parts parsed. As an
- example a file format can define different sections. Depending on the company specific semantics of the sections
- a different set of +PropertySource+ instances must be created.
-* Similarly the configuration abstraction can also be used as an interface for integrating Tamaya with alternate
- frameworks that provide logic for reading configuration files, such as Apache commons.configuration.
-
-=== 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]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-formats</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The Idea
-
-Formats should be reusable, meaning you should have to write a format parser only once and then be able to map the data read into whatever
-data structure (in our cases: property sources).
-
-==== ConfigurationData
-
-Configuration formats can be very different. Some are simple key/value pairs, whereas other also consist of multiple sections (e.g. ini-files) or
-hierarchical data (e.g. yaml, xml). This is solved in Tamaya by mapping the configuration read into a normalized intermediary format called
-+ConfigurationData+:
-
-[source,java]
-.ConfigurationData
--------------------------------------------------------
-public final class ConfigurationData {
-
- public ConfigurationFormat getFormat();
- public String getResource();
-
- public Set<String> getSectionNames();
- public Map<String,String> getSection(String name);
-
- public boolean hasDefaultProperties();
- public Map<String,String> getDefaultProperties();
- public Map<String,String> getCombinedProperties();
-
- public boolean isEmpty();
-}
--------------------------------------------------------
-
-In detail the data read from a file is organized into _sections_ as follows:
-
-* with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed.
-* properties can be owned by
- ** named sections
- ** an (unnamed) default section
-* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple
- named sections, depending on the configuration format.
-* The method +getSectionNames()+ returns a set of all section names.
-* With +getSection(String name)+ a named section can be accessed.
-* With +getDefaultSection()+ the 'default' section can be accessed. This is a convenience method.
-* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of
- ** all entries from the default section, without any changes.
- ** all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.
-* The configuration format used determines the mapping of configuration data read into this structure. The format
- implementation can as well provide alternate implementations of how the data read should be mapped into the
- combined properties map.
-
-
-==== ConfigurationFormat
-
-A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and
-creates a corresponding +ConfigurationData+ instance.
-
-[source,java]
--------------------------------------------------------
-public interface ConfigurationFormat {
-
- String getName();
- boolean accepts(URL url);
- ConfigurationData readConfiguration(String resource, InputStream inputStream);
-}
--------------------------------------------------------
-
-
-=== How to tranform ConfigurationData into a PropertySource
-
-For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful:
-
-. The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties
- or/and as default properties. The most simple cases is, where all properties have been added as 'default'
- properties. In this case the default properties can be used as the property sources properties without any change.
-. If the format did also add section based properties, the combined properties returned can be used, hereby
- replacing the '::' separator with a '.' separator.
-. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataPropertySource+
- and overriding the +Map<String,String> populateData(ConfigurationData data)+ method.
-
-In most cases the usage of a +FlattenedDefaultPropertySource+, is a good choice to start. This class
-provides a convenient default mapping and also allows to customized the mapping easily:
-
-[source,java]
--------------------------------------------------------
-ConfigurationData data = ...;
-FlattenedDefaultPropertySource ps = new FlattenedDefaultPropertySource(data){
- protected Map<String, String> populateData(ConfigurationData data) {
- ...
- }
-};
--------------------------------------------------------
-
-Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
-resulting properties can have different semnatics, especially different priorities. Also section
-names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats
-with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping
-can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the
-appropriate collection of +PropertySource+ instances must be implemented.
-
-
-=== Examples
-
-==== Mapping ini-Files
-
-Consider the following ini-file:
-
-[source,listing]
-.Example.ini
--------------------------------------------------------
-a=valA
-a.b=valB
-
-[section1]
-aa=sectionValA
-aa.b.c=SectionValC
-
-[section2]
-a=val2Section2
--------------------------------------------------------
-
-This file content coud be mapped to the following structure:
-
-[source,listing]
-.Mapping of Example.ini
--------------------------------------------------------
-a=valA
-a.b=valB
-section1::valA=sectionValA
-section1::a.b.c=SectionValC
-section2::a=val2Section2
--------------------------------------------------------
-
-Nevertheless from the +ConfigurationData+ instance a more complex algorithm can access all the different parts:
-
-* the_default_ properties (a, a.b)
-* the section +section1+, with properties +aa, aa.b.c+
-* the section +section2+, qith properties +a+
-
-
-==== Mapping xml-Files
-
-The same concept can also be applied to xml-files. Consider the following configuration file:
-
-[source,xml]
-.Example.conf
--------------------------------------------------------
-<config>
- <default>
- <a>valA</a>
- <a.b>valB</a.B>
- </default>
-
- <section id="section1">
- <param id="aa">sectionValA</aa>
- <param id="aa.b.c">SectionValC</aa.b.c>
- </section>
- <section id="section2">
- <param id="a">val2Section2</aa>
- </section>
-</config>
--------------------------------------------------------
-
-This file basically describes the same configuration as the ini-based version we have seen before. The formats
-module hereby ships with 3 format classes:
-
-* +PropertiesFormat+ providing support for .properties files.
-* +PropertiesXmlFormat+ providing support for xml.property files.
-* +IniConfiguratonFormat+ providing support for xml.property files.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_functions.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_functions.adoc b/content/extensions/mod_functions.adoc
deleted file mode 100644
index 6e2c172..0000000
--- a/content/extensions/mod_functions.adoc
+++ /dev/null
@@ -1,108 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Functions
-
-toc::[]
-
-[[Core]]
-== Tamaya Functions (Extension Module)
-=== Overview
-
-Tamaya Functions is an extension module. Refer to the link:modules.html[extensions documentation] for further details.
-
-Tamaya Functions provides several functional extensions using the +ConfigOperator,ConfigQuery+ extension points. Most
-functional extension are accessible from the +ConfigurationFunction+ singleton. When importing its methods statically
-one can use the methods to achieve some interesting effects, e.g.
-
-[source,java]
--------------------------------------------------------------------
-import static org.apache.tamaya.functions.ConfigurationFunctions.*;
-
-Set<String> sections = ConfigurationProvider.getConfiguration().with(areas("a", false).with(transitiveAreas());
--------------------------------------------------------------------
-
-The expression above returns all fully qualified section names that are child sections of the root section 'a'.
-So given the entries +a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4+ the reult would be +a, a.a, a.b, a.b.c+.
-
-=== Compatibility
-
-The module is based on Java 7, so it can be used with Java 7 and beyond.
-
-=== Installation
-
-For using the functionality shown in this document you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-functions</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The Provided Functions
-
-==== Functions on +ConfigurationFunctions+
-
-The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton.
-
-* *ConfigOperator filter(PropertyMatcher matcher)* creates a +ConfigOperator+ that creates a +Configuration+
- containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only
- the _key_, but also the _value_.
-* *ConfigOperator map(KeyMapper keyMapper)* creates a +ConfigOperator+ that maps the keys as defined
- by the given _keyMapper_.
-* *ConfigOperator section(String section)* creates a +ConfigOperator+ that creates a +Configuration+ containing only
- entries that are direct or indirect members of the given section.
-* *ConfigOperator section(String areaKey, boolean stripKeys)* creates a +ConfigOperator+ that creates a +Configuration+
- containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine
- if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.
-* *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member
- of a given section.
-* *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given
- _key_ is a direct or indirect member of at least one of the given _sectionKeys_.
-* *ConfigQuery<Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
- also have parameters present).
-* *ConfigQuery<Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
- including the transitive closure of sections.
-* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
- qualified section names that are selected by the given _predicate_.
-* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
- qualified section names that are selected by the given _predicate_, including the transitive closure of sections
- identified.
-* *ConfigOperator sectionsRecursive(String... sectionKeys)* provides a +ConfigOperator+ that filters all sections identified
- by the given _sectionKeys_ and its child sections.
-* *ConfigOperator sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +ConfigOperator+
- that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to
- determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or
- absolute (filtering only).
-* *ConfigQuery<String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
- representation.
-
-
-==== Functions on +PropertySourceFunctions+
-
-The following sections explain the provided functions defined by +PropertySourceFunctions+ singleton.
-
-* *PropertySource addMetaData(PropertySource propertySource, Map<String,String> metaData)* Creates a new +PropertySource+
- with the given metadata added.
-* *boolean isKeyInSection(String key, String sectionKey)* Checks if the given _key_ is a direct or indirect member of
- one of the given _sectionKey_.
-* *boolean isKeyInSections(String key, String... sectionKeys)* Checks if the given _key_ is a direct or indirect member of
- one of one of the given _sectionKeys_.
-* *Set<String> sections(Map<String, String> properties)* Extracts the sections from the given properties.
-* *Set<String> transitiveSections(Map<String, String> properties)* Extracts the transitive sections from the given
- properties.
-* *Set<String> sections(Map<String, String> properties, final Predicate<String> predicate)* Extracts the sections
- from the given properties, also filtering with the given predicate.
-* *Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate)* Extracts the transitive
- sections from the given properties, also filtering with the given predicate.
-* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +PropertySource+
- only containing the sections that a direct or indirect children of the given _sectionKeys_.
-* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +PropertySource+
- only containing the sections that a direct or indirect children of the given _sectionKeys_. With _stripKeys_ one can
- select of the returned values should be relative to its selection of be fully qualified.
-* *String stripSectionKeys(String key, String... sectionKeys)* This function strips away the matching section key as given
- in _sectionKeys_ from a given _key_.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_injection.adoc b/content/extensions/mod_injection.adoc
deleted file mode 100644
index 941351e..0000000
--- a/content/extensions/mod_injection.adoc
+++ /dev/null
@@ -1,430 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Injection
-
-toc::[]
-
-
-[[Core]]
-== Tamaya Injection (Extension Module)
-=== Overview
-
-Tamaya Injection is an extension module. Refer to the link:modules.html[extensions documentation] for further details
-about modules.
-
-Tamaya Injection provides functionality for injecting configured values into beans, or creating configuration
-template instances.
-
-Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate
-code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a
-built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the
-according injection services. This module adds this functionality to Tamaya.
-
-=== Compatibility
-
-The module is based on Java 7, so it can be used with Java 7 and beyond.
-
-=== Installation
-
-Basically Tamaya's injection API is deployed as API artifact:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-injection-api</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-To use injection with Java SE you must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-injection</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-Similarly there are other injection implementations available, targetig platforms such as
-
-* Spring, Spring Boot
-* Java EE/CDI
-* OSGI, Apache Felix/Apache Karaf
-
-
-=== Core Concepts
-
-Basically you annotate fields or methods in your beans with +@Config+ to enable configuration injection. Tamaya
-additionally defines further annotations that allo you to define additional aspects such as default values, custom
-converters etc. The following example illustrates the basic functionality:
-code snippet:
-
-[source,java]
-.Annotated Example Class
---------------------------------------------
-package foo.bar;
-
-public class ConfiguredClass {
-
- // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
- private String testProperty;
-
- // Trying to resolve mutiple keys, with a default value, if none could be resolved
- @Config({"a.b.c.key1","a.b.legacyKey",area1.key2"}, defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
- String value1;
-
- // Typical case
- @Config("a.b.c.key2")
- private int value2;
-
- // resolved by default as foo.bar.ConfiguredClass.accessUrl
- // Using a (default) String -> URL converter
- @Config(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
- private URL accessUrl;
-
- // Config injection disabled for this property
- @NoConfig
- private Integer int1;
-
- // Overriding the String -> BigDecimal converter with a custom implementation.
- @Config("BD")
- @WithPropertyConverter(MyBigDecimalRoundingAdapter.class)
- private BigDecimal bigNumber;
-
- ...
-}
---------------------------------------------
-
-
-When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
-this feature a class must be annotated with +@ConfigAutoInject+:
-
-[source, java]
-. An autoinjected bean class
---------------------------------------------
-package a.b;
-
-@ConfigAutoInject
-public final class Tenant {
- private int id;
- private String name;
- private String description;
- @NoConfig // prevents auto injection for this field
- private String id2;
-
- public int getId(){
- return id;
- }
- public String getName(){
- return name;
- }
- public String getDescription(){
- return description;
- }
-}
---------------------------------------------
-
-These examples do not show all possibilities provided. Configuring instance of these
-class using Tamaya is very simple: Just pass the instance to Tamaya to let
-Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible):
-
-[source,java]
-.Configuring the +ConfiguredClass+ Instance
---------------------------------------------
-ConfiguredClass classInstance = new ConfiguredClass();
-ConfigurationInjector.configure(configuredClass);
-
-Tenant tenant = new Tenant();
-ConfigurationInjector.configure(tenant);
---------------------------------------------
-
-NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
-with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
-documentation.
-
-
-=== The Annotations in detail
-==== The ConfigurationInjector
-
-The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured
-by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed
-hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
-tries to determine configuration for each property of an instance passed, using the following resolution policy:
-
-Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
-[source, listing]
---------------------------------------------
-a.b.MyClass.myField
-a.b.MyClass.my-field
-MyClass.myField
-MyClass.my-field
-myField
-my-field
---------------------------------------------
-
-So given the following properties:
-
-[source, properties]
---------------------------------------------
-a.b.Tenant.id=1234
-Tenant.description=Any kind of tenant.
-name=<unnamed>
---------------------------------------------
-
-
-==== Accessing Supplier instances
-
-In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
-by the current context. This can be done using +Suppliers+:
-
-[source, java]
---------------------------------------------
-Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
- new Supplier<Tenant>(){
- public Tenant get(){
- return new Tenant();
- }
-});
---------------------------------------------
-
-With Java 8 it's even more simple:
-
-[source, java]
---------------------------------------------
-Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
- Tenant::new);
---------------------------------------------
-
-Hereby this annotation can be used in multiple ways and combined with other annotations such as
-+@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+.
-
-==== Minimal Example
-
-To illustrate the mechanism below the most simple variant of a configured class is given:
-
-[source,java]
-.Most simple configured class
---------------------------------------------
-pubic class ConfiguredItem{
- @Config
- private String aValue;
-}
---------------------------------------------
-
-When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
-the following is happening:
-
-* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
-* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
- keys are possible).
-* if not successful, an error is thrown (+ConfigException+)
-* On success, since no type conversion is involved, the value is injected.
-
-==== Using @DefaultValue
-
-In the next example we explicitly define the property value:
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
-
- @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
- private String aValue;
-}
---------------------------------------------
-
-==== Inject a DynamicValue Property
-
-Within this example we evaluate a dynamic value. This mechanism allows you to listen for configuration changes and to
-commit new values exactly, when convenient for you.
-
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
-
- @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
- private DynamicValue aValue;
-}
---------------------------------------------
-
-The +DynamicValue+ provides you the following functionality:
-
-[source,java]
---------------------------------------------
-public interface DynamicValue<T> {
-
- enum UpdatePolicy{
- IMMEDIATE,
- EXPLCIT,
- NEVER,
- LOG_AND_DISCARD
- }
-
- T get();
- T getNewValue();
- T evaluateValue();
- T commitAndGet();
- void commit();
- void discard();
- boolean updateValue();
-
- void setUpdatePolicy(UpdatePolicy updatePolicy);
- UpdatePolicy getUpdatePolicy();
- void addListener(PropertyChangeListener l);
- void removeListener(PropertyChangeListener l);
-
- boolean isPresent();
- T orElse(T other);
- // Enabled with Java 8
- // T orElseGet(ConfiguredItemSupplier<? extends T> other);
- // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
-
-}
---------------------------------------------
-
-Summarizing this class looks somehow similar to the new +Optional+ class added with Java 8. It provides
-a wrapper class around a configured instance. Additionally this class provides functionality that gives
-active control, to manage a configured value based on a ++LoadingPolicy+:
-
-* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
- is automatically applied without any further notice.
-* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
- returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
- hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
- +discard()+.
-* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
-* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
-
-Summarizing a +DynamicValue+ allows you
-
-* to reload actively updates of configured values.
-* update implicitly or explicitly all changes on the value.
-* add listeners that observe changes of a certain value.
-
-Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+. Hereby the value of the
-instance is not changed.
-
-
-==== Ommitting Injection using @NoConfig
-
-Adding the @NoConfig annotation prevents a field or method to be auto-injected from
-configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with auto-confiuration
-turned on as follows:
-
-[source,java]
---------------------------------------------
-@ConfigAutoInject
-pubic class ConfiguredItem{
-
- @NoConfig
- private transient int sum;
-
- private String a;
- private String b;
- Private String c;
-}
---------------------------------------------
-
-In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
-configuration.
-
-==== Adding custom operators using @WithConfigOperator
-
-The @WithConfigOperator annotation allows you define a class of type +ConfigOperator+, to being applied
-to the final +Configuration+, BEFORE the value is injected. This can be used for various use cases, e.g.
-filtering or validating the visible properties for a certain use case.
-
-[source,java]
---------------------------------------------
-
-@WithConfigOperator(MyConfigView.class)
-pubic class ConfiguredItem{
-
- @Config
- private String a;
-
-}
---------------------------------------------
-
-
-==== Adding custom property converters using @WithPropertyConverter
-
-The @WithPropertyConverter annotation allows you to define a class of type +PropertyConverter+, to be applied
-on a property configured to convert the String value to the expected injected type. This can be used for
-various use cases, e.g. adding custom formats, config models, decryption.
-
-[source,java]
---------------------------------------------
-
-pubic class ConfiguredItem{
-
- @WithPropertyConverter(MyPropertyConverter.class)
- @Config
- private String a;
-
-}
---------------------------------------------
-
-
-==== Defining the loading policy to be applied to configured values using @WithLoadPolicy
-
-The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The +LoadPolicy+
-enum hereby defines the various loading modes.
-
-[source,java]
---------------------------------------------
-
-@WithLoadPolicy(LoadPolicy.NEVER)
-pubic class BootTimeStableConfig{
-
- @WithPropertyConverter(MyPropertyConverter.class)
- @Config
- private String a;
-
-}
---------------------------------------------
-
-
-=== Configuration Events
-
-Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
-event backend in use, if and how events are published:
-
-* when you have the CDI extension active events are published using the default CDI event mechanism.
-* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
-* if no event delegation is available no events are published.
-
-The event published is very simple:
-
-[source,java]
---------------------------------------------
-public interface ConfiguredType {
- Class getType();
- String getName();
- Collection<ConfiguredField> getConfiguredFields();
- Collection<ConfiguredMethod> getConfiguredMethods();
- void configure(Object instance, Configuration config);
-}
-
-
-public interface ConfiguredField {
- Class<?> getType();
- Collection<String> getConfiguredKeys();
- String getName();
- String getSignature();
- Field getAnnotatedField();
- void configure(Object instance, Configuration config);
-}
-
-public interface ConfiguredMethod {
- Collection<String> getConfiguredKeys();
- Class<?>[] getParameterTypes();
- Method getAnnotatedMethod();
- String getName();
- String getSignature();
- void configure(Object instance, Configuration config);
-}
-----------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_jodatime.adoc b/content/extensions/mod_jodatime.adoc
deleted file mode 100644
index 4ebae7a..0000000
--- a/content/extensions/mod_jodatime.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: JodaTime
-
-toc::[]
-
-[[Core]]
-== Tamaya JodaTime (Extension Module)
-
-=== Overview
-
-Tamaya JodaTime is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time]
-in conjunction with Tamaya. Tamaya JodaTime defines some additional property
-converters to retrieve Joda-Time types from a given configuration.
-
-Refer to the link:modules.html[extensions documentation] for further details
-about modules.
-
-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]
------------------------------------------------
-<dependency>
- <grooupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-jodatime</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-After adding this dependency to your project you can retrieve
-Joda-Time based values directly from a given configuration.
-
-[source,java]
------------------------------------------------
-Configuration configuration = ConfigurationProvider.getConfiguration();
-
-DateTime pit = configuration.get("pointInTime", DateTime.class)
------------------------------------------------
-
-=== Specifying date and time values
-
-To be written.
-
-=== Specifing periods and durations
-
-To be written.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_json.adoc b/content/extensions/mod_json.adoc
deleted file mode 100644
index 66c12fa..0000000
--- a/content/extensions/mod_json.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Builder
-
-toc::[]
-
-
-[[BuilderCore]]
-== Tamaya JSON (Extension Module)
-=== Overview
-
-The Tamaya json module provides support for reading configuration using JSON format:
-
-
-=== Compatibility
-
-The 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-json</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-This extension also transitively requires the +tamaya.formats+ module.
-
-=== Reading configuration in JSON
-
-For reading JSON based onfiguration most easily a +JSONFormat+ can be provided:
-
-[source, java]
------------------------------------------------
-ConfigurationData dataRead = ConfigurationFormats.readConfig(
- getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
------------------------------------------------
-
-=== Examples
-
-The JSON module adds instances of +ConfigurationFormat+ so JSON configuration can be read and mapped to the
-according property maps. E.g. the following file is a simple and correct JSON configuration:
-
-[source,listing]
-----------------------------------------------------------------
-{
- "a" : "A",
- "b" : "B",
- "c" : "C",
- "d" : {
- "o" : "O",
- "p" : "P"
- }
-}
-----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_management.adoc b/content/extensions/mod_management.adoc
deleted file mode 100644
index b912747..0000000
--- a/content/extensions/mod_management.adoc
+++ /dev/null
@@ -1,92 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: JMX Management Access
-
-toc::[]
-
-
-[[ExtModel]]
-== Tamaya Management (JMX Support) (Extension Module)
-=== Overview
-
-The Tamaya management module provides support for registering a JMX management bean for accessing configuration.
-
-=== Compatibility
-
-The 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-management</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== The ManagedConfigMBean bean
-
-The management model defines the MBean of type +ManagedConfigMBean+ as follows:
-
-
-[source,java]
------------------------------------------------------------------------------
-public interface ManagedConfigMBean {
- String getJsonConfigurationInfo();
- String getXmlConfigurationInfo();
- Map<String, String> getConfiguration();
- Map<String, String> getSection(String area, boolean recursive);
- Set<String> getSections();
- Set<String> getTransitiveSections();
- boolean isSectionExisting(String area);
- default boolean isSectionEmpty(String area);
-}
------------------------------------------------------------------------------
-
-* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the
-current configuration.
-* +getConfiguration+ access the current configuration properties.
-* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query
- will not only return direct children, but also recursively walk down all subsection of the
- given section key.
-* +getSections+ returns all current known section names.
-* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single
- entries to the set as well.
-* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
- section keys.
-
-=== Registering the ManagedConfigMBean
-
-For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the
-following static methods are available:
-
-[source,java]
------------------------------------------------------------------------------
-public final class ConfigManagementSupport{
-
- private JMXSupport(){}
-
- public static ObjectName registerMBean();
- public static ObjectName registerMBean(String context);
- public static ObjectName unregisterMBean();
- public static ObjectName unregisterMBean(String context);
-}
------------------------------------------------------------------------------
-
-* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+
- and registers it. Optionally an additional _context_ parameter can be passed, which allows
- to register the management bean for different classloaders, e.g. for different
- ears.
-* +unregisterMBean+ does the oppsite than registering obviously.
-
-NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the
- +ServiceContextManager+. So you can replace the bean implementation by registering your
- overriding implementation using the current +ServiceContext+ (by default using
- +java.util.ServiceLoader+ and +@Priority+ annotation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_metamodel-staged.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_metamodel-staged.adoc b/content/extensions/mod_metamodel-staged.adoc
deleted file mode 100644
index cf02806..0000000
--- a/content/extensions/mod_metamodel-staged.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Staged PropertySources
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Metamodel: Staged PropertySources (Extension Module)
-=== Overview
-
-The Tamaya Staged PropertySources extension provides a base class and default implementation for loading
-multistaged configuration easily from a common configuration location.
-
-
-=== 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.metamodels</groupId>
- <artifactId>tamaya-metamodel.staged</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-The component will not register any components. The component basically provides the following options:
-
-* Use it as default configuration extension. Hereby you should define your stages in use by setting the
- +env.STAGE+ system property with the stages to be loaded in order of precedence (most significant last),
- e.g. +sys-env,DEFAULTS,TEST,DEVELOPMENT. _Additionally_ you must register
- +org.apache.tamaya.staged.StagedConfigPropertiesProvider+ as in
-
---------------------------------------------------------------
-META-INF
-|_service
- |_org.apache.tamaya.spi.PropertySourceProvider
---------------------------------------------------------------
-
-Tamaya will then load .properties files from +System.getenv(),
-classpath:DEFAULTS.properties, classpath:TEST.properties+ and
-+classpath:DEVELOPMENT.properties+
-
-* For more advanced requirements, such as alternate locations, patterns or formats, you can also extend one of the
- provided classes (+org.apache.tamaya.staged.StagedConfigPropertiesProvider+,
- ** +BaseStagedPropertySourceProvider+). Extending provides features such as:
-
- ** Defining a prefix for all entries provided/loaded.
- ** Using alternate locations or formats.
- ** Defining the ordinals used.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_model.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_model.adoc b/content/extensions/mod_model.adoc
deleted file mode 100644
index e454eb1..0000000
--- a/content/extensions/mod_model.adoc
+++ /dev/null
@@ -1,451 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Model Documentation and Validation
-
-toc::[]
-
-
-[[ExtModel]]
-== Tamaya Model Documentation and Validation (Extension Module)
-=== Overview
-
-The Tamaya model module provides support for documenting configuration and validating configuration read and processed
-against this model. Documentation and config models can be provided in different ways:
-
-* as separate meta-model documents
-* by providers that check classes/packages for configuration annotations (planned)
-
-
-=== 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-model</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-
-=== Describing the Configuration Meta-Model
-
-Basically configuration is modelled using key, value-pairs. Looking at a keys
-+a.b.c.param1+ and +a.b.c.param2+ the following concepts can be used to defined/describe
-configuration:
-
-. the _configuration section:_ In our case this equals to +a.b.c+, which itself also includes the
- transitive entries +a.b+ and +a+.
-. the _configuration parameter:_ Basically parameters are adressed using their fully qualified names,
- which equals to the containing section name and the relative parameter name, separated by the dor separator.
- In the above example +a.b.c.param1+ and +a.b.c.param2+ are the fully qualified parameter names.
-
-Now with only these 2 concepts a simple configuration meta-model can be defined as
-
-* a meta-model's name, used just for grouping different meta-models and entries to better separate
- descriptions, e.g. in a management console or generated configuration documentation site.
-* a set of sections.
-* a set of parameters.
-* Both, sections (+.model.target=Section+) as well as parameter models (+.model.target=Parameter+)
- ** can be modelled by a meta-data entry, by default +_my.config.key.model+.
- ** may be required, or optional (+.model.required=true|false+)
- ** may have an optional description
-* Parameters additionally have
- ** a _type_ (+.model.type=Classname+), described by the fully qualified class name, into which any configured (String)
- value must be convertable into. If no type is configured +java.ui.lang.String+ is assumed as default.
- ** an optional regular expression that can be used to validate the +String+ values returned from a
- configuration (+.model.expression=regexpression+).
-
-Given these concepts a configuration can be fully described. Entries that are not contained in one of the given
-sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of
-a section), are called _undefined_. Undefined parameters should be grouped with its parent section. Each section, as
-well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and
-only if
-
-. the section itself is (directly) _undefined_
-. the section is not a _super section_ of a defined section.
-
-As en example the section definition of +a.b.c+ also implicitly includes the sections +a.b+ and +a+ to be defined
-sections, despite the fact that section properties, such as description and custom configModels are not inherited to
-its parent, or child section.
-
-
-=== Defining Meta-Configuration Model
-
-The configuration meta-model is defined by simple configuration meta-data entries. The section for all model
-configuration by default is called +model+, which results in entries such as +_my.config.key.model.target=Section+.
-Within this section fully qualified configuration keys defines
-which part of the configuration is targeted by certain entries.
-
-==== Defining Sections
-
-First we start to define some configuration sections, the example below starts with the most important
-variants supported:
-
-[source,listing]
--------------------------------------------------------------------------------
-# Metamodel information
-_model.provider=ConfigModel Extension
-
-# org.mycompany.root (optional section)
-_org.mycompany.root.model.target=Section
-_org.mycompany.root.model.description=Root section defining my company configuration.
-
-# org.mycompany.security (required section)
-_org.mycompany.security.model.target=Section
-_org.mycompany.security.model.required=true
-_org.mycompany.security.model.description=Security related settings.\
- refer for further details to XXX.
-
-# minmal section
-_minimal.model.target=Section
-
-# custom validated section
-_validated.model.target=Section
-_validated.model.validator=org.apache.tamaya.model.TestValidator
--------------------------------------------------------------------------------
-
-Above +org.mycompany.root+ transitively defines 3 sections:
-
-* org
-* org.mycompany
-* org.mycompany.root
-
-All sections are optional. Additionally the model above also defines a required section +org.mycompany.security+.
-Required sections are checked so the section is not empty. It is not checked for any specific parameter hereby,
-only the existance of any child parameter is validated.
-
-The _class_ attribute has to be defined for any section definition, because if not set a model entry is, by default,
-defined to be a parameter configModel entry. Given above the entry for the section +minimal+ shows such a minimal
-entry.
-
-+validated+ defines a section, which is validated through a customizable validator. Hereby an ordered list of validators
-can be provided, separated by commas.
-
-
-==== Defining Parameters
-
-Similarly parameters also can be defined:
-
-[source,listing]
--------------------------------------------------------------------------------
-# org.mycompany.root.name (required parameter)
-_org.mycompany.root.name.model.target=Parameter
-_org.mycompany.root.name.model.required=true
-_org.mycompany.root.name.model.description=The company's name, also used in the application's main header.
-
-# org.mycompany.security (required parameters)
-_org.mycompany.security.uid.model.required=true
-_org.mycompany.security.uid.model.description=The user id.
-_org.mycompany.security.realm.model.required=true
-_org.mycompany.security.realm.model.validator=org.apache.tamaya.model.RealmValidator
-_org.mycompany.security.realm.model.description=The security realm required.
-_org.mycompany.security.tokenid.model.description=The token id, if the token service is used (optional).
-
-# A minmal parameter
-_minimalClass.model.target=Class
--------------------------------------------------------------------------------
-
-Similarly as when defining section also parameter entries define transitively its containing sections. E.g.
-the entry above for +org.mycompany.security.realm+ also defines the following sections (as optional).
-
-* org
-* org.mycompany
-* org.mycompany.security
-
-Additional entries for section, e.g. configModels to be done, can be added as described in the previous section,
-but are optional.
-
-Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it's
-parameter type to be defined. In the example above we define a parameter +minimalClass+ of type +Class+.
-Types hereby are fully qualified class names, whereas as 'java.ui.lang' for built-in language types can be
-ommitted.
-
-==== Model Locations
-
-By default the configuration model can be defined at the following locations:
-
-* +classpath*:META-INF/configmodel.properties+, separate to the current +Configuration+. This functionality is enabled
- by default, but can be disabled by adding +org.apache.tamaya.model.default.enabled=false+ to your current
- +Configuration+.
-* +implicitly as part of the current +Configuration+. THis can be disabled by setting
- the +org.apache.tamaya.model.integrated.enabled+ configuration poarameter to +false+.
-* customized by configuring the +org.apache.tamaya.model.resources+ in the current +Configuration+. This
- parameter allows to define the locations from where the model extension is trying to read the
- model configuration. If the _resources extension_ is available in your system it is used to
- evaluate the locations. If not the default +Classloader.getResources+ command is issued. Also it
- is required that the _formats extension_ is available, since this is used to effectively read the
- data. This extension also allows you to use alternate representation formats such as +ini, xml, yml, json+.
-
-
-=== Tracking Configuration Access
-
-The model module also allows tracking which code accesses configuration properties or configuration parameters.
-It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly
-ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length.
-The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+
-instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage
-statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+.
-
-Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+.
-+ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status.
-
-The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing:
-
-* the access point (+fqn.ClassName#method(line: xxx)+).
-* the number of accesses
-* the first an last access
-* the values read
-* the access stacktrace (filtered by ignored packages).
-
-[source,java]
------------------------------------------------------------
-public final class Usage {
- [...]
- public String getKey();
- public void clearMetrics();
- public int getReferenceCount();
- public int getUsageCount();
- public Collection<AccessDetail> getAccessDetails(Class type);
- public Collection<AccessDetail> getAccessDetails(Package pack);
- public Collection<AccessDetail> getAccessDetails(String lookupExpression);
- public Collection<AccessDetail> getAccessDetails();
- public void trackUsage(String value);
- public void trackUsage(String value, int maxTraceLength);
-
-
- public static final class AccessDetail {
- [...]
- public void clearStats();
- public long trackAccess(String value);
- public long getAccessCount();
- public String getAccessPoint();
- public long getFirstAccessTS();
- public long getLastAccessTS();
- public String[] getStackTrace();
- public Map<Long, String> getTrackedValues();
- }
-
-}
------------------------------------------------------------
-
-With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main
-singleton for configuration statistics is defined as follows:
-
-[source,java]
------------------------------------------------------------
-public final class ConfigUsageStats{
- public static Set<String> getIgnoredUsagePackages();
- public static void addIgnoredUsagePackages(String... packageName);
- public static void enableUsageTracking(boolean enabled);
- public static Usage getUsage(String key);
- public static Collection<Usage> getUsages();
- public static void clearUsageStats();
- public static Usage getUsageAllProperties();
- public static boolean isUsageTrackingEnabled();
- public static String getUsageInfo();
-}
------------------------------------------------------------
-
-==== Customizing the Stacktrage for Usage Reporting
-
-The stacktrace tracked by the system can be customized in several ways:
-
-* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names.
-* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a
- negative value will disable stacktrace logging completelely.
-
-
-=== Accessing Usage Statistics
-
-Bascially usage statistics are available in two forms:
-
-* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+
- singleton.
-* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics
- can be obtained, as illustrated below (a snipped from the current test output):
-
-[source,listing]
------------------------------------------------------------
-Apache Tamaya Configuration Usage Metrics
-=========================================
-DATE: Sat Apr 30 21:51:09 CEST 2016
-
-220 <<all>>:
- - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-3 java.version:
- - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
- - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-
------------------------------------------------------------
-
-
-==== Programmatic API
-
-Basically the configModel module provides a simple API to access the defined +ConfigModel+ instances and
-validating the current +Configuration+ against the models as follows:
-
-[source,java]
------------------------------------------------------------
-public final class ConfigModelManager {
-
- private ConfigModelManager() {}
-
- public static Collection<ConfigModel> getModels();
- public static Collection<ConfigModel> findModels(ModelType type, String namePattern);
- public static <T extends ConfigModel> T getModel(String name, Class<T> modelType);
- public static Collection<ConfigModel> findModels(String namePattern);
-
- public static Collection<ValidationResult> validate();
- public static Collection<ValidationResult> validate(boolean showUndefined);
- public static Collection<ValidationResult> validate(Configuration config);
- public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined);
-
- public static void registerMBean();
- public static void registerMBean(String context);
-
-}
------------------------------------------------------------
-
-This singleton allows to validate the current or any +Configuration+ instance. All the ConfigModels read also are
-available from the +getModels+ method. This models can be used to provide documentation, e.g. as part of a CLI interface
-or shown on a documentation web server.
-
-A +ConfigModel+ hereby is defined as one single part of configuration, typically corresponding to a specific concern
-of your system. As an example you can define different models for different modules or products plugged together.
-With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a
-single configuration source (e.g. for configuring the machine's IP address and subnet settings only once.
-
-[source,java]
------------------------------------------------------------
-public interface ConfigModel {
-
- ModelTarget getType();
- String getName();
- String getProvider();
- boolean isRequired();
- String getDescription();
- Collection<ValidationResult> validate(Configuration config);
-}
------------------------------------------------------------
-
-
-Hereby +ModelTarget+ defines more details on the kind of model:
-
-[source,java]
------------------------------------------------------------
-public enum ModelTarget {
- /**
- * A configuration section.
- */
- Section,
- /**
- * A configuration paramter.
- */
- Parameter,
- /**
- * ConfigModel that is a container of other validations.
- */
- Group
-}
------------------------------------------------------------
-
-A +ValidationResult+ models one validation executed by a +ConfigModel+ on a certain +Configuration+ instance:
-
-[source,java]
------------------------------------------------------------
-public final class ValidationResult {
-
- public static ValidationResult ofValid(ConfigModel configModel);
- public static ValidationResult ofMissing(ConfigModel configModel);
- public static ValidationResult ofMissing(ConfigModel configModel, String message);
- public static ValidationResult ofError(ConfigModel configModel, String error);
- public static ValidationResult ofWarning(ConfigModel configModel, String warning);
- public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage);
- public static ValidationResult ofDeprecated(ConfigModel configModel);
- public static ValidationResult ofUndefined(final String key);
- public static ValidationResult of(ConfigModel configModel, ValidationState result, String message);
-
- public ConfigModel getConfigModel();
- public ValidationState getResult();
- public String getMessage(),
-}
------------------------------------------------------------
-
-The result of a complete validation on a concrete +Configuration+ instance finally is mapped as a
-+Collection<ValidationResult>+, refer to the methods on +ConfigModelManager+.
-
-
-=== Auto-Documentation of Classes with Configuration Injection
-
-A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
-(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
-models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
-time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
-behaviour. Nevertheless this means that after your system has been started you should have access to a complete
-set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
-(through injection).
-
-
-== Model SPI
-=== Registering Configuration Models
-
-The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is
-the +ModelProviderSpi+ interface, which allows any kind of additional config models to be added to the system:
-
-[source,java]
------------------------------------------------------------
-public interface ModelProviderSpi {
-
- Collection<ConfigModel> getConfigModels();
-
-}
------------------------------------------------------------
-
-New instances implementing this interface must be registered into the current +ServiceContext+, by default the
-+ServiceLoader+ is used.
-
-
-=== The ConfigUsageStatsSpi
-
-The methods for managing and tracking of configuration changes are similarly delegated to an
-implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI.
-By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking
-logic can be adapted or replaced.
-
-=== Other Utility Classes
-
-The module also provides further utility classes that may be useful for implementing models or testing:
-
-* +AbstractModel+ provides a base class that can be extended, when implementing +ConfigModel+.
-* +AreaConfigModel+ provides a +ConfigModel+ implementation (with a corresponding +Builder+) to model the
- requirement of certain configuration sections being present, or opionally present, in the model.
-* +ParameterModel+ provides an implementation base class for validating parameters on existence and compliance
- with a regular expression.
-* +ConfigDocumentationMBean+ is the MBean registered that models similar functionality as +ConfigModelManager+.
-* +ConfigModelGroup+ provides a +ConfigModel+ that groups several child models.
-* +ConfigModelReader+ allows to read +ConfigModels+ from properties files as described at the beginning of this
- document.
-
-
-=== Switches to enable/disable functionality
-
-The model module provides different switches that can be used to activate or deactivate features:
-
-* +tamaya.model.integrated.enabled+ allows to deactivate reading inline metaconfiguration delivered with
- the normal Tamaya Configuration. By default inline entries (+_.abcd.model.*+) are evaluated.
-* +tamaya.model.default.enabled+ allows to deactivate reading metamodel information from
- +classpath:META-INF/configmodel.properties+. By default it is active.
-* +tamaya.model.resources+ allows to define additional resources (loaded through the resources extension),
- that can be used to read metamodel information in any format using Tamaya's format module.
-* the system property +tamaya.model.autoModelEvents+ allows to activate/deactivate the automatic
- documentation of classes configured and published by Tamaya +ConfiguredType+ event instances (e.g. published by
- Tamaya's injection modules).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_mutable_config.adoc b/content/extensions/mod_mutable_config.adoc
deleted file mode 100644
index cb8869d..0000000
--- a/content/extensions/mod_mutable_config.adoc
+++ /dev/null
@@ -1,267 +0,0 @@
-: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/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_optional.adoc b/content/extensions/mod_optional.adoc
deleted file mode 100644
index 1a4b967..0000000
--- a/content/extensions/mod_optional.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-: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/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_osgi.adoc b/content/extensions/mod_osgi.adoc
deleted file mode 100644
index 3a3ffd4..0000000
--- a/content/extensions/mod_osgi.adoc
+++ /dev/null
@@ -1,116 +0,0 @@
-: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/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_remote.adoc b/content/extensions/mod_remote.adoc
deleted file mode 100644
index ce303ed..0000000
--- a/content/extensions/mod_remote.adoc
+++ /dev/null
@@ -1,115 +0,0 @@
-: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();
- }
- }
-
-}
------------------------------------------------
[08/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
Posted by po...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/api.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/api.adoc b/content/documentation/api.adoc
new file mode 100644
index 0000000..1dd1d41
--- /dev/null
+++ b/content/documentation/api.adoc
@@ -0,0 +1,687 @@
+:jbake-type: page
+:jbake-status: published
+
+[[CoreDesign]]
+== Apache Tamaya: API
+
+Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
+that are 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.
+ ** +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.
+ ** +ConfigurationContext+, which provides a container for all the artifacts needed to build up a +Configuration+.
+ For example a context contains the property sources, property filters, converters and combination policy used.
+ Also the ordering of the property sources is defined by the context. A context instance given a
+ +Configuration+ can be created by calling +ConfigurationProvider.createConfiguration(context);+.
+ ** Similarly a +ConfigurationContext+ can be created using a +ConfigurationContextBuilder+. This builder can be
+ obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+.
+ ** +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 Type Conversion
+
+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 created from a +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 artifacts that determine the final +Configuration+ and
+also defines the ordering of the property sources, filters and converters contained:
+
+* +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
+
+A +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed. 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 changed, 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
+
+* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the
+ current +ConfigurationContext+.
+* calling +ConfigurationProvider.getConfigurationContextBuilder()+.
+
+[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+
+--------------------------------------------
+ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext()
+ .toBuilder();
+ .addPropertySources(new MyPropertySource())
+ .addPropertyFilter(new MyFilter())
+ .build();
+--------------------------------------------
+
+Hereby the builder provides several methods for adding, removing of property sources and also operations
+for programmatically change the property sourcepriorities, e.g.
+
+[source,java]
+.Chain manipulation using +ConfigurationContextBuilder+
+--------------------------------------------
+PropertySource propertySource = builder.getPropertySource("sourceId");
+
+// changing the priority of a property source. The ordinal value hereby is not considered.
+// Instead the position of the property source within the chain is changed.
+builder.decreasePriority(propertySource);
+
+// Alternately a comparator expression can be passed to establish the defined ordering...
+builder.sortPropertyFilters(MyFilterComparator::compare);
+--------------------------------------------
+
+Finally if the new context is ready a new configuration can be created, or the context is applied to the
+current configuration.
+
+[source,java]
+.Creating and applying a new +ConfigurationContext+
+--------------------------------------------
+ConfigurationContext context = builder.build();
+
+// Creates a new matching Configuration instance
+Configuration newConfig = ConfigurationProvider.createConfiguration(context);
+
+// Apply the new context to replace the current configuration:
+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+.
+
+= Interface ConfigurationContextBuilder
+
+include::temp-properties-files-for-site/attributes.adoc[]
+
+[[BuilderCore]]
+== Interface ConfigurationContextBuilder
+=== Overview
+
+The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
+e.g. as follows:
+
+[source,java]
+---------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+// do something
+Configuration config = builder.build();
+---------------------------------------------------------------
+
+Basically the builder allows to create configuration instances completely independent of the current configuration
+setup. This gives you full control on the +Configuration+ setup.
+
+
+=== Supported Functionality
+
+The builder allows you to add +PropertySource+ instances:
+
+[source,java]
+----------------------------------------------------------------
+ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder();
+builder.addPropertySources(sourceOne, sourceTwo, sourceThree
+Configuration config = ConfigurationProvider.createConfiguration(builder.build());
+----------------------------------------------------------------
+
+Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided
+by the property sources. This allows alternate ordering policies easily being implemented because
+creating a configuration based on a configuration context is already implemented and provided by the core
+API.
+
+Similarly you can add filters:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertyFilters(new MyConfigFilter());
+----------------------------------------------------------------
+
+...or +PropertySourceProvider+ instances:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertySourceProvider(new MyPropertySourceProvider());
+----------------------------------------------------------------
+
+
+
+[[ServiceContext]]
+==== The ServiceContext
+
+The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya.
+The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the
++ServiceContextManager+ singleton:
+
+[source,java]
+.Accessing the +ServiceContext+
+--------------------------------------------
+ServiceContext serviceContext = ServiceContextManager.getServiceContext();
+
+public interface ServiceContext{
+ int ordinal();
+ <T> T getService(Class<T> serviceType);
+ <T> List<T> getServices(Class<T> serviceType);
+}
+--------------------------------------------
+
+With the +ServiceContext+ a component can be accessed in two different ways:
+
+. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally
+ the most significant instance is returned only.
+. access all items given its type. This will return (by default) all instances loadedable from the current
+ runtime context, ordered by priority, hereby the most significant components added first.
+
+
+## Examples
+### Accessing Configuration
+
+_Configuration_ is obtained from the ConfigurationProvider singleton:
+
+[source,java]
+.Accessing +Configuration+
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+--------------------------------------------
+
+Many users in a SE context will probably only work with _Configuration_, since it offers all functionality
+needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is
+very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _Optional_ is supported:
+
+[source,java]
+--------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+String myKey = config.get("myKey"); // may return null
+int myLimit = config.get("all.size.limit", int.class);
+--------------------------------------------
+
+
+### Environment and System Properties
+
+By default environment and system properties are included into the _Configuration_. So we can access the current
+_PROMPT_ environment variable as follows:
+
+[source,java]
+--------------------------------------------
+String prompt = ConfigurationProvider.getConfiguration().get("PROMPT");
+--------------------------------------------
+
+Similary the system properties are directly applied to the _Configuration_. So if we pass the following system
+property to our JVM:
+
+[source,java]
+--------------------------------------------
+java ... -Duse.my.system.answer=yes
+--------------------------------------------
+
+we can access it as follows:
+
+[source,java]
+--------------------------------------------
+boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class);
+--------------------------------------------
+
+
+### Adding a Custom Configuration
+
+Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
+_tamaya-spi-support_ module you just have to perform a few steps:
+
+. Define a PropertySource as follows:
+
+[source,java]
+--------------------------------------------
+ public class MyPropertySource extends PropertiesResourcePropertySource{
+
+ public MyPropertySource(){
+ super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL);
+ }
+ }
+--------------------------------------------
+
+Then register +MyPropertySource+ using the +ServiceLoader+ by adding the following file:
+
+[source,listing]
+--------------------------------------------
+META-INF/services/org.apache.tamaya.spi.PropertySource
+--------------------------------------------
+
+...containing the following line:
+
+[source,listing]
+--------------------------------------------
+com.mypackage.MyPropertySource
+--------------------------------------------
+
+
+[[APIImpl]]
+== API Implementation
+
+The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for
+further details.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/core.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/core.adoc b/content/documentation/core.adoc
new file mode 100644
index 0000000..139eade
--- /dev/null
+++ b/content/documentation/core.adoc
@@ -0,0 +1,214 @@
+:jbake-type: page
+:jbake-status: published
+
+[[Core]]
+== Tamaya Core Implementation
+=== Overview
+
+Tamaya Core provides an implementation of the link:API.html[Tamaya Configuration API] and adds additional functionality
+and building blocks for supporting SPI implementations.
+
+Tamaya Core contains the following artifacts:
+
+* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+
+* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based
+ on the +@Priority+ annotations.
+* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances
+hereby providing type conversion for all important types.
+* A simple default configuration setup using the current classpath and an optional staging variable.
+* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and
+ registers them in the global +ConfigurationContext+
+* It provides a +ConfigurationContextBuilder+ implementation (class +DefaultConfigurationContextBuilder+) and allows
+ changing the current +ConfigurationContext+.
+
+The overall size of the library is very small. All required components are implemented and registered, so basically the
+Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible
+enough to be extended/accommodated with additional features as needed, such as
+
+* placeholder and resolution mechanisms
+* dynamic resource path lookup, e.g. with ant styled patterns
+* configuration injection and configuration templates
+* abstraction for reusable formats
+* integration with other existing solutions
+* configuration and configuration isolation targeting Java EE
+* dynamic configuration and configuration updates
+* Configuration management extensions
+* remote configuration
+* and more
+
+For details about the extension modules available and their functionality refer to the link:modules.html[extension user guide].
+
+
+[[CorePropertyConverters]]
+=== Default PropertyConverters in Core
+
+As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the
+listing of converters automatically registered with the Core module:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Target Type_ |_Class Name_ |_Supported Formats_
+|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF
+|java.math.BigInteger |BigIntegerConverter |0xFF, 1234
+|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
+|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
+|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123
+|java.ui.lang.Class |ClassConverter |<fully qualified class name>
+|java.util.Currency |CurrencyConverter |CHF, 123
+|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|_Enums_ |EnumConverter |<Enum item name>
+|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
+|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
+|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
+|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
+|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
+|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
+|ZoneId |ZoneIdConverter |Europe/Zurich
+|=======
+
+
+=== Registering PropertyConverters
+
+Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+,
+meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified
+class names of the converters to be registered (one line per each).
+
+Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically.
+
+NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically.
+
+
+[[ComponentLoadingAndPriorization]]
+=== Component Loading and Priorization
+
+Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components
+must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified
+implementation class names of the components to be registered (one line per each).
+The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya
+core adds this functionality by the possibility to add +@Priority+ annotations to the components registered.
+By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning
+
+* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value
+ effectively _overrides/replaces_ any component with lower values.
+* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the
+ ones with higher priority are before components with lower priority.
+* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is
+ still defined and predictable in almost all scenarios.
+
+NOTE: Sorting the property sources based on their ordinal value is only the default ordering principle applied. By implementing
+ your own implementation of +ConfigurationProviderSpi+ you can apply a different logic:
+
+
+[[RegisteringPropertySources]]
+=== Registering Property Sources
+
+PropertySources that provide configuration properties are registered as ordinary components as described in the previous
+section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit
++int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful
+due to several reasons:
+
+* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being
+ added easily.
+* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or
+ whatever may be appropriate.
+
+
+[[CorePropertySources]]
+== Configuration Setup in Core
+
+Tamaya Core provides a minimal configuration setting, that allows you to configure SE
+applications already easily. Basically configuration is built up by default as follows:
+
+. Read environment properties and add them prefixed with +env.+
+. Read all files found at +META-INF/javaconfiguration.properties+
+ and +META-INF/javaconfiguration.xml+
+
+
+=== Overview of Registered Default Property Sources and Providers
+
+The Tamaya Core implementation provides a couple of default +PropertySource+ implementations, which are automatically
+registered. They are all in the package +org.apache.tamaya.core.propertysource+ and
++org.apache.tamaya.core.provider+:
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Type_ |_Class Name_ |_Ordinal Used_
+|META-INF/javaconfiguration.properties |JavaConfigurationProvider |0
+|META-INF/javaconfiguration.xml |JavaConfigurationProvider |0
+|Environment Properties |EnvironmentPropertySource |300
+|System Properties |SystemPropertySource |400
+|=======
+
+
+=== Abstract Class PropertiesFilePropertySource
+
+The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+
+instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor:
+
+[source,java]
+--------------------------------------------
+PropertiesFilePropertySource(URL url);
+--------------------------------------------
+
+
+==== Abstract Class PropertiesPropertySource
+
+The abstract class +PropertiesPropertySource+ can be used for implementing a +PropertySource+ based on a +Properties+
+instance. It requires a +PropertySource+ to be passed on the constructor:
+
+[source,java]
+--------------------------------------------
+PropertiesPropertySource(Properties properties);
+--------------------------------------------
+
+
+==== Abstract Class BasePropertySource
+
+The abstract class +BasePropertySource+ can be used for implementing custom +PropertySource+ classes. It requires only
+one method to implemented:
+
+[source,java]
+.Implementing a PropertySource using BasePropertySource
+--------------------------------------------
+public class MyPropertySource extends BasePropertySource{
+
+ public String getName(){
+ // return a unique name for the property source, e.g. based on the underlying resource. This name also
+ // allows to access the property source later
+ }
+
+ public Map<String, String> getProperties(){
+ // Get a map with all properties provided by this property source
+ // If the property source is not scannable, the map returned may be empty.
+ // In the ladder case the +boolean isScannale()+ must be overridden, since
+ // by default property sources are assumed to be scannable.
+ }
+
+}
+--------------------------------------------
+
+By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in
++PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override
+the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+.
+
+
+[[CorePropertySourceProviders]]
+=== Default PropertySourceProvider in Core
+
+With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+
+present that loads all .properties files found at +META-INF/javaconfiguration.properties+
+and +META-INF/javaconfiguration.xml+.
+
+
+[[Extensions]]
+== Adding Extensions
+
+The Core module only implements the link:API.html[API]. Many users require/wish additional functionality from a
+configuration system. Fortunately there are numerous extensions available that add further functionality.
+Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath.
+
+For detailed information on the extensions available refer to the link:extensions.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc
new file mode 100644
index 0000000..a95f22f
--- /dev/null
+++ b/content/documentation/extensions.adoc
@@ -0,0 +1,62 @@
+:jbake-type: page
+:jbake-status: published
+
+== Apache Tamaya: Extension Modules
+
+toc::[]
+
+=== Mature Extensions
+
+Mature extensions have a stable API and SPI, similar to the API and Implementations provided.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+| | N/A: currently no extensions have reached that maturity level. | -
+|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. | link:extensions/mod_filter.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-injection-cdi-se+ | Java EE/standalone compliant CDI integration using Tamaya SE injection mechanism. | link:extensions/mod_cdi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation]
+|=======
+
+
+=== Extensions Sandbox
+
+Extensions in _draft state_ rather experimental or not yet very mature. API changes may occurr at any time
+and the may also have severe issues. So use at your own risk or join and help us getting them stable and
+well tested!
+
+NOTE: All extensions currently run on Java 7 as well as on Java 8.
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_ |_Description_ |_Links_
+|+org.apache.tamaya.ext:tamaya-commons+ |Combines Tamaya's Format Abstraction with Apache Commons. | -
+|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-metamodel+ |Provides support defining configuration using XML based meta-configuration. |link:extensions/mod_metamodel.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-validation+ |Provides support for XML based meta-configuration allowing to validate configuration read. |link:extensions/mod_validation.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-usagetracker+ |Provides support tracking of configuration usage and the consumer locations consuming configuration. |link:extensions/mod_usagetracker.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-consul+ | Integration with consul clusters. | link:extensions/mod_consul.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-etcd+ | Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-configured-sysprops+ | Allows Tamaya to integrate with +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-ui+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation]
+|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_builder.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_builder.adoc b/content/documentation/extensions/mod_builder.adoc
new file mode 100644
index 0000000..a589374
--- /dev/null
+++ b/content/documentation/extensions/mod_builder.adoc
@@ -0,0 +1,83 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Builder
+
+[[BuilderCore]]
+== Tamaya Builder (Extension Module)
+=== Overview
+
+The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
+e.g. as follows:
+
+[source,java]
+---------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+// do something
+Configuration config = builder.build();
+---------------------------------------------------------------
+
+Basically the builder allows to create configuration instances completely independent of the current configuration
+setup. This gives you full control on the +Configuration+ setup.
+
+=== Compatibility
+
+The module is based on Java 7, so it will run on Java 7 and does
+not require Java 8. The +ConfigurationProvider+
+as defined by the API, provides a builder instance for +ConfigurationContext+
+in a similar way. A +Configuration+ can also be created by passing an instance of a +ConfigurationContext+:
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding
+dependency to your module:
+
+[source,xml,subs="verbatim,attributes"]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-builder</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+=== Supported Functionality
+
+The builder allows you to add +PropertySource+ instances:
+
+[source,java]
+----------------------------------------------------------------
+ConfigurationBuilder builder = new ConfigurationBuilder();
+builder.addPropertySources(sourceOne).addPropertySources(sourceTwo);
+Configuration config = builder.build();
+----------------------------------------------------------------
+
+Similarly you can add filters:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertyFilters(new MyConfigFilter());
+----------------------------------------------------------------
+
+...or +PropertySourceProvider+ instances:
+
+[source,java]
+----------------------------------------------------------------
+builder.addPropertySourceProvider(new MyPropertySourceProvider());
+----------------------------------------------------------------
+
+Also the builder module allows to include/exclude any filters and property source already known to the current
++ConfigurationContext+:
+
+[source,java]
+----------------------------------------------------------------
+builder.disableProvidedPropertyConverters();
+builder.enableProvidedPropertyConverters();
+
+builder.disableProvidedPropertyFilters();
+builder.enableProvidedPropertyFilters();
+
+builder.disableProvidedPropertySources();
+builder.enableProvidedPropertySources();
+----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_camel.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_camel.adoc b/content/documentation/extensions/mod_camel.adoc
new file mode 100644
index 0000000..9690dda
--- /dev/null
+++ b/content/documentation/extensions/mod_camel.adoc
@@ -0,0 +1,129 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Integration with Apache Camel
+
+toc::[]
+
+
+[[Optional]]
+== Integration with Apache Camel (Extension Module)
+=== Overview
+
+The Tamaya Camel integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with Apache Camel.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from configuration builder support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-camel</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Camel integration comes basically with three artifacts:
+
+* A Camel +ResolverFunction+ implementation adding explicit property resolution
+ (+org.apache.tamaya.integration.camel.TamayaPropertyResolver+).
+* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and
+ additionally allows using Tamaya configuration as Camel _overrides_
+ (+org.apache.tamaya.integration.camel.TamayaPropertiesComponent+).
+
+
+=== Configuring using Camel Java DSL
+
+Camel integration using Java DSL is basically simple:
+
+[source, java]
+-----------------------------------------------
+import org.apache.tamaya.integration.camel.TamayaPropertiesComponent;
+
+camelContext.addComponent("properties", new TamayaPropertiesComponent());
+-----------------------------------------------
+
+Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows:
+
+[source, java]
+-----------------------------------------------
+RouteBuilder builder = new RouteBuilder() {
+ public void configure() {
+ from("direct:hello1").transform().simple("{{cfg:message}}");
+ }
+};
+camelContext.addRoutes(builder);
+builder = new RouteBuilder() {
+ public void configure() {
+ from("direct:hello2").transform().simple("{{tamaya:message}}");
+ }
+};
+camelContext.addRoutes(builder);
+-----------------------------------------------
+
+
+Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used
+as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel
++PropertiesComponent+:
+
+[source, java]
+-----------------------------------------------
+TamayaPropertiesComponent props = new TamayaPropertiesComponent();
+props.setTamayaOverrides(true);
+-----------------------------------------------
+
+
+=== Configuring using Camel XML DSL
+
+Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean
+as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we
+again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback:
+
+[source, xml]
+-----------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
+ ">
+
+ <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring">
+ <route id="r1">
+ <from uri="direct:hello1"/>
+ <transform>
+ <simple>{{message}}</simple>
+ </transform>
+ </route>
+ <route id="r2">
+ <from uri="direct:hello2"/>
+ <transform>
+ <simple>{{cfg:message}}</simple>
+ </transform>
+ </route>
+ <route id="r3">
+ <from uri="direct:hello3"/>
+ <transform>
+ <simple>{{tamaya:message}}</simple>
+ </transform>
+ </route>
+ </routeContext>
+
+ <bean id="properties" class="org.apache.tamaya.integration.camel.TamayaPropertiesComponent">
+ <property name="tamayaOverrides" value="true"/>
+ </bean>
+
+</beans>
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_cdi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_cdi.adoc b/content/documentation/extensions/mod_cdi.adoc
new file mode 100644
index 0000000..c49a61c
--- /dev/null
+++ b/content/documentation/extensions/mod_cdi.adoc
@@ -0,0 +1,217 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya CDI Integration (Extension Modules)
+=== Overview
+
+Apache Tamaya currently provides two implementations for integration with CDI extensions implementing similar
+functionality as described in this document:
+
+* Loading of CDI managed SPI components as configuration extensions such as +PropertySources, PropertySourceProviders,
+ PropertyFilters, etc+. This also includes SPI defined by any Tamaya submodules.
+* Implement and enable Tamaya's configuration injection services with CDI.
+
+Hereby there are two implementations provided:
+
+* +tamaya-cdi-ee+ implements injection by using CDI's injection mechanism to inject configuration values into the
+ beans managed by the CDI systems.
+* +tamaya-cdi-se+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used
+ for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas
+ beans and injection control overall are still managed by CDI.
+* One difference, of course, is that +tamaya-se+ also provides an SE compatible API (+ConfigurationInjection,
+ ConfigurationInjector+), which is not available, when using the purely Java EE based variant.
+
+The annotations used for all injection functionality in Tamaya is defined as a separate module. This allows you to
+code against the injection API without dependency on the concrete injection implementation. As a consequence your
+components will be compatible regardless if deployed in a pure SE, a Java EE (CDI) or OSGI or Spring environment:
+
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection-api</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Compatibility
+
+Both modules are based on Java 7, so they will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya CDI integration you only must one of the following dependencies to your module. Ensure that
+you never have installed both CDI extensions at the same time because this may be lead to unforseen side-effects.
+
+.CDI Pure Application Configuration
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-cdi-ee</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+.CDI enhanced with Tamaya SE Application Configuration
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-cdi-se</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they
+register CDI extensions that implement Configuration injection as described before.
+
+IMPORTANT: Never install Tamaya's +tamaya-cdi-se+ and +tamaya-cdi-ee+ on the same system, since unpredictable side
+ effects could occur.
+
+=== Registering CDI managed components into the Application's ConfigurationContext
+
+As mentioned both modules allow to provide Tamaya SPI extensions modules as ordinary CDI managed beans. By default
+extensions should be registered using +@Singleton+ or +@ApplicationScoped+ scope annotations. So you can define/deploy
+additional application specific +PropertySources+ and other artifacts simply by defining a CDI managed bean implementing
+the required SPI interface:
+
+[source, java]
+--------------------------------------------------------
+@Singleton
+public class TestPropertySource implements PropertySource{
+
+ final Map<String,String> config = new HashMap<>();
+
+ public TestPropertySource(){
+ config.put("a.b.c.key1", "keys current a.b.c.key1");
+ config.put("a.b.c.key2", "keys current a.b.c.key2");
+ config.put("{"+getName()+"}source", getClass().getName());
+ }
+
+ @Override
+ public int getOrdinal() {
+ return 10;
+ }
+
+ @Override
+ public String getName() {
+ return getClass().getName();
+ }
+
+ @Override
+ public String get(String key) {
+ return config.get(key);
+ }
+
+ @Override
+ public Map<String, String> getProperties() {
+ return config;
+ }
+
+ @Override
+ public boolean isScannable() {
+ return true;
+ }
+}
+--------------------------------------------------------
+
+Note that for many SPI's there is a priority mechanism using +@Priority+ annotations in place.
+The +ServiceContext+ implementation combines the components registered with the ones loaded from the +ServiceLoader+
+mechanism hereby considering classloaser hierarchies.
+
+
+=== Annotating your Classes
+
+Basically annotating your classes is stright forward. +@Config+ defines an additional CDI qualifier that is, depending
+on the module deployed, handled by a CDI producer (+tamaya-cdi-ee+) or the Tamaya SE injection mechanism $
+(+tamaya-cdi-se+). All types injected by this module are injected using _dependent scope_.
+
+
+[source, java]
+--------------------------------------------------------
+@RequestScoped
+public class ConfiguredClass{
+
+ @Config
+ private String testProperty;
+
+ @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"})
+ @ConfigDefault("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
+ String value1;
+
+ @Config({"foo","a.b.c.key2"})
+ private String value2;
+
+ @Config
+ @ConfigDefault("N/A")
+ private String runtimeVersion;
+
+ @Config
+ @ConfigDefault("${sys:java.version}")
+ private String javaVersion2;
+
+ @Config
+ @ConfigDefault("5")
+ private Integer int1;
+
+ ...
+
+}
+--------------------------------------------------------
+
+=== Advanced Use Cases
+
+Beside basic configuration Tamaya also covers additional requirements:
+
+* _Reading multiple keys, where the first successful one is determining the value of the configuration, is
+ simply possible, by adding multiple keys to the +@Configy+ annotation.
+ E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Config({"a.b", "new.b"}
+private String value;
+--------------------------------------------------------------------------------------
+
+* When you must apply a +ConfigOperator+ to your config, before reading the configuration, you can
+ configure one as follows:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Config({"a.b", "new.b"}
+@WithConfigOperator(MyOperator.class)
+private String value;
+--------------------------------------------------------------------------------------
+
+* When you must apply a some special conversion, or you use a type that is not registered
+ for conversion, you can configure a custom converter to be applied as follows:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Config({"a.b", "new.b"}
+@WithPropertyConverter(MyConverter.class)
+private MySpecialFooType value;
+--------------------------------------------------------------------------------------
+
+* Often multiple keys in a class belong to the same root section. So instead of copying this to
+ every entry you can define the most common root sections in the type's header:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@ConfigDefaultSections({"aaaa", "new"});
+public class MyType{
+
+@Config({"b", "[legacy.bKey]"} // lookups: "aaaa.b", "new.b", legacy.bKey
+private String value;
+--------------------------------------------------------------------------------------
+
+In the example above +legacy.bKey+ defines an absolute key, which is not combined with any defined
+default section parts.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_classloader_support.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_classloader_support.adoc b/content/documentation/extensions/mod_classloader_support.adoc
new file mode 100644
index 0000000..9a2d0df
--- /dev/null
+++ b/content/documentation/extensions/mod_classloader_support.adoc
@@ -0,0 +1,75 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+
+toc::[]
+
+[[Remote]]
+== Tamaya Classloader Aware ServiceContext (Extension Module)
+=== Overview
+
+The Tamaya classloader support provides an alternative implementation of +java.util.ServiceLoader+, which is aware
+of classloaders, hereby preventing multiple loading of components within a classloader hierarchy.
+
+
+=== 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-classloader-support</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+The component will auto.register its components and override the default +ServicceContext+ in use by default
+with an instance of type +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+. This implementation returns
+a priority of +10+.
+
+=== How it works
+
+Basically the component manages a +Map+ of all classloaders encountered. When services are accessed, the component
+will evaluate the services as follows:
+
+* the component walks up the class loader hierarchy.
+* in a next step the hierarchy is traversed down from the parent to the current classloader. Hereby it is checked
+ if the service list for the required type has been loaded already. If not the service configuration files are
+ evaluated.
+* This configuration file evaluation will ignore all resources already loaded by any of the already traversed parent
+ classloaders.
+* For each configuration file newly visible to the classloader currently traversed, the corresponding services are
+ loaded unleyy, the same service class already has been loaded by one its parent classloaders or another file
+ loaded with this classloader.
+* Finally all services found are returned as the full collection of services valid for the given context (classloader).
+
+This ensures no service is loaded multiple times, even when it is referenced multiple times in several service
+configurations. Additionally every service is loaded on the classloader where it is also declared the first time.
+
+
+=== Control Logging
+
+The service component by default only logs errors. But it is possible to change this by reconfiguring the logging
+levels on the following logging names/path: +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+
+
+* _INFO_ logs additional info on the services accessed.
+* _FINEST_ logs additional info on the services scanned and selected.
+
+
+=== Classloader Aware Configuration
+
+The mechanism above is used to provide a classloader aware implementation of +ConfigurationContext+
+(+org.apache.tamaya.clsupport.internal.CLAwareConfigurationContext+). Similarly to the service variants
+this class provides a context implementation that manages the core configuration aspects considering classloading
+hierarchies:
+
+* +PropertySource+, +PropertySourceProviders+
+* +PropertyFilters+, +PropertyCombinationPolicy+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_collections.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_collections.adoc b/content/documentation/extensions/mod_collections.adoc
new file mode 100644
index 0000000..e758756
--- /dev/null
+++ b/content/documentation/extensions/mod_collections.adoc
@@ -0,0 +1,232 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Collection Support
+
+toc::[]
+
+[[Optional]]
+== Tamaya Collection Support (Extension Module)
+=== Overview
+
+All configuration in Tamaya is expressed as simple key, value pairs. Nevertheless this concept allows similarly
+the modelling of collection typed values such as lists, sets, maps or simple collections of things. The Tamaya
+Collections extension adds this functionality to the Tamaya eco-system.
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To use Tamaya collection support you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-collections</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Overview
+
+Tamaya Collections adds +PropertyConverter+ implementations that are able to access configuration data
+as lists, maps or sets. By default this works out of the box as easy as accessing any other type of
+configuration data, e.g.
+
+[source, java]
+-----------------------------------------------
+Configuration config = ConfigurationProvider.getConfiguration();
+
+// Without any content specification, a list of String is returned.
+List<String> simpleList = config.get("my.list.config.entry", List.class);
+
+// Using a TypeLiteral allows to use every convertible sub type supported by the system.
+List<Integer> intList = config.get("my.list.config.entry", new TypeLiteral<List<Integer>>(){});
+-----------------------------------------------
+
+Configuration in that case, by default, is a simple comma-separated list of entries, e.g.
+
+[source, properties]
+-----------------------------------------------
+my.list.config.entry=1,34454,23,344545,3445
+-----------------------------------------------
+
+Additionally the module allows adding additional meta-entries, which allows to tweak some of the
+inner-workings, e.g.
+
+* using your own +PropertyConverter+ implementation for parsing entries.
+* specifying a custom separator String to be used to split the items (default is {{','}}.
+* specifying a custom separator String to be used to split key/value paris when parsing map entries.
+* specifying the implementation type of the collection instance to be returned.
+* specifying if the resulting collection should be returned as a modifiable collection.
+
+=== Supported Types
+
+This module supports the following types:
+
+* +java.util.Collection+
+* +java.util.List+
+* +java.util.ArrayList+
+* +java.util.LinkedList+
+* +java.util.Set+
+* +java.util.SortedSet+
+* +java.util.TreeSet+
+* +java.util.HashSet+
+* +java.util.Map+
+* +java.util.SortedMap+
+* +java.util.HashMap+
+* +java.util.TreeMap+
+
+Hereby the type is determined primarly by the parameter type accessed, e.g.
++config.get("mylist", ArrayList.class)+ will always return an +ArrayList+
+as result.
+
+==== Configuring the target implementation type
+
+Tamaya Collections allows you to configure the target collection type by adding the
+following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+
+can be ommitted:
+
+[ source, properties]
+-----------------------------------------------
+mylist=a,b,c
+_mylist.collection-type=LinkedList
+-----------------------------------------------
+
+When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still
+get an +ArrayList+ as a result. However when you call +config.get("mylist", List.class)+ you will
+get a +LinkedList+ as implementation type.
+
+This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation
+type returned when accessing +List+, +Map+ or +Collection+.
+
+
+=== Collecting Configuration Entries instead of Overriding
+
+By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for
+the most significant configuration entry is used. In case of collections (and maybe also other use cases),
+overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your
+configuration to be *combined* to a new entry containing all values provided by any property sources.
+
+Therefore Tamaya Collections also provides a more sophistiated +CombinationPolicy+ (automatically configured)
+that allows to adapt the way how configuration entries are combined. All you must do is declaring
+the mechanism to be applied by an according meta-configuration parameter, e.g. for +my.list+ your config may
+look as follows:
+
+[source, properties]
+-----------------------------------------------
+# from PropertSource 1
+my.list=1,2,3
+
+# from PropertSource 2
+my.list=4,5,6
+
+# without any additional meta-info these entries would be combined to
+my.list=4,5,6
+-----------------------------------------------
+
+With Tamaya Collections you can now configure the combination policy as follows:
+
+[source, properties]
+-----------------------------------------------
+# use one of the default policies: override / collect
+_my.list.combination-policy=collect
+
+# use an custom CombinationPolicy to combine the values
+_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy
+-----------------------------------------------
+
+So declaring the +collect+ policy the resulting raw output of the entry looks as follows:
+
+[source, properties]
+-----------------------------------------------
+# result when applying the collect policy:
+my.list=1,2,3,4,5,6
+-----------------------------------------------
+
+The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration
+parameter explained later in this document.
+
+
+=== Format of Collection Configuration
+
+By default collections are modelled as simple String values, that are tokenized into individual parts using a
+defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3".
+If the target context type is something different than String the smae conversion logic is used as when mapping
+configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed
+within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types,
+with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+.
+The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas
+for values the same logic is applied as for non-map collection types.
+
+[source, properties]
+-----------------------------------------------
+# a list, using the default format
+list=1,2,3,4,5,6
+
+# a map, using the default format
+map=a::b, c::d
+-----------------------------------------------
+
+==== Trimming of entries
+
+By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is
+also the case for key/value entries. So the following configuration results in the identical values for
++list1,list2+ and +map1,map2+:
+
+[source, properties]
+-----------------------------------------------
+# a list, using the default format
+list1=1,2,3,4,5,6
+list2=1, 2, 3, 4, 5, 6
+
+# a map, using the default format
+map1=a::b, c::d
+map2=a :: b, c :: d
+-----------------------------------------------
+
+Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
+space character as value:
+
+[source, properties]
+-----------------------------------------------
+# a list, with a ' ' value at the end
+list3=1, 2, 3, 4, 5, [ ]
+
+# a map, with a ' ' value for key '0'
+map3=1 :: a, 2 :: b, 0::[ ]
+-----------------------------------------------
+
+Hereby +\[+ escapes the sequence.
+
+
+==== Customizing the format
+
+The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data
+entries as follows, resulting in the same values as in the prevoius listing:
+
+[source, properties]
+-----------------------------------------------
+# a list, with a ' ' value at the end
+list3=1__2__3__ 4__ 5__[ ]
+_list3.item-separator=__
+
+# a map, with a ' ' value for key '0'
+map3=1->a, 2->b, 0->[ ]
+_map3.map-entry-separator=->
+-----------------------------------------------
+
+Of course these settings also can be combined:
+
+[source, properties]
+-----------------------------------------------
+# a reformatted map
+redefined-map=0==none | 1==single | 2==any
+_redefined-map.map-entry-separator===
+_redefined-map.item-separator=|
+-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_consul.adoc b/content/documentation/extensions/mod_consul.adoc
new file mode 100644
index 0000000..4407ed3
--- /dev/null
+++ b/content/documentation/extensions/mod_consul.adoc
@@ -0,0 +1,59 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Integration with consul (Hashicorp)
+
+toc::[]
+
+
+[[Optional]]
+== Integration with consul (Extension Module)
+=== Overview
+
+The Tamaya consul integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with consul. Basically the module supports read-only integration (as a +ConsulPropertySource+ as well
+as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension 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-consul</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Consul integration comes basically with 2 artifacts:
+
+* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
+ 'consul', which is automatically registered.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
+ by accessing a +MutableConfiguration+ using the URI +config:consul+.
+
+
+=== The ConsulPropertySource
+
+The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This
+enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
+in microservice containers to connect with the according consul cluster:
+
+* The property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible etcd servers
+ (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
+ configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
+ server can be established a warning will be logged, but deployment will not fail.
+* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed
+ context. This can be activated by setting the +-Dtamaya.consul.prefix=<PREFIX>+ system property. E.g. when the prefix is
+ set to +cluster-config.+ a consul key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/extensions/mod_environment.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_environment.adoc b/content/documentation/extensions/mod_environment.adoc
new file mode 100644
index 0000000..c0224a1
--- /dev/null
+++ b/content/documentation/extensions/mod_environment.adoc
@@ -0,0 +1,42 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Classloader Isolation Support
+
+toc::[]
+
+
+[[Remote]]
+== Tamaya Environment Model (Extension Module)
+=== Overview
+
+The Tamaya Environment extension adds a simple PropertySourceProvider that evaluates a List of environment context and
+combines them in the given order into an (optional) root context within the system's configuration.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To benefit from Tamaya Environment Model you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-envionment</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== How it Works
+
+tbd
+
+=== Reusable Base Classes
+
+tbd