Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master babbc85db -> 5b6657205

Added documentation for JSR module.

Signed-off-by: Anatole Tresch <>


Branch: refs/heads/master
Commit: 5b6657205ff8a635e627082889d44c1cd202016a
Parents: babbc85
Author: Anatole Tresch <>
Authored: Tue Feb 20 01:14:02 2018 +0100
Committer: Anatole Tresch <>
Committed: Tue Feb 20 01:14:02 2018 +0100

 content/documentation-new/core.adoc | 283 +++++++++++++++++++++++++++++++
 1 file changed, 283 insertions(+)
diff --git a/content/documentation-new/core.adoc 
new file mode 100644
index 0000000..e7a2c46
--- /dev/null
+++ b/content/documentation-new/core.adoc
@@ -0,0 +1,283 @@
+:jbake-type: page
+:jbake-status: published
+== Tamaya Core Implementation
+=== Overview
+Tamaya Core provides an implementation of the link:api.html[Configuration API] 
and adds additional functionality
+and building blocks for supporting SPI implementations.
+Tamaya contains the following core artifacts:
+* *tamaya-base* provides implementations and base classes for different API 
artifacts such as +Config,
+  ConfigContext, ConfigBuilder, BaseConfigSource+ and more. It is
+  built as an independent module, which also can be used with other 
+* The *tamaya-core*
+  implementation
+  ** leverages these base classes to build up a full API implementation, 
adding converter
+  implementations for most common Java types.
+  ** A +java.util.ServiceLoader+ based +ServiceContext+ implementation. This 
allows component priorization based
+  on the +@Priority+ annotations.
+  ** A +PropertyConverterManager+ that loads and stores references to all the 
preconfigured +PropertyConverter+ instances,
+  thus providing type conversion for all important types.
+* A simple default configuration setup using the current classpath and an 
optional staging variable.
+* It collects all +ConfigSource+ and +ConfigSourceProvider+ instances 
registered with the +ServiceLoader+ and
+  registers them in the global +ConfigurationContext+
+* It provides a +ConfigBuilder+ implementation (+DefaultConfigBuilder+), 
including an extended +TamayaConfigBuilder+
+  variant.
+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 (+org.apache.tamaya.ext:tamaya-formats+)
+* integration with other existing solutions (e.g. 
+* configuration and configuration isolation targeting Java EE 
+* dynamic configuration and configuration updates 
+* remote configuration (+org.apache.tamaya.ext:tamaya-etcd, 
+  org.apache.tamaya.ext:tamaya-hazelcast+)
+* and more
+For details about the extension modules available and  their functionality 
refer to the link:extensions.html[extension user guide].
+=== Default Converters
+The _SPI_ base module provides several +Converter+ implementations, which are 
automatically registered by the
+_Core_ module. Find below the listing of converters automatically registered 
with the Core module:
+|_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, 
+|java.ui.lang.Character     |CharConverter             |0xFF, 'a', 'H', 123
+|java.ui.lang.Class         |ClassConverter            |<fully qualified class 
+|java.util.Currency         |CurrencyConverter         |CHF, 123
+|java.ui.lang.Double        |DoubleConverter           |1, 0xFF, 1.2334, NaN, 
+|_Enums_                    |EnumConverter             |<Enum item name>
+|java.ui.lang.Float         |FloatConverter            |1, 0xFF, 1.2334, NaN, 
+|java.ui.lang.Integer       |IntegerConverter          |1, 0xD3, MIN_VALUE, 
+|LocalDate                  |LocalDateConverter        |<Date as defined by 
+|LocalTime                  |LocalTimeConverter        |<Time as defined by 
+|LocalDateTime              |LocalDateTimeConverter    |<LocalDateTime as 
defined by LocalDateTime.parse(String)>
+|java.ui.lang.Long          |LongConverter             |1, 0xD3, MIN_VALUE, 
+|java.ui.lang.Number        |NumberConverter           |1, 0xFF, 1.2334, NaN, 
+|java.ui.lang.Short         |ShortConverter            |1, 0xD3, MIN_VALUE, 
+|               |URIConverter              
+|               |URLConverter              
+|ZoneId                     |ZoneIdConverter           |Europe/Zurich
+=== Registering Converters
+Additional +Converters+ can be implemented easily. It is recommended to 
register them using
+the +java.util.ServiceLoader+, meaning you add a file under 
+containing the fully qualified class names of the converters to be registered 
(one line each) to enable
+Alternatively you can also use a +TamayaConfigBuilder+ to add additional 
converters programmatically.
+=== Component Loading and Priorization
+Tamaya _Core_ in general loads all components by default 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 such a functionality with the possibility to 
add +@Priority+
+annotations to the components registered. By default, and if no annotation is 
added +0+ is assumed
+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 
+* if a _collection_ of components is obtained from the +ServiceContext+ the 
components are _ordered_
+  based on their priorities, 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 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 
+      you can apply a different logic:
+=== Registering ConfigSources
++ConfigSource+ implementations that provide configuration properties are 
registered as components as described in the
+previous section. Hereby the precedence (ordering) of property sources is not 
hard-coded. Instead a +Comparator<ConfigSource>+
+can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering 
of the property sources
+registered. The default implementation hereby uses the following logic:
+. It checks for an property entry +config.ordinal+ if present the value is 
parsed into an +int+ value and used as
+  the ordinal val value.
+. It checks for an explicit method +int getOrdinal()+, if found its value is 
taken as an ordinal.
+. It checks for a +@Priority+ annotation, if present the priority value is 
used as an ordinal.
+. If none of the above works, +0+ is assumed as ordinal value.
+. If multiple +ConfigSource+ instances share the same ordinal value, they are 
ordered based on their fully qualified
+  class names.
+Custom implementations of the config source comparator can be applied by 
++TamayaConfigBuilder.sortSources(Comparator<ConfigSource>)+. The default 
comparator can be replaced
+by passing the fully qualified comparator class name as system property:
+The ladder allows to adapt the ordering of auto-discovered config sources, 
even if the value returned by
++int getOrdinal()+ cannot be changed.
+== 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/
+  and +META-INF/javaconfig.xml+
+=== Overview of Registered Default Config Sources and Providers
+The Tamaya Core implementation provides a couple of default +ConfigSource+ 
implementations, which are automatically
+registered. They are all in the package +org.apache.tamaya.base.configsource+:
+|_Type_                                   |_Class Name_                   
|_Ordinal Used_
+|META-INF/           |JavaConfigurationProvider      |100
+|META-INF/javaconfig.xml                  |JavaConfigurationProvider      |100
+|JNDI Entries                             |JNDIConfigSource               |200
+|Environment Properties                   |EnvironmentConfigSource        |300
+|System Properties                        |SystemConfigSource             |1000
+NOTE: Similarly to converters the config sources shown here are defined within 
the "tamaya-base* module
+      and automatically registered with the *tamaya-core* implementation using 
Tamaya's auto-discovery mechanisms.
+NOTE: +JNDIConfigSource+ is provided by the `tamaya-jndi` extension module.
+=== Abstract Class PropertiesFileConfigSource
+The abstract class +PropertiesFileConfigSource+ can be used for implementing a 
+ConfigSource+ based on a +URL+
+instance that points to a +.properites+ file. It requires a +URL+ to be passed 
on the constructor:
+PropertiesFileConfigSource(URL url);
+==== Abstract Class PropertiesConfigSource
+The abstract class +PropertiesConfigSource+ can be used for implementing a 
+ConfigSource+ based on a +Properties+
+instance. It requires a +Properties+ to be passed on the constructor:
+PropertiesConfigSource(Properties properties);
+==== Abstract Class BaseConfigSource
+The abstract class +BaseConfigSource+ can be used for implementing custom 
+ConfigSource+ classes. It requires only
+one method to implemented:
+.Implementing a ConfigSource using BaseConfigSource
+public class MyConfigSource extends BaseConfigSource{
+    public String getName(){
+        // return a unique name for the config 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 config source
+    }
+By default the ordinal of the config sources will be 1000, unless the key 
+as defined in +ConfigSource.CONFIG_ORDINAL+ is present in the current 
+ConfigSource+. Of course
+it is also possible to override the inherited +protected void 
initializeOrdinal(final int defaultOrdinal)+,
+or directly +int getOrdinal()+.
+=== Default ConfigSourceProvider in Core
+With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also 
a default +ConfigSourceProvider+
+present that loads all files found at 
+and +META-INF/javaconfig.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 +ConfigContext+ by implementing the 
+ * Component SPI which encapsulates the evaluation of a single or full 
+ * for a {@link ConfigurationContext}.
+ */
+public interface ConfigValueEvaluator {
+    /**
+     * Evaluates single value using a {@link ConfigContext}.
+     * @param key the config key, not null.
+     * @param context the context, not null.
+     * @return the value, or null.
+     */
+    ConfigValue evaluteRawValue(String key, ConfigContext context);
+    /**
+     * Evaluates all property values from a {@link ConfigurationContext}.
+     * @param context the context, not null.
+     * @return the value, or null.
+     */
+    Iterable<ConfigValue> evaluateRawValues(ConfigContext context);
+The default implementation +DefaultConfigValueEvaluator+ implements the 
following logic:
+. Collect all +ConfigSources+ from the context.
+. Access +String get(String)+ (single key access)/ +Map<String,String> 
+  (config map access) from each property source and combine the previous with 
the next value using
+  the +ConfigValueCombinationPolicy+ 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
+== Adding Extensions
+Tamaya _Core_ 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].

Reply via email to