Repository: incubator-tamaya-site Updated Branches: refs/heads/master 425bda132 -> 16e1f9bbe
Clarified documentation. 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/16e1f9bb Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/16e1f9bb Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/16e1f9bb Branch: refs/heads/master Commit: 16e1f9bbe8e40d451871619bac1a2f6cb95d34f8 Parents: 425bda1 Author: anatole <anat...@apache.org> Authored: Fri Feb 3 09:22:02 2017 +0100 Committer: anatole <anat...@apache.org> Committed: Fri Feb 3 09:22:28 2017 +0100 ---------------------------------------------------------------------- content/documentation/api.adoc | 218 ++++++++++++++++++++---------------- 1 file changed, 120 insertions(+), 98 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/16e1f9bb/content/documentation/api.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/api.adoc b/content/documentation/api.adoc index a2f4fea..c895ef0 100644 --- a/content/documentation/api.adoc +++ b/content/documentation/api.adoc @@ -4,51 +4,62 @@ [[CoreDesign]] == Apache Tamaya: API -Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required -that are the base of all the other mechanisms. As a starting point we recommend you read the corresponding +Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required. +Everything else uses or extends these basic mechanisms. As a starting point we recommend you read the corresponding link:../highleveldesign.html[High Level Design Documentation] [[API]] == The Tamaya API The API provides the artifacts as described in the link:../highleveldesign.html[High Level Design Documentation], which are: -* A simple but complete SE *API* for accessing key/value based _Configuration_: - ** +Configuration+ hereby models configuration, the main interface of Tamaya. +Configuration+ provides +* The package +org.apache.tamaya+ defines a simple but complete SE *API* for accessing key/value based _Configuration_: + ** +Configuration+ hereby models _configuration_, the main interface of Tamaya. +Configuration+ provides *** access to literal key/value pairs. *** functional extension points (+with, query+) using a unary +ConfigOperator+ or a function +ConfigurationQuery<T>+. ** +ConfigurationProvider+ provides with +getConfiguration()+ the static entry point for accessing configuration. ** +ConfigException+ defines a runtime exception for usage by the configuration system. - ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned by a registered - +PropertyProvider+. + ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned in case non-String types + are accessed. ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type. -* Additionally the *SPI* provides: - ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+ hereby - *** is designed as a minimalistic interface that be implemented by any kind of data provider (local or remote) - *** provides single access for key/value pairs in raw format as String key/values only (+getPropertyValue+). - *** can optionally support scanning of its provided values, implementing +getProperties()+. - ** _PropertySourceProvider:_ allows to register multiple property sources dynamically, e.g. all config files found in - file system folder.. - ** +ConfigurationProviderSpi+ defines the SPI that is used as a backing bean for the +ConfigurationProvider+ - singleton. - ** +PropertyFilter+, which allows filtering of property values prior getting returned to the caller. - ** +PropertyValueCombinationPolicy+ optionally can be registered to change the way how different key/value - pairs are combined to build up the final +Configuration+ passed over to the filters registered. - ** +ConfigurationContext+, which provides a container for all the artifacts needed to build up a +Configuration+. - For example a context contains the property sources, property filters, converters and combination policy used. - Also the ordering of the property sources is defined by the context. A context instance given a - +Configuration+ can be created by calling +ConfigurationProvider.createConfiguration(context);+. - ** Similarly a +ConfigurationContext+ can be created using a +ConfigurationContextBuilder+. This builder can be - obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+. - ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack. - ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded. - -This is also reflected in the main packages of the API: - -* +org.apache.tamaya+ contains the main API abstractions used by users. -* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+ - mechanism. +* The package +org.apache.tamaya.spi+ provides interfaces used for extending and/or + adapting Tamaya's core functionality, as well as artifacts for creating + +Configuration+ instances programmatically: + ** _PropertySource:_ is the the interface to be implemented for adding configuration entries. A +PropertySource+ hereby + *** is minimalistic and can be implemented in any way. E.g. there is no distiction that + the configuration data provided is managed locally, remotedely. There is even no + requirement that the configuration data is always fully available. Summarizing a + +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. + ** _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 + +ConfigurationProvider+ singleton. + ** +PropertyFilter+ allows filtering of property values prior getting returned to the caller. Filters by default are + registered as global filters, filtering _raw_ values. The final +String+ value of a configuration entry is the + final value after all registered filters have been applied. + ** A +PropertyValueCombinationPolicy+ optionally can be registered to change the logic how key/value + pairs from subsequent property sources in the property source chain are combined to calculate the final + _raw_ value passed over to the filters registered. + ** A +ConfigurationContext+ is the container of all inner components (+PropertySource, PropertyFilter, + PropertyValueCombinationPolicy, PropertyConverter+) required to implement a +Configuration+. Also the ordering + of the property sources, filters and converters is defined by the context. + A +ConfigurationContext+ is automatically created on startup collecting and adding all registered artifacts. + Based on this +ConfigurationContext+ the _default_ +Configuration+ is created, which can be accessed from + +ConfigurationProvider.getConfiguration+. + Summarizing a +ConfigurationContext+ contains the ordered property sources, property filters, converters and combination + policy used. Once a +ConfigurationContext+ is instanciated a corresponding +Configuration+ instance can be + created easily by calling +ConfigurationProvider.createConfiguration(context)+. + ** Finally Tamaya also supports _programmatically_ creating +Configuration+ instances and using them in your code + as needed. This can be achieved most easily by building a custom +ConfigurationContext+ using a + +ConfigurationContextBuilder+. This builder can be obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+. + ** Finally +ServiceContext+ and +ServiceContextManager+ provide an abstraction to the underlying runtime environment, + allowing different component loading and lifecycle strategies to be used. This is very useful since component (service) + loading in Java SE, Java EE, OSGI and other runtime environments may be differ significantly. In most cases even + extension programmers will not have to deal with these two artifacts. @@ -119,8 +130,8 @@ Nevertheless most of these advantages can be mitigated easily, hereby still keep === Configuration -+Configuration+ is the main API provided by Tamaya. It allows reading of single property values or the whole -property map, but also supports type safe access: ++Configuration+ is the main artifact provided by Tamaya. It allows reading of single property values or all known +properties, but also supports type safe access: [source,java] .Interface Configuration @@ -149,6 +160,7 @@ Hereby * +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+. +* +getConfigurationContext()+ allows access to the underlying components of a +Configuration+ instance. The class +TypeLiteral+ is basically similar to the same class provided with CDI: @@ -177,6 +189,7 @@ public class TypeLiteral<T> implements Serializable { } -------------------------------------------- + Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton: [source,java] @@ -185,41 +198,41 @@ Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ si Configuration config = ConfigurationProvider.getConfiguration(); -------------------------------------------- -Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+. +Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+, which is managed by the ++ServiceContextManager+ (see later). [[PropertyConverter]] ==== Property Type Conversion -As illustrated in the previous section, +Configuration+ also to access non String types. Nevertheless internally -all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the -configured String values into the required target type. This is achieved with the help of +PropertyConverters+: +As illustrated in the previous section, +Configuration+ also allows access of typed values. Internally +all properties are strictly modelled as Strings. As a consequence non String values must be derived by converting the +String values into the required target type. This is achieved with the help of +PropertyConverters+: [source,java] -------------------------------------------- public interface PropertyConverter<T>{ T convert(String value, ConversionContext context); - //X TODO Collection<String> getSupportedFormats(); } -------------------------------------------- -The +ConversionContext+ contains additional meta-information for the accessed key, inclusing the key'a name and -additional metadata. +The +ConversionContext+ contains additional meta-information about the key accessed, including the key'a name and +additional metadata. This can be very useful, e.g. when the implementation of a +PropertyConverter+ requires additional +metadata for determining the correct conversion to be applied. -+PropertyConverter+ instances can be implemented and registered by default using the +ServiceLoader+. Hereby -a configuration String value is passed to all registered converters for a type in order of their annotated +@Priority+ -value. The first non-null result of a converter is then returned as the current configuration value. ++PropertyConverter+ instances can be implemented and registered by default using the Java +ServiceLoader+. The ordering +of the registered converters, by default, is based on the annotated +@Priority+ values (priority +0+ is assumed if the +annotation is missing). The first non-null result of a converter is returned as the final configuration value. -Access to converters is provided by the current +ConfigurationContext+, which is accessible from -the +ConfigurationProvider+ singleton. +Access to converters is provided by the current +ConfigurationContext+, which is accessible calling +Configuration.getConfigurationContext()+. [[ExtensionPoints]] === Extension Points We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore -we have added functional extension mechanisms to +Configuration+ that were used in other areas of the Java eco-system -as well: +we have added _functional_ extension mechanisms to +Configuration+ that were used in other areas of the +Java eco-system (e.g. Java Time API and JSR 354) as well: * +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of +Configuration+. Operators can be used to cover use cases such as filtering, configuration views, security @@ -267,10 +280,10 @@ The class +ConfigException+ models the base *runtime* exception used by the conf === Interface PropertySource We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to -understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a +java.util.Map<String, +understand, generic, flexible, yet extensible mechanism. Looking at the Java language features a +java.util.Map<String, String>+ and +java.util.Properties+ basically model these aspects out of the box. -Though there are advantages in using these types as a model, there are some severe drawbacks, notably implementation +Though there are advantages in using these types as a model, there are some drawbacks. Notably implementation of these types is far not trivial and the collection API offers additional functionality not useful when aiming for modelling simple property sources. @@ -280,7 +293,7 @@ identified to be necessary: [source,java] -------------------------------------------- public interface PropertySource{ - int getOrdinal(); + int getOrdinal(); // This feature is under discussion String getName(); String get(String key); boolean isScannable(); @@ -293,12 +306,12 @@ Hereby * +get+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available. * +getProperties+ allows to extract all property data to a +Map<String,String>+. Other methods like +containsKey, keySet+ as well as streaming operations then can be applied on the returned +Map+ instance. -* But not in all scenarios a property source may be scannable, e.g. when looking up keys is very inefficient, it - may not make sense to iterator over all keys to collect the corresponding properties. - This can be evaluated by calling +isScannable()+. If a +PropertySource+ is defined as non scannable accesses to +* But not in all scenarios a property source is able to provide all values at once (aka to be _scannable_), e.g. + when looking up keys is very inefficient, it may not make sense to iterate over all keys to collect the corresponding + 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. -* +getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where + +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 @@ -310,8 +323,9 @@ This interface can be implemented by any kind of logic. It could be a simple in provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple property sources with additional combination/aggregation rules in place. -+PropertySources+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current - active +ServiceContext+. ++PropertySources+ to be picked up automatically and be added to the _default_ +Configuration, must be registered +using the Java +ServiceLoader+ (or the mechanism provided by the current active +ServiceContext+, see later in this +document for further details). [[PropertySourceProvider]] @@ -338,17 +352,18 @@ current active +ServiceContext+. [[PropertyFilter]] === Interface PropertyFilter -Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated before a +Configuration+ instance is -passed to the user. Filters can hereby used for multiple purposes, such as +Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated each time before a configuration value +is passed to the user. Filters can be used for multiple purposes, such as * resolving placeholders * masking sensitive entries, such as passwords * constraining visibility based on the current active user * ... -+PropertyFilters+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current -active +ServiceContext+. Similar to property sources they are managed in an ordered filter chain, based on the -applied +@Priority+ annotations. +For +PropertyFilters+ to be picked up automatically and added to the _default_ +Configuration+ must be,by default, +registered using the Java +ServiceLoader+ (or the mechanism provided by the current active +ServiceContext+). +Similar to property sources they are managed in an ordered filter chain, based on the +class level +@Priority+ annotations (assuming +0+ if none is present). A +PropertyFilter+ is defined as follows: @@ -362,11 +377,11 @@ public interface PropertyFilter{ Hereby: -* returning +null+ will remove the key from the final result +* returning +null+ will remove the key from the final result. * non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies filter evaluation has to be continued as long as filters are still changing some of the values to be returned. To prevent possible endless loops after a defined number of loops evaluation is stopped. -* +FilterContext+ provides additional metdata, inclusing the key accessed, which is useful in many use cases. +* +FilterContext+ provides additional metdata, including 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. @@ -374,13 +389,10 @@ This method is called each time a single entry is accessed, and for each propert [[PropertyValueCombinationPolicy]] ==== Interface PropertyValueCombinationPolicy -This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to -build up the final Configuration to be passed over to the +PropertyFilters+. The default implementation is just -overriding all values read before with the new value read. Nevertheless for collections and other use cases it is -often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the -new value. Finally looking at the method's signature it may be surprising to find a +Map+ for the value. The basic -value hereby is defined by +currentValue.get(key)+. Nevertheless the +Map+ may also contain additional meta entries, -which may be considered by the policy implementation. +This interface is purely optional and can be used to adapt the way how property key/value pairs are combined to +build up the final configuration _raw_ value 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 +more intelligent logic is required. [source,java] -------------------------------------------- @@ -397,26 +409,31 @@ public interface PropertyValueCombinationPolicy{ } }; - String collect(Map<String,String> currentValue currentValue, String key, + Map<String,String> collect(Map<String,String> currentValue 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 '_'). + [[ConfigurationContext]] ==== The Configuration Context -A +Configuration+ is created from a +ConfigurationContext+, which is -accessible from +Configuration.getContext()+: +A +Configuration+ is created from a +ConfigurationContext+. Each +Configuration+ instance provides it's underlying +context by +Configuration.getContext()+: [source,java] .Accessing the current +ConfigurationContext+ -------------------------------------------- -ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext(); +Configuration config = ...; +ConfigurationContext context = config.getContext(); -------------------------------------------- -The +ConfigurationContext+ provides access to the internal artifacts that determine the final +Configuration+ and +The +ConfigurationContext+ provides access to the internal artifacts that determine the +Configuration+ and also defines the ordering of the property sources, filters and converters contained: * +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances). @@ -440,19 +457,21 @@ consequently +Configuration+) must be adapted: * Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the tests executed. -In such cases the +ConfigurationContext+ must be changed, meaning it must be possible: +In such cases the +ConfigurationContext+ may change, meaning it must be possible: * to add or remove +PropertySource+ instances * to add or remove +PropertyFilter+ instances * to add or remove +PropertyConverter+ instances * to redefine the current +PropertyValueCombinationPolicy+ instances. -This can be achieved by obtaining an instance of +ConfigurationContextBuilder+. Instances of this builder can be -accessed either +This is nothing new, a +ConfigurationContextBuilder+ already allows us to achive this. So we must only ensure that +we can easily create a new +ConfigurationContextBuilder+ using a given +ConfigurationContext+ as input. This can be +done by * calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the current +ConfigurationContext+. -* calling +ConfigurationProvider.getConfigurationContextBuilder()+. +* calling +ConfigurationProvider.getConfigurationContextBuilder()+ and then applying the current +ConfigurationContext+ + by calling +setContext(ConfigurationContext)+ on the +ConfigurationContextBuilder+ instance. [source,java] .Accessing a +ConfigurationContextBuilder+ @@ -461,7 +480,7 @@ ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder(); -------------------------------------------- -With such a builder a new +ConfigurationContext+ can be created and then applied: +Finally when we are finished a new +ConfigurationContext+ can be created: [source,java] .Creating and applying a new +ConfigurationContext+ @@ -473,8 +492,9 @@ ConfigurationContext context = ConfigurationProvider.getConfiguration().getConte .build(); -------------------------------------------- -Hereby the builder provides several methods for adding, removing of property sources and also operations -for programmatically change the property sourcepriorities, e.g. +But let's also have a deeper look at what functionality a +ConfigurationContextBuilder+ provides. Basically such a +builder allows to add, remove or reorder property sources, converters and filters or changing any other aspect +of a +ConfigurationContext+: [source,java] .Chain manipulation using +ConfigurationContextBuilder+ @@ -489,8 +509,9 @@ builder.decreasePriority(propertySource); builder.sortPropertyFilters(MyFilterComparator::compare); -------------------------------------------- -Finally if the new context is ready a new configuration can be created, or the context is applied to the -current configuration. +Finally if the new +ConfigurationContext+ is ready a new +Configuration+ can be created. +Optionally the new +Configuration+ can also be installed as the new _default_ +Configuration+ +instace as illustrated below: [source,java] .Creating and applying a new +ConfigurationContext+ @@ -501,22 +522,22 @@ ConfigurationContext context = builder.build(); Configuration newConfig = ConfigurationProvider.createConfiguration(context); // Apply the new context to replace the current configuration: -ConfigurationProvider.setConfigurationContext(context); +ConfigurationProvider.setConfiguration(newConfig); -------------------------------------------- -Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw an +UnsupportedOperationException+. -This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationContextSettable()+. +Hereby +ConfigurationProvider.setConfiguration(Configuration)+ can throw an +UnsupportedOperationException+. +This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationSettable()+. [[ConfigurationProviderSpi]] ==== Implementing and Managing Configuration -One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interface, which is backing up the +One of the most important SPI in Tamaya is the +ConfigurationProviderSpi+ interface, which is backing up the +ConfigurationProvider+ singleton. Implementing this class allows * to fully determine the implementation class for +Configuration+ -* to manage the current +ConfigurationContext+ in the scope and granularity required. -* to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context. +* to manage the current +Configuration+ in the scope and granularity required. +* to provide access to the right +Configuration+ based on the current runtime context. * Performing changes as set with the current +ConfigurationContextBuilder+. = Interface ConfigurationContextBuilder @@ -536,7 +557,7 @@ Configuration config = builder.build(); --------------------------------------------------------------- Basically the builder allows to create configuration instances completely independent of the current configuration -setup. This gives you full control on the +Configuration+ setup. +setup. This gives you full control how and when +Configuration+ is created. === Supported Functionality @@ -555,7 +576,7 @@ by the property sources. This allows alternate ordering policies easily being im creating a configuration based on a configuration context is already implemented and provided by the core API. -Similarly you can add filters: +Similarly you can add +PropertyFilters+: [source,java] ---------------------------------------------------------------- @@ -574,7 +595,8 @@ builder.addPropertySourceProvider(new MyPropertySourceProvider()); [[ServiceContext]] ==== The ServiceContext -The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya. +The +ServiceContext+ allows to define how components are loaded in Tamaya. It is the glue layer, which interacts +with the underlying runtime system such as Java SE, Java EE, OSGI, VertX etc. The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the +ServiceContextManager+ singleton: @@ -594,8 +616,8 @@ With the +ServiceContext+ a component can be accessed in two different ways: . access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally the most significant instance is returned only. -. access all items given its type. This will return (by default) all instances loadedable from the current - runtime context, ordered by priority, hereby the most significant components added first. +. access all items given a type. This will return (by default) all instances loadedable from the current + runtime context, ordered by priority (the most significant components added first). ## Examples @@ -682,5 +704,5 @@ com.mypackage.MyPropertySource [[APIImpl]] == API Implementation -The API is implemented by the Tamaya-Core-module. Refer to the link:core.html[Core documentation] for +The API is implemented by the +tamaya-core+ module. Refer to the link:core.html[Core documentation] for further details.
