You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2015/12/06 16:16:08 UTC
incubator-tamaya git commit: Added / updated documentation.
Repository: incubator-tamaya
Updated Branches:
refs/heads/master 0ebe01b33 -> 062109a95
Added / updated documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/062109a9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/062109a9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/062109a9
Branch: refs/heads/master
Commit: 062109a95c8d91890be99cc554130c33562b09bd
Parents: 0ebe01b
Author: anatole <an...@apache.org>
Authored: Sun Dec 6 16:15:59 2015 +0100
Committer: anatole <an...@apache.org>
Committed: Sun Dec 6 16:15:59 2015 +0100
----------------------------------------------------------------------
src/site/asciidoc/extensions/mod_injection.adoc | 172 +++++++++++++------
src/site/asciidoc/extensions/mod_model.adoc | 156 +++++++++++++----
src/site/asciidoc/extensions/mod_osgi.adoc | 78 +++++++++
3 files changed, 324 insertions(+), 82 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/062109a9/src/site/asciidoc/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_injection.adoc b/src/site/asciidoc/extensions/mod_injection.adoc
index 63d69e0..11a654c 100644
--- a/src/site/asciidoc/extensions/mod_injection.adoc
+++ b/src/site/asciidoc/extensions/mod_injection.adoc
@@ -62,7 +62,18 @@ The module is based on Java 7, so it can be used with Java 7 and beyond.
=== Installation
-To benefit from configuration event support you only must add the corresponding dependency to your module:
+Basically Tamaya's injection API is deployed as API artifact:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-injection-api</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+To use injection with Java SE you must add the corresponding dependency to your module:
[source, xml]
-----------------------------------------------
@@ -73,9 +84,18 @@ To benefit from configuration event support you only must add the corresponding
</dependency>
-----------------------------------------------
+Similarly there are other injection implementations available, targetig platforms such as
+
+* Spring, Spring Boot
+* Java EE/CDI
+* OSGI, Apache Felix/Apache Karaf
+
+
=== Core Concepts
-As an example refer to the following
+Basically you annotate fields or methods in your beans with +@Config+ to enable configuration injection. Tamaya
+additionally defines further annotations that allo you to define additional aspects such as default values, custom
+converters etc. The following example illustrates the basic functionality:
code snippet:
[source,java]
@@ -88,12 +108,12 @@ public class ConfiguredClass{
// resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
private String testProperty;
- @ConfiguredProperty(keys={"a.b.c.key1","a.b.legacyKey",area1.key2"})
+ @Config({"a.b.c.key1","a.b.legacyKey",area1.key2"})
@DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
String value1;
// Using a (default) String -> Integer converter
- @ConfiguredProperty(keys="a.b.c.key2")
+ @Config("a.b.c.key2")
private int value2;
// resolved by default as foo.bar.ConfiguredClass.accessUrl
@@ -106,7 +126,7 @@ public class ConfiguredClass{
private Integer int1;
// Overriding the String -> BigDecimal converter with a custom implementation.
- @ConfiguredProperty(keys="BD")
+ @Config("BD")
@WithPropertyConverter(MyBigDecimalRoundingAdapter.class)
private BigDecimal bigNumber;
@@ -114,8 +134,37 @@ public class ConfiguredClass{
}
--------------------------------------------
-The class does not show all (but most) possibilities provided. Configuring an instance of the
-class using Tamaya is very simple. The only thing is to pass the instance to Tamaya to let
+
+When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
+this feature a class must be annotated with +@ConfigAutoInject+:
+
+[source, java]
+. An autoinjected bean class
+--------------------------------------------
+package a.b;
+
+@ConfigAutoInject
+public final class Tenant{
+ private int id;
+ private String name;
+ private String description;
+ @NoConfig // prevents auto injection for this field
+ private String id2;
+
+ public int getId(){
+ return id;
+ }
+ public String getName(){
+ return name;
+ }
+ public String getDescription(){
+ return description;
+ }
+}
+--------------------------------------------
+
+These examples do not show all possibilities provided. Configuring instance of these
+class using Tamaya is very simple: Just pass the instance to Tamaya to let
Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible):
[source,java]
@@ -123,14 +172,22 @@ Tamaya inject the configuration (or throw a +ConfigException+, if this is not po
--------------------------------------------
ConfiguredClass classInstance = new ConfiguredClass();
ConfigurationInjector.configure(configuredClass);
+
+Tenant tenant = new Tenant();
+ConfigurationInjector.configure(tenant);
--------------------------------------------
+NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
+with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
+documentation.
+
+
=== The Annotations in detail
==== The ConfigurationInjector
The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured
by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed
-hereby must not be annotated with +@ConfiguredProperty+ for being configurable. By default Tamaya
+hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
tries to determine configuration for each property of an instance passed, using the following resolution policy:
Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
@@ -153,31 +210,6 @@ Tenant.description=Any kind of tenant.
name=<unnamed>
--------------------------------------------
-The following bean can be configured as follows:
-
-[source, java]
---------------------------------------------
-package a.b;
-
-@ConfiguredType(autoConfigure=true)
-public final class Tenant{
- private int id;
- private String name;
- private String description;
-
- public int getId(){
- return id;
- }
- public String getName(){
- return name;
- }
- public String getDescription(){
- return description;
- }
-}
-
-Tenant tenant = ConfigurationInjector.getInstance().configure(new Tenant());
---------------------------------------------
==== Accessing ConfiguredItemSupplier instances
@@ -213,21 +245,19 @@ To illustrate the mechanism below the most simple variant of a configured class
.Most simple configured class
--------------------------------------------
pubic class ConfiguredItem{
- @ConfiguredProperty
+ @Config
private String aValue;
}
--------------------------------------------
-When this class is configured, e.g. by passing it to +Configuration.configure(Object)+,
+When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
the following is happening:
-* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.of();+
-* The current property value (String) is evaluated by calling +cfg.get("aValue");+
+* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
+* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
+ keys are possible).
* if not successful, an error is thrown (+ConfigException+)
* On success, since no type conversion is involved, the value is injected.
-* The configured bean is registered as a weak change listener in the config system's underlying
- configuration, so future config changes can be propagated (controllable by applying the
- +@WithLoadPolicy+ annotation).
==== Using @DefaultValue
@@ -236,7 +266,7 @@ In the next example we explicitly define the property value:
--------------------------------------------
pubic class ConfiguredItem{
- @ConfiguredProperty(keys={"aValue", "a.b.value","a.b.deprecated.value"})
+ @Config({"aValue", "a.b.value","a.b.deprecated.value"})
@DefaultValue("${env:java.version}")
private String aValue;
}
@@ -251,7 +281,7 @@ commit new values exactly, when convenient for you.
--------------------------------------------
pubic class ConfiguredItem{
- @ConfiguredProperty(keys={"aValue", "a.b.value","a.b.deprecated.value"})
+ @Config({"aValue", "a.b.value","a.b.deprecated.value"})
@DefaultValue("${env:java.version}")
private DynamicValue aValue;
}
@@ -316,13 +346,13 @@ instance is not changed.
==== Ommitting Injection using @NoConfig
-Adding the @NoConfig annotation prevents a field or method to be selected (mostly auto-selected) for
-configuration. This is especially useful, if a type is annotated as @ConfiguredType with auto-confiuration
+Adding the @NoConfig annotation prevents a field or method to be auto-injected from
+configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with auto-confiuration
turned on as follows:
[source,java]
--------------------------------------------
-@ConfiguredType(autoConfigure=true)
+@ConfigAutoInject
pubic class ConfiguredItem{
@NoConfig
@@ -349,7 +379,7 @@ filtering or validating the visible properties for a certain use case.
@WithConfigOperator(MyConfigView.class)
pubic class ConfiguredItem{
- @ConfiguredProperty
+ @Config
private String a;
}
@@ -360,7 +390,7 @@ pubic class ConfiguredItem{
The @WithPropertyConverter annotation allows you to define a class of type +PropertyConverter+, to be applied
on a property configured to convert the String value to the expected injected type. This can be used for
-various use cases, e.g. adding custom formats, validation, decryption.
+various use cases, e.g. adding custom formats, config models, decryption.
[source,java]
--------------------------------------------
@@ -368,7 +398,7 @@ various use cases, e.g. adding custom formats, validation, decryption.
pubic class ConfiguredItem{
@WithPropertyConverter(MyPropertyConverter.class)
- @ConfiguredProperty
+ @Config
private String a;
}
@@ -387,9 +417,53 @@ enum hereby defines the various loading modes.
pubic class BootTimeStableConfig{
@WithPropertyConverter(MyPropertyConverter.class)
- @ConfiguredProperty
+ @Config
private String a;
}
--------------------------------------------
+
+=== Configuration Events
+
+Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
+event backend in use, if and how events are published:
+
+* when you have the CDI extension active events are published using the default CDI event mechanism.
+* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
+* if no event delegation is available no events are published.
+
+The event published is very simple:
+
+[source,java]
+--------------------------------------------
+public interface ConfiguredType {
+ Class getType();
+ String getName();
+ public Collection<ConfiguredField> getConfiguredFields();
+ Collection<ConfiguredMethod> getConfiguredMethods();
+ void configure(Object instance, Configuration config);
+}
+
+
+public interface ConfiguredField {
+ Class<?> getType();
+ Collection<String> getConfiguredKeys();
+ String getName();
+ String getSignature();
+ Field getAnnotatedField();
+ void configure(Object instance, Configuration config);
+}
+
+public interface ConfiguredMethod {
+ Collection<String> getConfiguredKeys();
+ Class<?>[] getParameterTypes();
+ Method getAnnotatedMethod();
+ String getName();
+ String getSignature();
+ void configure(Object instance, Configuration config);
+}
+----------------------------------------
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/062109a9/src/site/asciidoc/extensions/mod_model.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_model.adoc b/src/site/asciidoc/extensions/mod_model.adoc
index 96cc682..326a7f3 100644
--- a/src/site/asciidoc/extensions/mod_model.adoc
+++ b/src/site/asciidoc/extensions/mod_model.adoc
@@ -46,7 +46,7 @@ toc::[]
=== Overview
The Tamaya model module provides support for documenting configuration and validating configuration read and processed
-against this model. Documentation and validation can be provided in different ways:
+against this model. Documentation and config models can be provided in different ways:
* as separate meta-model documents
* by providers that check classes/packages for configuration annotations (planned)
@@ -95,7 +95,7 @@ Now with only these 2 concepts a simple configuration meta-model can be defined
a separator character.
** may be required, or optional
** may have an optional description
- ** may have additional custom validations configured.
+ ** may have additional custom configModels configured.
* Parameters additionally have
** a _type_, described by the fully qualified class name, into which any configured (String) value must be
convertable into. If no type is configured +java.lang.String+ should be assumed as default.
@@ -103,7 +103,7 @@ Now with only these 2 concepts a simple configuration meta-model can be defined
configuration.
Given these concepts a configuration can be fully described. Entries that are not contained in one of the given
-sections (or its children), or parameters not described or marked as valid (e.g. for dynamic validations of
+sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of
a section), are called _undefined_. Undefined parameters should be grouped with its parent section. Each section, as
well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and
only if
@@ -112,7 +112,7 @@ only if
. the section is not a _super section_ of a defined section.
As en example the section definition of +a.b.c+ also implicitly includes the sections +a.b+ and +a+ to be defined
-sections, despite the fact that section properties, such as description and custom validations are not inherited to
+sections, despite the fact that section properties, such as description and custom configModels are not inherited to
its parent, or child section.
@@ -147,7 +147,7 @@ variants supported:
# custom validated section
{model}.validated.class=Section
-{model}.validated.validations=org.apache.tamaya.model.TestValidator
+{model}.validated.configModels=org.apache.tamaya.model.TestValidator
-------------------------------------------------------------------------------
Above +org.mycompany.root+ transitively defines 3 sections:
@@ -161,7 +161,7 @@ Required sections are checked so the section is not empty. It is not checked for
only the existance of any child parameter is validated.
The _class_ attribute has to be defined for any section definition, because if not set a model entry is, by default,
-defined to be a parameter validation entry. Given above the entry for the section +minimal+ shows such a minimal
+defined to be a parameter configModel entry. Given above the entry for the section +minimal+ shows such a minimal
entry.
+validated+ defines a section, which is validated through a customizable validator. Hereby an ordered list of validators
@@ -183,7 +183,7 @@ Similarly parameters also can be defined:
{model}.org.mycompany.security.uid.required=true
{model}.org.mycompany.security.uid.description=The user id.
{model}.org.mycompany.security.realm.required=true
-{model}.org.mycompany.security.realm.validations=org.apache.tamaya.model.RealmValidator
+{model}.org.mycompany.security.realm.configModels=org.apache.tamaya.model.RealmValidator
{model}.org.mycompany.security.real.description=The security realm required.
{model}.org.mycompany.security.tokenid.description=The token id, if the token service is used (optional).
@@ -198,7 +198,7 @@ the entry above for +org.mycompany.security.realm+ also defines the following se
* org.mycompany
* org.mycompany.security
-Additional entries for section, e.g. validations to be done, can be added as described in the previous section,
+Additional entries for section, e.g. configModels to be done, can be added as described in the previous section,
but are optional.
Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it's
@@ -226,77 +226,167 @@ By default the configuration model can be defined at the following locations:
==== Programmatic API
-Basically the validation module provides a simple API to evaluate the current +Configuration+ by as follows:
+Basically the configModel module provides a simple API to access the defined +ConfigModel+ instances and
+validating the current +Configuration+ against the models as follows:
[source,java]
-----------------------------------------------------------
-public final class ConfigValidator {
+public final class ConfigModelManager {
- private ConfigValidator() {}
+ private ConfigModelManager() {}
+
+ public static Collection<ConfigModel> getModels();
+ public static Collection<ConfigModel> findModels(ModelType type, String namePattern);
+ public static <T extends ConfigModel> T getModel(String name, Class<T> modelType);
+ public static Collection<ConfigModel> findModels(String namePattern);
public static Collection<ValidationResult> validate();
public static Collection<ValidationResult> validate(boolean showUndefined);
public static Collection<ValidationResult> validate(Configuration config);
public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined);
- public static Collection<Validation> getValidations();
+ public static void registerMBean();
+ public static void registerMBean(String context);
+
}
-----------------------------------------------------------
-This singleton allows to validate the current or any +Configuration+ instance. All the validations read also are
-available from the +getValidations+ method, which returns you not less than a instance of the current
-configuration model. This instance can be used to provide documentation, e.g. as part of a CLI interface or
-shown on a documentation web server.
+This singleton allows to validate the current or any +Configuration+ instance. All the ConfigModels read also are
+available from the +getModels+ method. This models can be used to provide documentation, e.g. as part of a CLI interface
+or shown on a documentation web server.
-A +Validation+ hereby is defined as:
+A +ConfigModel+ hereby is defined as one single part of configuration, typically corresponding to a specific concern
+of your system. As an example you can define different models for different modules or products plugged together.
+With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a
+single configuration source (e.g. for configuring the machine's IP address and subnet settings only once.
[source,java]
-----------------------------------------------------------
-public interface Validation {
+public interface ConfigModel {
- String getType();
+ ModelType getType();
String getName();
+ String getProvider();
+ boolean isRequired();
String getDescription();
Collection<ValidationResult> validate(Configuration config);
}
-----------------------------------------------------------
-Similarly a +ValidationResult+ is modelled as:
+
+Hereby +ModelType+ defines more details on the kind of model:
+
+[source,java]
+-----------------------------------------------------------
+public enum ModelType {
+ /**
+ * A configuration section.
+ */
+ Section,
+ /**
+ * A configuration paramter.
+ */
+ Parameter,
+ /**
+ * ConfigModel to ensure a certain configuration filter is installed.
+ */
+ Filter,
+ /**
+ * ConfigModel to ensure a certain combination policy is active.
+ */
+ CombinationPolicy,
+ /**
+ * ConfigModel that is a container of other validations.
+ */
+ Group,
+ /**
+ * ConfigModel to simply check availability for a class on the current classpath.
+ */
+ LoadableClass
+}
+-----------------------------------------------------------
+
+A +ValidationResult+ models one validation executed by a +ConfigModel+ on a certain +Configuration+ instance:
[source,java]
-----------------------------------------------------------
public final class ValidationResult {
- public static ValidationResult ofValid(Validation validation);
- public static ValidationResult ofMissing(Validation validation);
- public static ValidationResult ofMissing(Validation validation, String message);
- public static ValidationResult ofError(Validation validation, String error);
- public static ValidationResult ofWarning(Validation validation, String warning);
- public static ValidationResult ofDeprecated(Validation validation, String alternateUsage);
- public static ValidationResult ofDeprecated(Validation validation);
+ public static ValidationResult ofValid(ConfigModel configModel);
+ public static ValidationResult ofMissing(ConfigModel configModel);
+ public static ValidationResult ofMissing(ConfigModel configModel, String message);
+ public static ValidationResult ofError(ConfigModel configModel, String error);
+ public static ValidationResult ofWarning(ConfigModel configModel, String warning);
+ public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage);
+ public static ValidationResult ofDeprecated(ConfigModel configModel);
public static ValidationResult ofUndefined(final String key);
- public static ValidationResult of(Validation validation, ValidationState result, String message);
+ public static ValidationResult of(ConfigModel configModel, ValidationState result, String message);
- public Validation getValidation();
+ public ConfigModel getConfigModel();
public ValidationState getResult();
public String getMessage(),
}
-----------------------------------------------------------
+The result of a complete validation on a concrete +Configuration+ instance finally is mapped as a
++Collection<ValidationResult>+, refer to the methods on +ConfigModelManager+.
+
+
+=== Auto-Documentation of Classes with Configuration Injection
+
+A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
+(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
+models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
+time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
+behaviour. Nevertheless this means that after your system has been started you should have access to a complete
+set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
+(through injection).
+
== Model SPI
+=== Registering Configuration Models
The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is
-the +ValidationProviderSpi+ interface, which allows any kind of additional validations to be added to the system:
+the +ModelProviderSpi+ interface, which allows any kind of additional config models to be added to the system:
[source,java]
-----------------------------------------------------------
-public interface ValidationProviderSpi {
+public interface ModelProviderSpi {
- Collection<Validation> getValidations();
+ Collection<ConfigModel> getConfigModels();
}
-----------------------------------------------------------
New instances implementing this interface must be registered into the current +ServiceContext+, by default the
-+ServiceLoader+ is used.
\ No newline at end of file
++ServiceLoader+ is used.
+
+
+=== Other Utility Classes
+
+The module also provides further utility classes that may be useful for implementing models or testing:
+
+* +AbstractModel+ provides a base class that can be extended, when implementing +ConfigModel+.
+* +AreaConfigModel+ provides a +ConfigModel+ implementation (with a corresponding +Builder+) to model the
+ requirement of certain configuration sections being present, or opionally present, in the model.
+* +ParameterModel+ provides an implementation base class for validating parameters on existence and compliance
+ with a regular expression.
+* +ConfigDocumentationMBean+ is the MBean registered that models similar functionality as +ConfigModelManager+.
+* +ConfigModelGroup+ provides a +ConfigModel+ that groups several child models.
+* +ConfigModelReader+ allows to read +ConfigModels+ from properties files as described at the beginning of this
+ document.
+
+
+=== Switches to enable/disable functionality
+
+The model module provides different switches that can be used to activate or deactivate features:
+
+* +org.apache.tamaya.model.integrated.enabled+ allows to deactivate reading inline metaconfiguration delivered with
+ the normal Tamaya Configuration. By default inline entries (+{meta}...+) are evaluated.
+* +org.apache.tamaya.model.default.enabled+ allows to deactivate reading metamodel information from
+ +classpath:META-INF/configmodel.properties+. By default it is active.
+* +org.apache.tamaya.model.resources+ allows to defie additional resources (loaded through the resources extension),
+ that can be used to read metamodel information in any format using Tamaya's format module.
+* the system property +org.apache.tamaya.model.autoModelEvents+ allows to activate/deactivate the automatic documentation of
+ classes configured and published by Tamaya +ConfiguredType+ event instances (e.g. published by Tamaya's injection
+ modules).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/062109a9/src/site/asciidoc/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_osgi.adoc b/src/site/asciidoc/extensions/mod_osgi.adoc
new file mode 100644
index 0000000..8f906d4
--- /dev/null
+++ b/src/site/asciidoc/extensions/mod_osgi.adoc
@@ -0,0 +1,78 @@
+= Apache Tamaya -- Extensions: OSGI Integrations
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.osgi
+:title: Apache Tamaya Extensions: OSGI Integration
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: December 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:toc:
+:toc-placement: manual
+:encoding: UTF-8
+:numbered:
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[Optional]]
+== Tamaya OSGI Support
+=== Overview
+
+Tamaya provides also support for integration with OSGI. Hereby several options are available how Tamaya can be used in
+an OSGI context:
+
+. All Tamaya modules, its API and core library are actually valid OSGI bundles. So adding them into your OSGI modules
+ and using Tamaya is basically directly supported. Nevertheless OSGI works rather differently from a class- and
+ resource loading perspective. As long as you rely on Tamaya's mechanisms for resource loading things should work
+ out of the box. In the back Tamaya's core module actually comes with implicit OSGI support, which is automatically
+ activated, if Tamaya is running in an OSGI context. This support actually
+ ** Listens on deployed bundles and activel reads all resources registered as +ServiceLoader+ services and registers
+ them as OSGI services.
+ ** Uses the OSGI bundle to resolve any further resources, because accessing them from the classloader directly
+ typically fails in an OSGI context.
+.. Adding Tamaya's OSGI _general_ module replaces the existing OSGI +ConfigAdmin+ service with an istance based on
+ Tamaya.
+.. Adding Tamaya's OSGI _Felix_ module reimplements Felix's +FilePropertyManager+ module, hereby using any preexisting
+ instance as backend. This allows to use Tamaya as overriding configuration provider with runtime environments that
+ are based on Apache Felix and Apache Karaf.
+.. Tamaya's injection module actually combines Tamaya's base functionality and injecion capabilities with the
+ current +ConfigAdmin+ to resolve the effective raw properties. Hereby the values returned from the OSGI
+ +ConfigAdmin+ method are added to Tamaya's configuration model as a normal +PropertySource+. This way users
+ can simply decide using Tamaya's configuration model, how values from OSGI and Tamaya should be combined BEFORE
+ they are used for configuration injection. Configuration injection itself is done by Tamaya's _injection_ module
+ for Java SE.
+
+
+=== Compatibility
+
+All module described are based on Java 7, so it will not run on Java 7 and beyond.
+TBD: OSGI version required.
+
+