tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject incubator-tamaya-site git commit: Clarified documentation.
Date Fri, 03 Feb 2017 08:25:54 GMT
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 <anatole@apache.org>
Authored: Fri Feb 3 09:22:02 2017 +0100
Committer: anatole <anatole@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.


Mime
View raw message