tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject [03/10] incubator-tamaya git commit: Fixed outdated root dcumentation.
Date Wed, 09 Mar 2016 13:11:12 GMT
Fixed outdated root dcumentation.

Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/c5e524ae
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/c5e524ae
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/c5e524ae

Branch: refs/heads/master
Commit: c5e524ae783a85a29302aa198c500c0bd1488921
Parents: 1c931fa
Author: anatole <anatole@apache.org>
Authored: Tue Mar 8 20:17:01 2016 +0100
Committer: anatole <anatole@apache.org>
Committed: Tue Mar 8 20:17:01 2016 +0100

 docs/src/main/asciidoc/API.adoc      | 59 +++++++++++++++++++------------
 docs/src/main/asciidoc/Core.adoc     | 21 ++---------
 docs/src/main/asciidoc/examples.adoc |  3 ++
 docs/src/main/asciidoc/index.adoc    | 13 +++----
 4 files changed, 46 insertions(+), 50 deletions(-)

diff --git a/docs/src/main/asciidoc/API.adoc b/docs/src/main/asciidoc/API.adoc
index 10d76ee..f145425 100644
--- a/docs/src/main/asciidoc/API.adoc
+++ b/docs/src/main/asciidoc/API.adoc
@@ -76,22 +76,21 @@ The API provides the artifacts as described in the link:CoreDesign.html[Core
 * A simple but complete SE *API* for accessing key/value based _Configuration_:
   ** +Configuration+ hereby models configuration, the main interface of Tamaya. +Configuration+
      *** access to literal key/value pairs.
-     *** functional extension points (+with,query+) based on +UnaryOperator<Configuration>+
(operator) and
-         +Function<Configuration,T>+ (query).
-  ** +ConfigurationProvider+ provides the static entry point for accessing configuration.
-  ** +ConfigProvider+ provides static access to the current +Configuration+ (default configuration)
+     *** 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 safe define the target type to be returned
by a registered
+  ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned
by a registered
-  ** +PropertyConverter+, which defines conversion of String values into any required target
+  ** +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 data interface to be implemented by any kind of data
providers (local or remote)
-     *** provides data key/value pairs in raw format as String key/values only
-     *** can optionally support scanning of its provided values
-  ** _PropertySourceProvider:_ allows to add property sources dynamically.
+  ** _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
+     *** 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+
   ** +PropertyFilter+, which allows filtering of property values prior getting returned to
the caller.
@@ -102,7 +101,7 @@ The API provides the artifacts as described in the link:CoreDesign.html[Core
   ** +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 parts of the API, which is quite small:
+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+
@@ -184,8 +183,11 @@ property map, but also supports type safe access:
 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
@@ -200,6 +202,7 @@ Hereby
 * +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:
@@ -249,11 +252,14 @@ configured String values into the required target type. This is achieved
with th
 public interface PropertyConverter<T>{
-    T convert(String value);
+    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+.
 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
@@ -283,7 +289,7 @@ use Lambdas and method references in Java 8:
 .Applying a +ConfigurationQuery+ using a method reference
-ConfigSecurity securityContext = Configuration.current().query(ConfigSecurity::targetSecurityContext);
+ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext);
 NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes.
@@ -296,7 +302,7 @@ Operator calls basically look similar:
 Configuration secured = ConfigurationProvider.getConfiguration()
                            .with((config) ->
-                                 config.getOptional("foo").isPresent()?;
+                                 config.get("foo")!=null?;
@@ -404,7 +410,7 @@ A +PropertyFilter+ is defined as follows:
 // Functional Interface
 public interface PropertyConverter{
-    String filterProperty(String key, String valueToBeFiltered);
+    String filterProperty(String value, ConversionContext context);
@@ -414,6 +420,7 @@ Hereby:
 * non null values are used as the current value of the key. Nevertheless for resolving multi-step
   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.
+* +ConversionContext+ 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.
@@ -425,19 +432,25 @@ This interface can be implemented optional. It can be used to adapt
the way how
 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.
+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.
 // FunctionalInterface
 public interface PropertyValueCombinationPolicy{
-   public final PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
-           (current, key, propertySource) -> Optional.ofNullable(propertySource.get(key))
-                                                     .filter(s -> !s.isEmpty())
-                                                     .orElse(current);
+   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
-   String collect(String currentValue, String key, PropertySource propertySource);

diff --git a/docs/src/main/asciidoc/Core.adoc b/docs/src/main/asciidoc/Core.adoc
index dec5a1b..14e0195 100644
--- a/docs/src/main/asciidoc/Core.adoc
+++ b/docs/src/main/asciidoc/Core.adoc
@@ -157,26 +157,11 @@ due to several reasons:
 == Configuration Setup in Core
-Tamaya Core provides a minimal, but already powerful configuration setting, that allows you
to configure SE
-applications already easily. Basically you can provide configuration properties using the
following formats and
-locations (from weakest to strongest):
+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 in +META-INF/cfg/defaults.properties+
-. Read all files found in +META-INF/cfg/${tamaya.stage}/defaults.properties+
-. Read all files found in +META-INF/cfg/config.properties+
-. Read all files found in +META-INF/cfg/${tamaya.stage}/config.properties+
-. Read current system properties.
-Hereby +tamaya.stage+ can be set by setting an according environment property, or by applying
(overriding any environment
-property) a corresponding system property:
-[source, listing]
-If not set the staging locations will be ignored.
+. Read all files found at +META-INF/javaconfiguration.properties+
 === Overview of Registered Default Property Sources and Providers

diff --git a/docs/src/main/asciidoc/examples.adoc b/docs/src/main/asciidoc/examples.adoc
index 66b9b0b..ab7e0de 100644
--- a/docs/src/main/asciidoc/examples.adoc
+++ b/docs/src/main/asciidoc/examples.adoc
@@ -77,3 +77,6 @@ adapted.
 This example shows how to build a +Configuration+ using a simple pure SE builder API as provided
by the
 _builder extension_.
+=== Remote
+THe remote example shows a simple setup where parts of the +Configuration+ are read remotedly.

diff --git a/docs/src/main/asciidoc/index.adoc b/docs/src/main/asciidoc/index.adoc
index f757758..2617d3e 100644
--- a/docs/src/main/asciidoc/index.adoc
+++ b/docs/src/main/asciidoc/index.adoc
@@ -95,7 +95,7 @@ Nevertheless there are a few things that are not part of Tamaya:
   your enterprise context, such as supported file locations, formats, overriding and filter
rules etc.
 === And what can I do with Apache Tamaya?
 There are basically two main usage scenarios, which are synergetic:
@@ -172,8 +172,7 @@ to go, but you may want to add additional extensions that provide more
 === Required Java version
-The full API is based on Java SE 8.0 language features, whereas a compatible implementation
of API and Core
-is similarly available for Java SE 7 as well.
+The API is based on Java SE 7.0 language features.
 == Where should I continue
@@ -193,15 +192,11 @@ Finally
 Javadoc of the current API
-* link:API.html[General API Documentation] and link:../javadoc/api/java7/index.html[API Javadoc
for Java7] /
-  link:../javadoc/api/java8/index.html[API Javadoc for Java8]
+* link:API.html[General API Documentation] and link:../javadoc/api/index.html[API Javadoc]
 Javadoc of the current Core Implementation
-* link:Core.html[General Core Documentation] and link:../javadoc/core/java7/index.html[Core
Javadoc for Java7] /
-  link:../javadoc/core/java8/index.html[Core Javadoc for Java8]
-Javadoc of the current Extension Modules
+* link:Core.html[General Core Documentation] and link:../javadoc/core/index.html[Core Javadoc
for Java7]
 === Examples

View raw message