You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2014/11/28 07:19:03 UTC
incubator-tamaya git commit: Reorganized content hierarchy so GH page
rendering works.
Repository: incubator-tamaya
Updated Branches:
refs/heads/master ecacac496 -> f494f9fb1
Reorganized content hierarchy so GH page rendering works.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/f494f9fb
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/f494f9fb
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/f494f9fb
Branch: refs/heads/master
Commit: f494f9fb10ab987121ae3e616c733402d7155b3e
Parents: ecacac4
Author: anatole <an...@apache.org>
Authored: Fri Nov 28 07:18:55 2014 +0100
Committer: anatole <an...@apache.org>
Committed: Fri Nov 28 07:18:55 2014 +0100
----------------------------------------------------------------------
docs/Design.adoc | 112 +++++++++
docs/design/0_UseCases.adoc | 255 +++++++++++++++++++
docs/design/1_Requirements.adoc | 33 +++
docs/design/2_CoreConcepts.adoc | 299 +++++++++++++++++++++++
docs/pom.xml | 6 +-
docs/src/design/Design.adoc | 112 ---------
docs/src/design/content/0_UseCases.adoc | 255 -------------------
docs/src/design/content/1_Requirements.adoc | 33 ---
docs/src/design/content/2_CoreConcepts.adoc | 299 -----------------------
9 files changed, 702 insertions(+), 702 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/Design.adoc
----------------------------------------------------------------------
diff --git a/docs/Design.adoc b/docs/Design.adoc
new file mode 100644
index 0000000..f6e24d6
--- /dev/null
+++ b/docs/Design.adoc
@@ -0,0 +1,112 @@
+Apache Tamaya -- Design Documentation
+=====================================
+:name: Tamaya
+:rootpackage: org.apache.tamaya
+:title: Apache Tamaya
+:revnumber: 0.1-SNAPSHOT
+:revremark: Incubator
+:revdate: November 2014
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch, Anatole Tresch
+:email: <at...@gmail.com>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+
+'''
+
+<<<
+
+-> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[]
+
+toc::[]
+
+<<<
+:numbered!:
+-----------------------------------------------------------
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-----------------------------------------------------------
+
+:numbered:
+
+<<<
+
+== Introduction
+This document describes the {name} API for Configuration. The technical objective is to provide a
+unified configuration model in Java, targeting Java ME, SE as well as the EE platform.
+The API will provide support for key/value based application configuration. It will provide
+as well higher level APIs that are based on the low level ke</value pairs. Finally it will
+provide extension points for adding additional features and additional modules for extension
+or adaption.
+
+=== Working Group
+This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This
+specification is the result of the collaborative work of the members of the {name} Users Group and the community at
+large. Currently the project is lead by Anatole Tresch (atsticks at gmail.dot com).
+
+=== Goals
+Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of
+well defined aspects of a software product without having to recompile/rebuild the code.
+
+==== Targets
+{name} targets to support all general configuration aspects, e.g.
+
+* spplication configuration
+** plugins
+** modules
+** components
+* Configuration of Java EE related aspects for Java enterprise application portability and dynamic provisioning, such as
+** Configuration of CDI (interceptors, decorators and alternatives)
+** Configuration of Bean Validation, JSF, web applications etc.
+* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values, or by providing
+ accessors to evaluate current configuration vlues. This can be used explicitly or transparently by client code.
+
+Additionally the solution should support
+
+* multiple configuration locations, including remote locations
+* multiple configuration formats, including custom formats
+* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und URIs are supported by default.
+* type conversion
+* configuration of collections
+
+
+=== Required Java version
+The API is based on Java SE 8.0 language features.
+
+=== How this document is organized
+There are five main section in this document:
+
+* Use cases.
+* Requirements.
+* Specification.
+* Implementation Recommendations.
+* An appendix.
+
+include::design/0_UseCases.adoc[]
+include::design/1_Requirements.adoc[]
+include::design/2_CoreConcepts.adoc[]
+
+:numbered!:
+== APPENDIX
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/design/0_UseCases.adoc
----------------------------------------------------------------------
diff --git a/docs/design/0_UseCases.adoc b/docs/design/0_UseCases.adoc
new file mode 100644
index 0000000..5a95b4e
--- /dev/null
+++ b/docs/design/0_UseCases.adoc
@@ -0,0 +1,255 @@
+<<<
+[[Use Cases]]
+== Use Cases
+
+This section describes some, but not all, of the use cases that should be covered with this JSR.
+
+[[UC Simple Configuration]]
+=== Simple Property Based Configuration
+
+In this most simple usage scenario an application is created that is preconfigured by some property files contained in the
+Java archive. Using the command line it is possible to redefine/override some of the properties, e.g. by using system properties.
+Typical example are small command line tools.
+
+-> It must be possible to define default configuration and package it with the (SE) application.
+
+-> It must be possible to consider system properties or other command line arguments for usage with configuration.
+
+-> It must be possible that command line arguments can override defaults configured.
+
+[[UC Advanced Property Based Configuration]]
+=== Advanced Property Based Configuration
+
+Enhancing the previous scenario, we might as well consider the current environment. Saying that our overriding mechanisms
+must be improved, since
+
+* some environment settings should not be overridable
+* some defaults should be overridden by environment or system properties, whereas others may not
+
+Additionally the user may have an option, where he is allowed to define an external configuration file that should be used to configure
+the application. This is especially useful for applications with lots of command line options (under windows even command
+execution may fail die to exceeding command length). Finally application developers may have their own formats in place, so the
+system should be able to support these formats.
+
+-> Environment properties must be considered as well.
+
+-> It must be possible to control overriding.
+
+-> It must be possible to dynamically add configuration locations to be considered.
+
+-> It must be possible to define customized configuration formats.
+
+[[UC Modularized Configuration]]
+=== Modularized Configuration
+
+When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional things
+to be considered by a configuration system:
+
+* The different modules must have access to their own "module configuration".
+* Modules may want to define a contract, which properties may be overriden.
+
+Consequently
+
+-> Parts of Configuration must be identifiable and accessible in a isolated way.
+
+-> Module configuration requires partial isolation or other mechanisms to ensure only configuration aspects
+ that are allowed to be overriden can be overriden.
+
+[[UC Dynamic Provisioning]]
+=== Dynamic Provisioning
+
+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.
+
+Consequently:
+
+-> Ensure Configuration can be transferred over the network easily.
+
+-> Whereas many people will no think serializability is the solution, it would be much more useful to define
+ a text based format for serialization, e.g. in +XML+ or +JSON+.
+
+-> Similarly a management API should be defined, which allows to inspect the configuration in place, e.g. using
+ JMX or REST services.
+
+[[UC Java EE]]
+=== Java EE
+
+Considering Java EE different aspects should be considered:
+
+* Java EE is a complex multi-layered architecture with different levels of runtime contexts:
+** application server boot level (system classloader),
+** (optional) deployment/undeployment of ears (ear classloader),
+** (optional) deployment/undeployment of web applications (war classloader),
+** different runtime setups, e.g. EJB calls, MDB execution, Servlet Requests, scheduled and timed executions.
+* Configuring administrative resources (e.g. datasources, users, security etc) is typically vendor specific.
+* The environment is inherently multi-threaded.
+
+Given that a couple of additional requirements araise:
+
+-> 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.
+
+[[UC MultiTenancy]]
+=== Scenario MultiTenancy
+In multi tenancy setups a hierarchical/graph model of contexts for configurations is required. For example there might
+be some kind of layering as follows:
+
+* Layer 0: Low level system configuration
+* Layer 1: Domain configuration
+* Layer 2: Default App configuration
+* Layer 3: Tenant specific configuration
+* Layer 4: User specific configuration
+
+Configurations made in the tenant or user layer override the default app configuration etc.
+
+-> 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.
+
+[[UC Java API]]
+=== Accessing Configuration
+
+So far we described much how configuration must be organized and managed, but we got not concrete, how it is accessed.
+Basically there are two basic scenarios to be distinguished, which mainly depend on the way how the lifecycle of a component
+to be configured is managed:
+
+* If the lifecycle is managed manually by the developer, the configuration system
+** can inject configuration values, when explicitly called to to so
+** can provide an accessor for configuration.
+* If the lifecycle is managed by some container such as a DI container, the configuration
+ system should leverage the functionality of the container, where possible.
+
+The most simplest way is using injection, e.g. a POJO can be written as follows:
+
+[source, java]
+.Configured POJO Example
+----------------------------------------------------
+public class MyPojo {
+ @ConfigProperty("myCurrency")
+ @DefaultValue("CHF")
+ private String currency;
+
+ @ConfigProperty("myCurrencyRate")
+ private Long currencyRate;
+
+ // complex algorithm based on the currency
+}
+----------------------------------------------------
+
+The instance then can be passed for being configured:
+
+[source, java]
+.Configuring a POJO
+----------------------------------------------------
+MyPojo instance = new MyPojo();
+Configuration.configure(instance);
+----------------------------------------------------
+
+Another way of accessing configuration would be by defining a type safe template
+providing access to the configured values and let the configuration system implement
+the interface:
+
+[source, java]
+.Type Safe Configuration Template Example
+----------------------------------------------------
+public interface MyConfig {
+ @ConfigProperty("myCurrency")
+ @DefaultValue("CHF")
+ String getCurrency();
+
+ @ConfigProperty("myCurrencyRate")
+ Long getCurrencyRate();
+
+}
+----------------------------------------------------
+
+The configuration system will then implement the
+interface using configuration as follows:
+
+[source, java]
+.Accessing a type safe Configuration Template
+----------------------------------------------------
+MyConfig config = Configuration.of(MyConfig.class);
+----------------------------------------------------
+
+Finally there is a generic +Configuration+ type that can be used as well, which
+provides full access to all features:
+
+[source, java]
+.Accessing Configuration
+----------------------------------------------------
+Configuration config = Configuration.of(Configuration.class);
+----------------------------------------------------
+
+
+[[UC Testing]]
+=== Testing
+When testing a Java solution, it must be possible to easily control the configuration provided, so isolated
+component tests can be written effectively. Also it should be possible to control/isolate the configuration level for
+each test case.
+
+-> isolation of configuration services is required
+
+-> API for controlling the configuration provided, required for according implementations in the testing frameworks.
+
+[[UC Staging]]
+=== Staging
+Different companies go through different staging levels during the development of software components. Currently only
+rarely the EE frameworks support staging aspects, nevertheless no broader, well modelled staging concept is defined.
+Different companies also have different staging or sub-staging levels in place, which also must be reflected.
+Especially with sub-stages inheritance of stage related configuration is common sense and should be supported.
+
+-> Main stages available and to be supported must be defined.
+
+-> Enable additional stages to be added, so also custom stages can be supported.
+
+
+[[UC CotsIntegration]]
+=== Custom of the Shelf (COTS) Integration
+When buying software from an external software company it is often very cumbersome to integrate, adapt and customize
+third party software to the internal operational requirements. Especially, when software is delivered as ear modules
+portability is often very difficult and time consuming. Configuration should enable COTS providers to define a
+customization contract, which also can be part of the COTS software interface and integration specifications. This
+would allow operations to better control and configure third party solutions as possible, whereas in the evaluation
+phase the integration and configuration options can explicitly be defined.
+
+-> It must be possible to document configuration aspects supported.
+
+-> Configuration must be overridable from external sources (the operations which must operate the COTS solution).
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/design/1_Requirements.adoc
----------------------------------------------------------------------
diff --git a/docs/design/1_Requirements.adoc b/docs/design/1_Requirements.adoc
new file mode 100644
index 0000000..88c910e
--- /dev/null
+++ b/docs/design/1_Requirements.adoc
@@ -0,0 +1,33 @@
+<<<
+[[Requirements]]
+== Requirements
+=== Core Configuration Requirements
+Based on the scope and use cases described above the following core requirements can be identified:
+
+* Configuration is modelled as String based key/value pairs.
+* Configuration can be combined using the GoF composite pattern. Hereby different composition policies can be applied, such as
+ ** override: subsequent entries override existing ones.
+ ** substraction: keys present in the second configuration will be removed.
+ ** union-resolve: key/values were added, in case of conflicts a +ConfigException+ must be thrown.
+ ** union-ignore: similar to union, whereas duplicates are ignored (leaving the initial value loaded).
+ ** intersection:
+
+[[RequirementsServer]]
+=== Server Configuration Requirements
+shskjdhskhds sdkj ksjdks skjdskjd:
+
+. Req1
+. Req2
+
+[[RequirementsExtensions]]
+=== Extensions Requirements
+shskjdhskhds sdkj ksjdks skjdskjd:
+
+. Req1
+. Req2
+
+[[RequirementsNonFunctional]]
+=== Non Functional Requirements
+. Req1
+. Req2
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/design/2_CoreConcepts.adoc
----------------------------------------------------------------------
diff --git a/docs/design/2_CoreConcepts.adoc b/docs/design/2_CoreConcepts.adoc
new file mode 100644
index 0000000..9eeadf9
--- /dev/null
+++ b/docs/design/2_CoreConcepts.adoc
@@ -0,0 +1,299 @@
+<<<
+[[Core Concepts]]
+== {name} Core Concepts
+Though {name} is a very powerful and flexible solution there are basically only a few simple core concepts required that build
+the base of all the other mechanisms:
+
+* Key/Value Pairs
+* Property Providers
+* Meta Data
+* Combining property providers
+* Environment Model
+* Configuration
+* Configuration Injection
+
+These parts are explained in the following sections. It is recommended that user's of the API read through this part.
+All subsequent parts are building upon this concepts and may be more difficult to understand without having read
+this section.
+
+[[API KeyValues]]
+=== Key/Value Pairs
+
+Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple
+and similarly most commonly used are simple literal key/value pairs. So the core building block of {name} are key/value pairs.
+You can think of a common +.properties+ file, e.g.
+
+[source,properties]
+.A simple properties file
+--------------------------------------------
+a.b.c=cVal
+a.b.c.1=cVal1
+a.b.c.2=cVal2
+a=aVal
+a.b=abVal
+a.b2=abVal
+--------------------------------------------
+
+Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g.
+
+[source,properties]
+.Accessing some properties
+--------------------------------------------
+Properties props = new Properties();
+props.readProperties(...);
+String val = props.getProperty("a.b.c");
+val = props.getProperty("a.b.c.1");
+...
+--------------------------------------------
+
+This looks familiar to most of you. Nevertheless when looking closer to the above key/value pairs,
+there are more concepts in place: looking at the keys +a.b.c+, +a.b.c.1+, +a.b.c.2+, +a+, +a.b+ we
+see that the key names build up a flattened tree structure. So we can define the following:
+
+Given a key +p1.p2.p3.k=value+:
+
+* +p1.p2.p3.k+ is called the _qualified key_
+* +p1.p2.p3+ is the key's _area_
+* the child areas +p1.p2", "p1+ are called _areas_ as well
+* +k+ is the _(unqualified) key_
+
+Given that you can perform some very useful actions:
+
+* you can filter the keys with an area. E.g. in the example before you can query for all keys within the area +a.b.c+
+ and map them to new properties set as follows:
+
+[source,properties]
+.Accessing an area
+--------------------------------------------
+1=cVal1
+2=cVal2
+--------------------------------------------
+
+Similarly accessing the area +a+ results in the following properties:
+
+[source,properties]
+.Accessing the area +a+
+--------------------------------------------
+b=abVal
+b2=abVal
+--------------------------------------------
+
+Additionally you can access all values of an area recursively, so accessing +a+ recursively results in
+the following properties:
+
+[source,properties]
+.Accessing area +a+ recursively
+--------------------------------------------
+b.c=cVal
+b.c.1=cVal1
+b.c.2=cVal2
+b=abVal
+b2=abVal
+--------------------------------------------
+
+Why this is useful? Well there are different use cases:
+
+* you can segregate your configuration properties, e.g. a module can access its module configuration by
+ querying all properties under the area +config.modules.myModule+ (or whatever would be appropriate).
+* you can use this mechanism to configure maps (or more generally: collections).
+* you can easily filter parts of configuration
+* ...and more.
+
+==== Why Using Strings Only
+
+Using Strings as base representation of configuration comes with several huge advantages:
+
+* Strings are simple to understand
+* Strings are human readable and therefore easy to prove for correctness
+* Strings can easily be used within different language, different VMs, files or network communications.
+* Strings can easily be compared and manipulated
+* Strings can easily be searched, indexed and cached
+* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in
+ production as well in testing.
+* and more
+
+On the other side there are also disadvantages:
+
+* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as
+numbers,
+ dates etc.
+* Often you want not to work with Strings, but with according types.
+* Strings are not hierarchical, so mapping hierarchical structures requires some extra efforts.
+
+Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above:
+
+* Adding type safe converters on top of String allow to add any type easily, that can be directly mapped out of Strings.
+ This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.
+* Even more complex mappings can be easily realized, by using String not as a direct representation of configuration,
+ but a reference that defines where the more complex configuration artifact is available. This mechanism is similarly
+ easy to understand as parsing Strings to numbers, but is powerful enough to provide e.g. all kind of deployment
+ descriptors in Java EE.
+* Hierarchical and collection types can be mapped in different ways:
+** The keys of configuration can have additional syntax/semantics. E.g. when adding dor-separating path semantics
+*** trees/maps can also simply be mapped:
+
+[API Property Providers]
+=== Property Providers
+
+We have seen that constrain configuration aspects to simple literal key/value pairs provides us with an easy to
+understand, generic, flexible, yet extendible mechanism. Looking at the Java language features a +vava.util.Map<String,
+String>+ and +java.util.Properties+ basically model these quite well out of the box.
+So it makes sense to build configuration on top of the JDK's +Map+ interface. This creates immediately additional
+benefits:
+
+* we inherit full Lambda and collection support
+* Maps are widely known and well understood
+
+Nevertheless there are some things to be considered:
+
+* Configuration also requires meta-data, such as
+** the origin of a certain configuration entry and how it was derived from other values
+** the sensitivity of some data
+** the provider that have read the data
+** the time, when the data was read
+** the timestamp, when some data may be outdated
+** ...
+
+Basically the same is also the not related to some single configuration key, but also to a whole map.
+The +PropertyProvider+ interface models exact these aspects and looks as illustrated below:
+
+[source,java]
+.Interface PropertyProvider
+--------------------------------------------
+public interface PropertyProvider{
+
+ Optional<String> get(String key);
+ boolean containsKey(String key);
+ Map<String, String> toMap();
+ MetaInfo getMetaInfo();
+
+ default boolean hasSameProperties(PropertyProvider provider);
+ default Set<String> keySet();
+ default ConfigChangeSet load();
+ default boolean isMutable();
+ default void apply(ConfigChangeSet change);
+}
+--------------------------------------------
+
+Hereby
+
+* +getMetaInfo()+ return the meta information for the property provider, as well as for individual property key/value pairs.
+* +get, containsKey, keySet+ look similar to the methods on +Map+, though +get+ uses the +Optional+ type introduced
+ with Java 8. This avoids returning +null+ or throwing exceptions in case no such entry is available and also
+ reduced the API's footprint, since default values can be easily implemented by calling +Optional.orElse+.
+* +isMutable()+ allows to easy check, if a property provider is mutable, which is more elegant than catching
+ +NonSupportedOperation+ exception thrown on the according methods of +Map+.
+* +load()+ finally allows to (re)load a property map. It depends on the implementing source, if this operation
+ has any effect. If the map changes an according +ConfigChange+ must be returned, describing the
+ changes applied.
+* +hasSameProperties+ allows to perform a comparison with another provider.
+* +toMap+ allows to extract thing to a +Map+.
+
+This simple model will be used within the spi, where configuration can be injected/provided from external resources.
+But we have seen, that we have to consider additional aspects, such as extendability and type safety. Therefore we
+extend +PropertyMap+ and hereby also apply the 'composite pattern', which results in the following key abstraction.
+
+[[API Configuration]]
+=== Configuration
+
+Configuration inherits all basic features from +PropertyProvider+, but additionally adds functionality for
+type safety and extension mechanisms:
+
+[source,java]
+.Interface Configuration
+--------------------------------------------
+public interface Configuration extends PropertyProvider{
+
+ default OptionalBoolean getBoolean(String key);
+ default OptionalInt getInteger(String key);
+ default OptionalLong getLong(String key);
+ default OptionalDouble getDouble(String key);
+ default <T> Optional<T> getAdapted(String key, PropertyAdapter<T> adapter);
+ <T> Optional<T> get(String key, Class<T> type);
+
+ // accessing areas
+ default Set<String> getAreas();
+ default Set<String> getTransitiveAreas();
+ default Set<String> getAreas(final Predicate<String> predicate);
+ default Set<String> getTransitiveAreas(Predicate<String> predicate);
+ default boolean containsArea(String key);
+
+ // extension points
+ default Configuration with(ConfigOperator operator);
+ default <T> T query(ConfigQuery<T> query);
+
+ // versioning
+ default String getVersion(){return "N/A";}
+ void addPropertyChangeListener(PropertyChangeListener l);
+ void removePropertyChangeListener(PropertyChangeListener l);
+
+ // singleton accessors
+ public static boolean isDefined(String name);
+ public static <T> T of(String name, Class<T> template);
+ public static Configuration of(String name);
+ public static Configuration of();
+ public static <T> T of(Class<T> type){
+ public static void configure(Object instance);
+ public static String evaluateValue(String expression);
+ public static String evaluateValue(Configuration config, String expression);
+ public static void addGlobalPropertyChangeListener(PropertyChangeListener listener);
+ public static void removeGlobalPropertyChangeListener(PropertyChangeListener listener);
+}
+--------------------------------------------
+
+Hereby
+
+* +XXX getXXX(String)+ provide type safe accessors for all basic wrapper types of the JDK.
+* +getAdapted+ allow accessing any type, hereby also passing a +PropertyAdapter+ that converts
+ the configured literal value to the type required.
+* +getAreas()+, +getTransitiveAreas()+ allow to examine the hierarchical tree modeled by the configuration tree.
+ Optionally also predicates can be passed to select only part of the tree to be returned.
+* +containsArea+ allows to check, if an area is defined.
+* +with, query+ provide the extension points for adding additional functionality.
+
+* the static accessor methods define:
+ ** +of(), of(Class), of(String), of(String, Class)+ return the configuration valid for the current runtime environment.
+ ** +addGlobalPropertyChangeListener, removeGlobalPropertyChangeListener+ allow to register or unregister
+ global config change listener instances.
+ ** evaluateValue allows to evaluate a configuration expression based on a given configuration.
+ ** +configure+ performs injection of configured values.
+
+
+=== Environment
+
+The environment basically is also a kind of property/value provider similar to +System.getProperties()+ and +System
+.getenv()+ in the JDK. Nevertheless it provides additional functionality:
+
+[source,java]
+.Interface Environment
+--------------------------------------------
+public interface Environments {
+
+ String getEnvironmentType();
+ String getEnvironmentId();
+ String getContext();
+ Environment getParentEnvironment();
+
+ Optional<String> get(String key);
+ boolean containsKey(String key);
+ Set<String> keySet();
+ Map<String,String> toMap();
+
+ public static Environment of(){
+ public static Environment getRootEnvironment(){
+ public static List<String> getEnvironmentTypeOrder(){
+ public static List<String> getEnvironmentHierarchy(){
+ public static Optional<Environment> getEnvironment(String environmentType, String contextId){
+ public static Set<String> getEnvironmentContexts(String environmentType){
+ public static boolean isEnvironmentActive(String environmentType){
+--------------------------------------------
+
+* environments are hierarchical. Hereby all environments inherit from the root environment. The root environment
+ hereby must contain
+ ** all JDK's system properties, with same keys, values
+ ** all JDK's environment properties, prefixed with +env:+.
+ ** additionaly root properties as needed.
+* each environment also defines its +Stage+. Hereby, if not set explicitly the +Stage+ is inherited from the root
+ environment. Consequently the root environment must provide a +Stage+, which by default should be +Stage.Development+.
+* the static accessor methods define:
+ ** +of(), of(Class), of(String), of(String, Class)+ return the environment valid for the current runtime environment.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/pom.xml
----------------------------------------------------------------------
diff --git a/docs/pom.xml b/docs/pom.xml
index 9895bff..6233b4f 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -46,8 +46,6 @@ under the License.
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<configuration>
- <sourceDirectory>src</sourceDirectory>
- <baseDir>${project.basedir}</baseDir>
<eruby>erubis</eruby>
</configuration>
<executions>
@@ -58,12 +56,14 @@ under the License.
<goal>process-asciidoc</goal>
</goals>
<configuration>
+ <baseDir>${project.basedir}</baseDir>
<outputDirectory>target/design</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<backend>html</backend>
<embedAssets>true</embedAssets>
<imagesDir>${project.build.sourceDirectory}/images/</imagesDir>
- <sourceDocumentName>design/Design.adoc</sourceDocumentName>
+ <sourceDirectory>.</sourceDirectory>
+ <sourceDocumentName>Design.adoc</sourceDocumentName>
</configuration>
</execution>
</executions>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/src/design/Design.adoc
----------------------------------------------------------------------
diff --git a/docs/src/design/Design.adoc b/docs/src/design/Design.adoc
deleted file mode 100644
index 4d94114..0000000
--- a/docs/src/design/Design.adoc
+++ /dev/null
@@ -1,112 +0,0 @@
-Apache Tamaya -- Design Documentation
-=====================================
-:name: Tamaya
-:rootpackage: org.apache.tamaya
-:title: Apache Tamaya
-:revnumber: 0.1-SNAPSHOT
-:revremark: Incubator
-:revdate: November 2014
-:longversion: {revnumber} ({revremark}) {revdate}
-:authorinitials: ATR
-:author: Anatole Tresch, Anatole Tresch
-:email: <at...@gmail.com>
-:source-highlighter: coderay
-:website: http://tamaya.incubator.apache.org/
-:iconsdir: {imagesdir}/icons
-:toc:
-:toc-placement: manual
-:icons:
-:encoding: UTF-8
-:numbered:
-
-'''
-
-<<<
-
--> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[]
-
-toc::[]
-
-<<<
-:numbered!:
------------------------------------------------------------
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
------------------------------------------------------------
-
-:numbered:
-
-<<<
-
-== Introduction
-This document describes the {name} API for Configuration. The technical objective is to provide a
-unified configuration model in Java, targeting Java ME, SE as well as the EE platform.
-The API will provide support for key/value based application configuration. It will provide
-as well higher level APIs that are based on the low level ke</value pairs. Finally it will
-provide extension points for adding additional features and additional modules for extension
-or adaption.
-
-=== Working Group
-This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This
-specification is the result of the collaborative work of the members of the {name} Users Group and the community at
-large. Currently the project is lead by Anatole Tresch (atsticks at gmail.dot com).
-
-=== Goals
-Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of
-well defined aspects of a software product without having to recompile/rebuild the code.
-
-==== Targets
-{name} targets to support all general configuration aspects, e.g.
-
-* spplication configuration
-** plugins
-** modules
-** components
-* Configuration of Java EE related aspects for Java enterprise application portability and dynamic provisioning, such as
-** Configuration of CDI (interceptors, decorators and alternatives)
-** Configuration of Bean Validation, JSF, web applications etc.
-* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values, or by providing
- accessors to evaluate current configuration vlues. This can be used explicitly or transparently by client code.
-
-Additionally the solution should support
-
-* multiple configuration locations, including remote locations
-* multiple configuration formats, including custom formats
-* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und URIs are supported by default.
-* type conversion
-* configuration of collections
-
-
-=== Required Java version
-The API is based on Java SE 8.0 language features.
-
-=== How this document is organized
-There are five main section in this document:
-
-* Use cases.
-* Requirements.
-* Specification.
-* Implementation Recommendations.
-* An appendix.
-
-include::src/design/content/0_UseCases.adoc[]
-include::src/design/content/1_Requirements.adoc[]
-include::src/design/content/2_CoreConcepts.adoc[]
-
-:numbered!:
-== APPENDIX
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/src/design/content/0_UseCases.adoc
----------------------------------------------------------------------
diff --git a/docs/src/design/content/0_UseCases.adoc b/docs/src/design/content/0_UseCases.adoc
deleted file mode 100644
index 5a95b4e..0000000
--- a/docs/src/design/content/0_UseCases.adoc
+++ /dev/null
@@ -1,255 +0,0 @@
-<<<
-[[Use Cases]]
-== Use Cases
-
-This section describes some, but not all, of the use cases that should be covered with this JSR.
-
-[[UC Simple Configuration]]
-=== Simple Property Based Configuration
-
-In this most simple usage scenario an application is created that is preconfigured by some property files contained in the
-Java archive. Using the command line it is possible to redefine/override some of the properties, e.g. by using system properties.
-Typical example are small command line tools.
-
--> It must be possible to define default configuration and package it with the (SE) application.
-
--> It must be possible to consider system properties or other command line arguments for usage with configuration.
-
--> It must be possible that command line arguments can override defaults configured.
-
-[[UC Advanced Property Based Configuration]]
-=== Advanced Property Based Configuration
-
-Enhancing the previous scenario, we might as well consider the current environment. Saying that our overriding mechanisms
-must be improved, since
-
-* some environment settings should not be overridable
-* some defaults should be overridden by environment or system properties, whereas others may not
-
-Additionally the user may have an option, where he is allowed to define an external configuration file that should be used to configure
-the application. This is especially useful for applications with lots of command line options (under windows even command
-execution may fail die to exceeding command length). Finally application developers may have their own formats in place, so the
-system should be able to support these formats.
-
--> Environment properties must be considered as well.
-
--> It must be possible to control overriding.
-
--> It must be possible to dynamically add configuration locations to be considered.
-
--> It must be possible to define customized configuration formats.
-
-[[UC Modularized Configuration]]
-=== Modularized Configuration
-
-When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional things
-to be considered by a configuration system:
-
-* The different modules must have access to their own "module configuration".
-* Modules may want to define a contract, which properties may be overriden.
-
-Consequently
-
--> Parts of Configuration must be identifiable and accessible in a isolated way.
-
--> Module configuration requires partial isolation or other mechanisms to ensure only configuration aspects
- that are allowed to be overriden can be overriden.
-
-[[UC Dynamic Provisioning]]
-=== Dynamic Provisioning
-
-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.
-
-Consequently:
-
--> Ensure Configuration can be transferred over the network easily.
-
--> Whereas many people will no think serializability is the solution, it would be much more useful to define
- a text based format for serialization, e.g. in +XML+ or +JSON+.
-
--> Similarly a management API should be defined, which allows to inspect the configuration in place, e.g. using
- JMX or REST services.
-
-[[UC Java EE]]
-=== Java EE
-
-Considering Java EE different aspects should be considered:
-
-* Java EE is a complex multi-layered architecture with different levels of runtime contexts:
-** application server boot level (system classloader),
-** (optional) deployment/undeployment of ears (ear classloader),
-** (optional) deployment/undeployment of web applications (war classloader),
-** different runtime setups, e.g. EJB calls, MDB execution, Servlet Requests, scheduled and timed executions.
-* Configuring administrative resources (e.g. datasources, users, security etc) is typically vendor specific.
-* The environment is inherently multi-threaded.
-
-Given that a couple of additional requirements araise:
-
--> 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.
-
-[[UC MultiTenancy]]
-=== Scenario MultiTenancy
-In multi tenancy setups a hierarchical/graph model of contexts for configurations is required. For example there might
-be some kind of layering as follows:
-
-* Layer 0: Low level system configuration
-* Layer 1: Domain configuration
-* Layer 2: Default App configuration
-* Layer 3: Tenant specific configuration
-* Layer 4: User specific configuration
-
-Configurations made in the tenant or user layer override the default app configuration etc.
-
--> 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.
-
-[[UC Java API]]
-=== Accessing Configuration
-
-So far we described much how configuration must be organized and managed, but we got not concrete, how it is accessed.
-Basically there are two basic scenarios to be distinguished, which mainly depend on the way how the lifecycle of a component
-to be configured is managed:
-
-* If the lifecycle is managed manually by the developer, the configuration system
-** can inject configuration values, when explicitly called to to so
-** can provide an accessor for configuration.
-* If the lifecycle is managed by some container such as a DI container, the configuration
- system should leverage the functionality of the container, where possible.
-
-The most simplest way is using injection, e.g. a POJO can be written as follows:
-
-[source, java]
-.Configured POJO Example
-----------------------------------------------------
-public class MyPojo {
- @ConfigProperty("myCurrency")
- @DefaultValue("CHF")
- private String currency;
-
- @ConfigProperty("myCurrencyRate")
- private Long currencyRate;
-
- // complex algorithm based on the currency
-}
-----------------------------------------------------
-
-The instance then can be passed for being configured:
-
-[source, java]
-.Configuring a POJO
-----------------------------------------------------
-MyPojo instance = new MyPojo();
-Configuration.configure(instance);
-----------------------------------------------------
-
-Another way of accessing configuration would be by defining a type safe template
-providing access to the configured values and let the configuration system implement
-the interface:
-
-[source, java]
-.Type Safe Configuration Template Example
-----------------------------------------------------
-public interface MyConfig {
- @ConfigProperty("myCurrency")
- @DefaultValue("CHF")
- String getCurrency();
-
- @ConfigProperty("myCurrencyRate")
- Long getCurrencyRate();
-
-}
-----------------------------------------------------
-
-The configuration system will then implement the
-interface using configuration as follows:
-
-[source, java]
-.Accessing a type safe Configuration Template
-----------------------------------------------------
-MyConfig config = Configuration.of(MyConfig.class);
-----------------------------------------------------
-
-Finally there is a generic +Configuration+ type that can be used as well, which
-provides full access to all features:
-
-[source, java]
-.Accessing Configuration
-----------------------------------------------------
-Configuration config = Configuration.of(Configuration.class);
-----------------------------------------------------
-
-
-[[UC Testing]]
-=== Testing
-When testing a Java solution, it must be possible to easily control the configuration provided, so isolated
-component tests can be written effectively. Also it should be possible to control/isolate the configuration level for
-each test case.
-
--> isolation of configuration services is required
-
--> API for controlling the configuration provided, required for according implementations in the testing frameworks.
-
-[[UC Staging]]
-=== Staging
-Different companies go through different staging levels during the development of software components. Currently only
-rarely the EE frameworks support staging aspects, nevertheless no broader, well modelled staging concept is defined.
-Different companies also have different staging or sub-staging levels in place, which also must be reflected.
-Especially with sub-stages inheritance of stage related configuration is common sense and should be supported.
-
--> Main stages available and to be supported must be defined.
-
--> Enable additional stages to be added, so also custom stages can be supported.
-
-
-[[UC CotsIntegration]]
-=== Custom of the Shelf (COTS) Integration
-When buying software from an external software company it is often very cumbersome to integrate, adapt and customize
-third party software to the internal operational requirements. Especially, when software is delivered as ear modules
-portability is often very difficult and time consuming. Configuration should enable COTS providers to define a
-customization contract, which also can be part of the COTS software interface and integration specifications. This
-would allow operations to better control and configure third party solutions as possible, whereas in the evaluation
-phase the integration and configuration options can explicitly be defined.
-
--> It must be possible to document configuration aspects supported.
-
--> Configuration must be overridable from external sources (the operations which must operate the COTS solution).
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/src/design/content/1_Requirements.adoc
----------------------------------------------------------------------
diff --git a/docs/src/design/content/1_Requirements.adoc b/docs/src/design/content/1_Requirements.adoc
deleted file mode 100644
index 88c910e..0000000
--- a/docs/src/design/content/1_Requirements.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-<<<
-[[Requirements]]
-== Requirements
-=== Core Configuration Requirements
-Based on the scope and use cases described above the following core requirements can be identified:
-
-* Configuration is modelled as String based key/value pairs.
-* Configuration can be combined using the GoF composite pattern. Hereby different composition policies can be applied, such as
- ** override: subsequent entries override existing ones.
- ** substraction: keys present in the second configuration will be removed.
- ** union-resolve: key/values were added, in case of conflicts a +ConfigException+ must be thrown.
- ** union-ignore: similar to union, whereas duplicates are ignored (leaving the initial value loaded).
- ** intersection:
-
-[[RequirementsServer]]
-=== Server Configuration Requirements
-shskjdhskhds sdkj ksjdks skjdskjd:
-
-. Req1
-. Req2
-
-[[RequirementsExtensions]]
-=== Extensions Requirements
-shskjdhskhds sdkj ksjdks skjdskjd:
-
-. Req1
-. Req2
-
-[[RequirementsNonFunctional]]
-=== Non Functional Requirements
-. Req1
-. Req2
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/f494f9fb/docs/src/design/content/2_CoreConcepts.adoc
----------------------------------------------------------------------
diff --git a/docs/src/design/content/2_CoreConcepts.adoc b/docs/src/design/content/2_CoreConcepts.adoc
deleted file mode 100644
index 9eeadf9..0000000
--- a/docs/src/design/content/2_CoreConcepts.adoc
+++ /dev/null
@@ -1,299 +0,0 @@
-<<<
-[[Core Concepts]]
-== {name} Core Concepts
-Though {name} is a very powerful and flexible solution there are basically only a few simple core concepts required that build
-the base of all the other mechanisms:
-
-* Key/Value Pairs
-* Property Providers
-* Meta Data
-* Combining property providers
-* Environment Model
-* Configuration
-* Configuration Injection
-
-These parts are explained in the following sections. It is recommended that user's of the API read through this part.
-All subsequent parts are building upon this concepts and may be more difficult to understand without having read
-this section.
-
-[[API KeyValues]]
-=== Key/Value Pairs
-
-Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple
-and similarly most commonly used are simple literal key/value pairs. So the core building block of {name} are key/value pairs.
-You can think of a common +.properties+ file, e.g.
-
-[source,properties]
-.A simple properties file
---------------------------------------------
-a.b.c=cVal
-a.b.c.1=cVal1
-a.b.c.2=cVal2
-a=aVal
-a.b=abVal
-a.b2=abVal
---------------------------------------------
-
-Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g.
-
-[source,properties]
-.Accessing some properties
---------------------------------------------
-Properties props = new Properties();
-props.readProperties(...);
-String val = props.getProperty("a.b.c");
-val = props.getProperty("a.b.c.1");
-...
---------------------------------------------
-
-This looks familiar to most of you. Nevertheless when looking closer to the above key/value pairs,
-there are more concepts in place: looking at the keys +a.b.c+, +a.b.c.1+, +a.b.c.2+, +a+, +a.b+ we
-see that the key names build up a flattened tree structure. So we can define the following:
-
-Given a key +p1.p2.p3.k=value+:
-
-* +p1.p2.p3.k+ is called the _qualified key_
-* +p1.p2.p3+ is the key's _area_
-* the child areas +p1.p2", "p1+ are called _areas_ as well
-* +k+ is the _(unqualified) key_
-
-Given that you can perform some very useful actions:
-
-* you can filter the keys with an area. E.g. in the example before you can query for all keys within the area +a.b.c+
- and map them to new properties set as follows:
-
-[source,properties]
-.Accessing an area
---------------------------------------------
-1=cVal1
-2=cVal2
---------------------------------------------
-
-Similarly accessing the area +a+ results in the following properties:
-
-[source,properties]
-.Accessing the area +a+
---------------------------------------------
-b=abVal
-b2=abVal
---------------------------------------------
-
-Additionally you can access all values of an area recursively, so accessing +a+ recursively results in
-the following properties:
-
-[source,properties]
-.Accessing area +a+ recursively
---------------------------------------------
-b.c=cVal
-b.c.1=cVal1
-b.c.2=cVal2
-b=abVal
-b2=abVal
---------------------------------------------
-
-Why this is useful? Well there are different use cases:
-
-* you can segregate your configuration properties, e.g. a module can access its module configuration by
- querying all properties under the area +config.modules.myModule+ (or whatever would be appropriate).
-* you can use this mechanism to configure maps (or more generally: collections).
-* you can easily filter parts of configuration
-* ...and more.
-
-==== Why Using Strings Only
-
-Using Strings as base representation of configuration comes with several huge advantages:
-
-* Strings are simple to understand
-* Strings are human readable and therefore easy to prove for correctness
-* Strings can easily be used within different language, different VMs, files or network communications.
-* Strings can easily be compared and manipulated
-* Strings can easily be searched, indexed and cached
-* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in
- production as well in testing.
-* and more
-
-On the other side there are also disadvantages:
-
-* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as
-numbers,
- dates etc.
-* Often you want not to work with Strings, but with according types.
-* Strings are not hierarchical, so mapping hierarchical structures requires some extra efforts.
-
-Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above:
-
-* Adding type safe converters on top of String allow to add any type easily, that can be directly mapped out of Strings.
- This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.
-* Even more complex mappings can be easily realized, by using String not as a direct representation of configuration,
- but a reference that defines where the more complex configuration artifact is available. This mechanism is similarly
- easy to understand as parsing Strings to numbers, but is powerful enough to provide e.g. all kind of deployment
- descriptors in Java EE.
-* Hierarchical and collection types can be mapped in different ways:
-** The keys of configuration can have additional syntax/semantics. E.g. when adding dor-separating path semantics
-*** trees/maps can also simply be mapped:
-
-[API Property Providers]
-=== Property Providers
-
-We have seen that constrain configuration aspects to simple literal key/value pairs provides us with an easy to
-understand, generic, flexible, yet extendible mechanism. Looking at the Java language features a +vava.util.Map<String,
-String>+ and +java.util.Properties+ basically model these quite well out of the box.
-So it makes sense to build configuration on top of the JDK's +Map+ interface. This creates immediately additional
-benefits:
-
-* we inherit full Lambda and collection support
-* Maps are widely known and well understood
-
-Nevertheless there are some things to be considered:
-
-* Configuration also requires meta-data, such as
-** the origin of a certain configuration entry and how it was derived from other values
-** the sensitivity of some data
-** the provider that have read the data
-** the time, when the data was read
-** the timestamp, when some data may be outdated
-** ...
-
-Basically the same is also the not related to some single configuration key, but also to a whole map.
-The +PropertyProvider+ interface models exact these aspects and looks as illustrated below:
-
-[source,java]
-.Interface PropertyProvider
---------------------------------------------
-public interface PropertyProvider{
-
- Optional<String> get(String key);
- boolean containsKey(String key);
- Map<String, String> toMap();
- MetaInfo getMetaInfo();
-
- default boolean hasSameProperties(PropertyProvider provider);
- default Set<String> keySet();
- default ConfigChangeSet load();
- default boolean isMutable();
- default void apply(ConfigChangeSet change);
-}
---------------------------------------------
-
-Hereby
-
-* +getMetaInfo()+ return the meta information for the property provider, as well as for individual property key/value pairs.
-* +get, containsKey, keySet+ look similar to the methods on +Map+, though +get+ uses the +Optional+ type introduced
- with Java 8. This avoids returning +null+ or throwing exceptions in case no such entry is available and also
- reduced the API's footprint, since default values can be easily implemented by calling +Optional.orElse+.
-* +isMutable()+ allows to easy check, if a property provider is mutable, which is more elegant than catching
- +NonSupportedOperation+ exception thrown on the according methods of +Map+.
-* +load()+ finally allows to (re)load a property map. It depends on the implementing source, if this operation
- has any effect. If the map changes an according +ConfigChange+ must be returned, describing the
- changes applied.
-* +hasSameProperties+ allows to perform a comparison with another provider.
-* +toMap+ allows to extract thing to a +Map+.
-
-This simple model will be used within the spi, where configuration can be injected/provided from external resources.
-But we have seen, that we have to consider additional aspects, such as extendability and type safety. Therefore we
-extend +PropertyMap+ and hereby also apply the 'composite pattern', which results in the following key abstraction.
-
-[[API Configuration]]
-=== Configuration
-
-Configuration inherits all basic features from +PropertyProvider+, but additionally adds functionality for
-type safety and extension mechanisms:
-
-[source,java]
-.Interface Configuration
---------------------------------------------
-public interface Configuration extends PropertyProvider{
-
- default OptionalBoolean getBoolean(String key);
- default OptionalInt getInteger(String key);
- default OptionalLong getLong(String key);
- default OptionalDouble getDouble(String key);
- default <T> Optional<T> getAdapted(String key, PropertyAdapter<T> adapter);
- <T> Optional<T> get(String key, Class<T> type);
-
- // accessing areas
- default Set<String> getAreas();
- default Set<String> getTransitiveAreas();
- default Set<String> getAreas(final Predicate<String> predicate);
- default Set<String> getTransitiveAreas(Predicate<String> predicate);
- default boolean containsArea(String key);
-
- // extension points
- default Configuration with(ConfigOperator operator);
- default <T> T query(ConfigQuery<T> query);
-
- // versioning
- default String getVersion(){return "N/A";}
- void addPropertyChangeListener(PropertyChangeListener l);
- void removePropertyChangeListener(PropertyChangeListener l);
-
- // singleton accessors
- public static boolean isDefined(String name);
- public static <T> T of(String name, Class<T> template);
- public static Configuration of(String name);
- public static Configuration of();
- public static <T> T of(Class<T> type){
- public static void configure(Object instance);
- public static String evaluateValue(String expression);
- public static String evaluateValue(Configuration config, String expression);
- public static void addGlobalPropertyChangeListener(PropertyChangeListener listener);
- public static void removeGlobalPropertyChangeListener(PropertyChangeListener listener);
-}
---------------------------------------------
-
-Hereby
-
-* +XXX getXXX(String)+ provide type safe accessors for all basic wrapper types of the JDK.
-* +getAdapted+ allow accessing any type, hereby also passing a +PropertyAdapter+ that converts
- the configured literal value to the type required.
-* +getAreas()+, +getTransitiveAreas()+ allow to examine the hierarchical tree modeled by the configuration tree.
- Optionally also predicates can be passed to select only part of the tree to be returned.
-* +containsArea+ allows to check, if an area is defined.
-* +with, query+ provide the extension points for adding additional functionality.
-
-* the static accessor methods define:
- ** +of(), of(Class), of(String), of(String, Class)+ return the configuration valid for the current runtime environment.
- ** +addGlobalPropertyChangeListener, removeGlobalPropertyChangeListener+ allow to register or unregister
- global config change listener instances.
- ** evaluateValue allows to evaluate a configuration expression based on a given configuration.
- ** +configure+ performs injection of configured values.
-
-
-=== Environment
-
-The environment basically is also a kind of property/value provider similar to +System.getProperties()+ and +System
-.getenv()+ in the JDK. Nevertheless it provides additional functionality:
-
-[source,java]
-.Interface Environment
---------------------------------------------
-public interface Environments {
-
- String getEnvironmentType();
- String getEnvironmentId();
- String getContext();
- Environment getParentEnvironment();
-
- Optional<String> get(String key);
- boolean containsKey(String key);
- Set<String> keySet();
- Map<String,String> toMap();
-
- public static Environment of(){
- public static Environment getRootEnvironment(){
- public static List<String> getEnvironmentTypeOrder(){
- public static List<String> getEnvironmentHierarchy(){
- public static Optional<Environment> getEnvironment(String environmentType, String contextId){
- public static Set<String> getEnvironmentContexts(String environmentType){
- public static boolean isEnvironmentActive(String environmentType){
---------------------------------------------
-
-* environments are hierarchical. Hereby all environments inherit from the root environment. The root environment
- hereby must contain
- ** all JDK's system properties, with same keys, values
- ** all JDK's environment properties, prefixed with +env:+.
- ** additionaly root properties as needed.
-* each environment also defines its +Stage+. Hereby, if not set explicitly the +Stage+ is inherited from the root
- environment. Consequently the root environment must provide a +Stage+, which by default should be +Stage.Development+.
-* the static accessor methods define:
- ** +of(), of(Class), of(String), of(String, Class)+ return the environment valid for the current runtime environment.