Repository: incubator-tamaya-site Updated Branches: refs/heads/master 69e489603 -> a449f485a
TAMAYA-253: Added replacement policy for raw evaluation. 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/b4003211 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/b4003211 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/b4003211 Branch: refs/heads/master Commit: b400321110504fc33807071d429731c77878201f Parents: 69e4896 Author: anatole <anat...@apache.org> Authored: Sun Mar 5 21:24:25 2017 +0100 Committer: anatole <anat...@apache.org> Committed: Sun Mar 5 21:24:25 2017 +0100 ---------------------------------------------------------------------- content/documentation/api.adoc | 36 ++++++------ content/documentation/core.adoc | 58 +++++++++++++++++++- content/documentation/extensions/mod_jndi.adoc | 3 + .../extensions/mod_spi-support.adoc | 6 ++ 4 files changed, 82 insertions(+), 21 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b4003211/content/documentation/api.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/api.adoc b/content/documentation/api.adoc index 9761a5f..ffd8850 100644 --- a/content/documentation/api.adoc +++ b/content/documentation/api.adoc @@ -33,7 +33,9 @@ The API provides the artifacts as described in the link:../highleveldesign.html[ +PropertySource+ *** provides String based property access for single key/value pairs in _raw_ format (meaning no postprocessing is applied yet). - *** can _optionally_ provide access to a +Map<String,String>+, providing all its properties at once. + *** can _optionally_ provide access to a +Iterable<PropertyValue>+, providing all its properties at once. + *** defines the default ordinal to be used for establishing the order of significance among all + auto-discovered property sources. ** _PropertySourceProvider:_ allows to automatically register multiple property sources, e.g. all config files found in a file system folder.. ** +ConfigurationProviderSpi+ defines the interface to be implemented by the delegating bean that is implementing the @@ -293,12 +295,11 @@ identified to be necessary: [source,java] -------------------------------------------- public interface PropertySource{ - // This feature is under discussion - // int getOrdinal(); + int getOrdinal(); String getName(); - String get(String key); + PropertyValue get(String key); boolean isScannable(); - Map<String, String> getProperties(); + Iterable<PropertyValue> getProperties(); } -------------------------------------------- @@ -312,13 +313,14 @@ Hereby properties. 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. The fact if a +PropertySource+ is _scannable_ can be determined by calling +isScannable()+. -* TODO Feature is in question: +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+. +* +int getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where + property sources with higher ordinals override ones with lower ordinals. If the ordinal of two property sources is + the same, the natural ordering of the fully qualified class names of the property source implementations is 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. + Implementations of this API may provide additional functionality to adapt the default ordinal of auto-discovered + property sources. +* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within its containing +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 @@ -403,22 +405,20 @@ public interface PropertyValueCombinationPolicy{ PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR = new PropertyValueCombinationPolicy(){ @Override - public Map<String,String> collect(Map<String,String> currentValue, String key, + public PropertyValue collect(PropertyValue currentValue, String key, PropertySource propertySource) { PropertyValue value = propertySource.get(key); - return value!=null?value.getConfigEntries():currentValue; + return value!=null?value:currentValue; } }; - Map<String,String> collect(Map<String,String> currentValue currentValue, String key, + PropertyValue collect(PropertyValue currentValue, String key, PropertySource propertySource); } -------------------------------------------- -Looking at the +collect+ method's signature it may be surprising to find a +Map+ for the return type. -This is because returning a +Map+ allows also to filter/combine/use meta entries (by default entries starting -with an '_'). +Looking at the +collect+ method's signature, returning a +PropertyValue+ allows also to filter/combine/use meta entries. [[ConfigurationContext]] http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b4003211/content/documentation/core.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/core.adoc b/content/documentation/core.adoc index 496bf07..575ca1e 100644 --- a/content/documentation/core.adoc +++ b/content/documentation/core.adoc @@ -127,6 +127,9 @@ by passing the fully qualified comparator class name as system property: +-Dproperty-source-comparator=a.b.c.MyComparatorClass+ +The ladder allows to adapt the ordering of auto-discovered property sources, even if the value returned by ++int getOrdinal()+ cannot be changed. + [[CorePropertySources]] == Configuration Setup in Core @@ -148,12 +151,15 @@ registered. They are all in the package +org.apache.tamaya.core.propertysource+ [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 +|META-INF/javaconfiguration.properties |JavaConfigurationProvider |100 +|META-INF/javaconfiguration.xml |JavaConfigurationProvider |100 +|JNDI Entries |JNDIPropertySource |200 |Environment Properties |EnvironmentPropertySource |300 -|System Properties |SystemPropertySource |400 +|System Properties |SystemPropertySource |1000 |======= +NOTE: +JNDIPropertySource+ is provided by the `tamaya-jndi` extension module. + === Abstract Class PropertiesFilePropertySource @@ -216,6 +222,52 @@ present that loads all +.properties+ files found at +META-INF/javaconfiguration. and +META-INF/javaconfiguration.xml+. +=== Replacing the property value evaluation policy + +Tamaya's core implementation allows to replace the complete logic how a configuration value or the current configuration +properties are calculated from a given +ConfigurationContext+ by implementing the +ConfigValueEvaluator+ +interface: + +[source,java] +-------------------------------------------- +/** + * Component SPI which encapsulates the evaluation of a single or full <b>raw</b>value + * for a {@link ConfigurationContext}. + */ +public interface ConfigValueEvaluator { + + /** + * Evaluates single value using a {@link ConfigurationContext}. + * @param key the config key, not null. + * @param context the context, not null. + * @return the value, or null. + */ + PropertyValue evaluteRawValue(String key, ConfigurationContext context); + + /** + * Evaluates all property values from a {@link ConfigurationContext}. + * @param context the context, not null. + * @return the value, or null. + */ + Iterable<PropertyValue> evaluateRawValues(ConfigurationContext context); + +} +-------------------------------------------- + +The default implementation +DefaultConfigValueEvaluator+ implements the following logic: + +. Collect all +PropertySources+ from the context. +. Access +PropertyValue get(String)+ (single key access)/ +Map<String,PropertyValue> getProperties()+ + (config map access) from each property source and combine the previous with the next value using + the +PropertyValueCombinationPolicy+ in place. + +The resulting _raw_ value(s) are then finally handed over to the registered filters and finally +converted to +String/Map<String,String>+ as required by the user API. + +To replace this default behaviour you must register your implementation with the current ++ServiceContext+. + + [[Extensions]] == Adding Extensions http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b4003211/content/documentation/extensions/mod_jndi.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_jndi.adoc b/content/documentation/extensions/mod_jndi.adoc index 0bba306..5c862b2 100644 --- a/content/documentation/extensions/mod_jndi.adoc +++ b/content/documentation/extensions/mod_jndi.adoc @@ -60,6 +60,9 @@ will return an empty map instance. After calling `setScannable(true);` a call to `getProperties()` will return a String representation of the JNDI tree. Hereby leaves of the tree are converted using `String.valueOf(leaveObject)`. +This module automatically registers an instance of +JNDIPropertySource+ with a +default ordinal of +200+. + You can extend this class or manually instantiate it, e.g. as part of a +PropertySourceProvider+. If no `Context` is passed explicitly, a new +InitialContext+ is created, without any environment parameters set. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b4003211/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 index e43bab9..5bf4efc 100644 --- a/content/documentation/extensions/mod_spi-support.adoc +++ b/content/documentation/extensions/mod_spi-support.adoc @@ -35,7 +35,13 @@ used SPI parts in Tamaya: easy to use high level API. + +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+ values and their class names. ++ The default configuration implementation also allows to replace the raw value evaluation + logic using a +ConfigValueEvaluator+, similar to Tamaya's core implementation. +NOTE: It is highly recommended that you read also the link:../core.html[documentation] of Tamaya's + implementation core, since this describes the abstrations in use in more + detail. This module allows to reuse Tamaya's implementation artifacts but + still allow alternate implementations of the core API to be used. === Compatibility
