API Concepts

[Anatole Tresch <at...@gmail.com>]

Hi all

I put together a first summary of the API concepts. Many of the things, we
already had a look at, whereas others we already faced are NOT part of the
API, but implementation specific. The APOI IMO is quite small. Hope this
makes sense for you - let me know.

I will try to put together a implementation summary (core) as well...

Cheers,
Anatole


 * The API contains the following core concepts/artifacts: *

   -

   * Literal Key/Value Pairs *
    -

   *PropertyProvider: is the the SPI for a source that provides
   configuration data. A PropertyProvider hereby defines *
    -

      * a minimalistic SPI to be implemented by the config data source *
       -

      * provides data key/value pairs in raw format as String key/values
      only *
       -

      * providers should not have any dependencies other than to the
      datasource *
       -

      * providers may read context dependent data, but basically providers
      themselves are not contextual. Context management should be done by the
      ConfigurationProvider implementation that also is responsible
for combining
      a set of property providers to a Configuration. Configuration is the API
      that users of Tamaya will see, when they access configuration in raw
      format. Hereby Configuration *
       -

      * adds type support for non String types *
       -

      * provides functional extension points (with,query) *
       -

      * allows registering/deregistering of change listeners *
       -

      * is the entry point for evaluating the current Configuration *
       -

      * each PropertyProvider can be easily converted into a Configuration *
       -

      * allows configuration entries to be injected *
       -

      * to access configuration templates (annotated interfaces). *
       -

      * Configuration may support mutability by allowing instances of
      ConfigChangeSet to be passed. *
        -

   *PropertyProviders allows to aggregate different property providers.
   Hereby property providers are seen as sets, which can be combined to new
   providers using set styled operations (aggregate, intersect, subtract).
   This allows to model and create composite container providers, to build up
   more complex configuration models step by step. *
    -

   *MetaInfo is provided by each Configuration, PropertyProvider and
   describes the configuration/provider and its entries. *
    -

   *Environment is the base model for modelling the environment and the
   accessor for getting the current Environment instance. *
    -

   *Annotations a set of annotations allows to configure configuration
   injection on classes or interface (aka config templates). *

 * The SPI contains the following core concepts/artifacts: *

   -

   *Bootstrap is the delegate singleton that is used by the framework to
   resolve components. The effective component loading can be accessed by
   implementing and registering an instance of ServiceProvider using
   java.util.ServiceLoader. *
    -

   * All the singleton used explicitly (PropertyAdapters,PropertyProviders
   are backed up corresponding API interfaces. To override a singleton’s
   behaviour the corresponding SPI has to be implemented and registered, so it
   can be loaded by the current Bootstrap setup (by default ServiceLoader
   based). *
    -

   * Also the singleton used implicitly by Configuration, Environment,
   Stage are backed up corresponding SPI interfaces. To override a singleton’s
   behaviour the corresponding SPI has to be implemented and registered, so it
   can be loaded by the current Bootstrap setup (by default ServiceLoader
   based). *

 * This is also reflected in the main parts of the API, which is quite
small: *

   -

   *org.apache.tamaya contains the main abstractions Configuration,
   ConfigOperator, ConfigQuery, PropertyAdapter, Stage, Environment,
   PropertyProvider, MetaInfo *
    -

   *org.apache.tamaya.spi contains the SPI interfaces to be implemented by
   implementations and the Bootstrap mechanism. + org.apache.tamaya.annot
   contains the annotations defined. *

 * In the implementation are there are additional projects: *

   -

   *org.apache.tamaya.core contains the core implementation of the API.
   Deploying it together with the API results in a flexible framework that can
   be easily used for configuration of different complexity. But out of the
   box this framework will not do much more than exposing system and
   environment properties, its power comes when an additional meta-model is
   defined and deployed. Hereby you can write your own, or use on e of the
   provided ones (see later). *
    -

   * the core part is extended by multiple additional modules *
    -

      * CDI integration *
       -

      * Default configuration meta-models and providers for the most common
      usage scenarios *
       -

         * standalone applications *
          -

         * Java EE *
          -

         * …      *