Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@tamaya.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: anatole@apache.org
To: commits@tamaya.incubator.apache.org
Message-Id: <2b599eed48df462ab7f2941787959e1b@git.apache.org>
Subject: incubator-tamaya-site git commit: TAMAYA-145: Updated OSGI
 documentation.
Date: Mon, 26 Dec 2016 08:52:03 +0000 (UTC)
archived-at: Mon, 26 Dec 2016 08:52:10 -0000

Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master 3147ee23c -> a83cd574c


TAMAYA-145: Updated OSGI 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/a83cd574
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/a83cd574
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/a83cd574

Branch: refs/heads/master
Commit: a83cd574ceb5d6828541a7013eddc41e084f627c
Parents: 3147ee2
Author: anatole <anatole@apache.org>
Authored: Sun Dec 25 12:19:22 2016 +0100
Committer: anatole <anatole@apache.org>
Committed: Sun Dec 25 12:19:22 2016 +0100

----------------------------------------------------------------------
 content/documentation/extensions/mod_osgi.adoc | 168 ++++++++++++--------
 1 file changed, 102 insertions(+), 66 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/a83cd574/content/documentation/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_osgi.adoc b/content/documentation/extensions/mod_osgi.adoc
index 3a3ffd4..9a6a55d 100644
--- a/content/documentation/extensions/mod_osgi.adoc
+++ b/content/documentation/extensions/mod_osgi.adoc
@@ -10,44 +10,20 @@ toc::[]
 == 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 actively reads all resources configured as +java.util.ServiceLoader+ services and
-     registers them as OSGI services. Hereby integration is complete meaning you can also register Tamaya services
-     as normal OSGI services, e.g. your own +PropertySource+ instances.
-  ** Uses the OSGI bundle to resolve for resources, because accessing them from the classloader directly
-     typically fails in an OSGI context.
-. Adding Tamaya's OSGI integration module replaces the existing OSGI +ConfigAdmin+ service with an istance based on
-  Tamaya. Hereby several aspects can be configured using system properties:
-  ** +org.tamaya.integration.osgi.cm.ranking+ (int) allows to configure the OSGI service ranking used by the Tamaya
-    BundleActivator to register Tamaya's +ConfigAdmin+ service. In OSGI higher ranking precede lower rankings. By default
-    Tamaya's OSGI extending service registration mechanism is reusing any annotated +@Priority+ priority values as
-    corresponsing rankings.
-  ** +org.tamaya.integration.osgi.cm.override+ (boolean) allows to configure if Tamaya is overriding any existing
-    values from the default +ConfigAdmin+ instance, or only extending them. In other words this setting allows you to
-    define, which configuration subsystem has precedence for evaluating the final values, either Tamaya based
-    configuration (default) or the configuration mechanisms provided by default from your OSGI container (when this flag
-    is set to +false+).
-  ** +org.tamaya.integration.osgi.cm.inject+ allows you to deactivate injection of configuration values into your
-    OSGI services (by default injection is enabled). In all cases accessing the OSGI +ConfigAdmin+ service to
-    read your configuration is working as usual. But Tamaya adds additional injection functionality, which allows
-    to inject typed configuration as described by the Tamaya injection api.
-
-It is also possible to combine things, e.g. when you only define a low ranking for Tamaya's configuration service and
-the same time allow injection to be active, you will have Tamaya's injection support based on your default
-OSGI configuration.
+Tamaya provides also support for integration with OSGI. Hereby Tamaya implements the OSGI +ConfigAdmin+ service,
+which is the OSGI basic component providing configuration. Tamaya by default overrides the OSGI default configuration
+but can also be configured to extend it.
 
 
 === Compatibility
 
 All module described are based on Java 7, so it will run on Java 7 and beyond.
-The modules are built against OSGI Compendium version 5.0.
+The modules are built against OSGI Compendium version 5.0. Tamaya OSGI support is tested against the following OSGI
+runtimes:
+
+* Apache Karaf, version 4.0.7
+* tbd: Apache Felix, version x.x.x.
+* tbd: Eclipse Equinox, version x.x.x.
 
 
 === Installation
@@ -59,48 +35,67 @@ environment:
 -----------------------------------------------
 # API and core
 org.apache.tamaya:tamaya-api:{tamaya_version}
-org.apache.tamaya:tamaya-core:{tamaya_version}
 org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0-alpha-1
-# injection API. SE injection module and dependencies
-org.apache.tamaya.ext:tamaya-injection-api:{tamaya_version}
-org.apache.tamaya.ext:tamaya-injection:{tamaya_version}
-org.apache.geronimo.specs:geronimo-atinject_1.0_spec:1.0
-org.apache.geronimo.specs:geronimo-el_2.2_spec:1.0.4
-org.apache.geronimo.specs:geronimo-interceptor_1.1_spec:1.0
-org.apache.geronimo.specs:geronimo-jcdi_1.1_spec:1.0
-# OSGI integration and dependencies
-org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
+org.apache.tamaya:tamaya-core:{tamaya_version}
 org.apache.tamaya.ext:tamaya-functions:{tamaya_version}
+org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
 -----------------------------------------------
 
 
-=== Usage
+=== How Tamaya deals with OSGI Specialities
 
-As an example, what is possible you can implement an OSGI service as a normal POJO and publish it as an OSGI service.
-Given that configuration can be injected very easily:
+Important to know is that within OSGI class- and resource loading is not compatible with standard Java SE. Also bundle can
+be loaded or unloaded at any time, so Tamaya's logic should not assume a stable non changing environment.
+These constraints are handled by Tamaya (implemented in +tamaya-core+ and +tamaya-psgi+) as follows:
 
-[source, java]
------------------------------------------------
-public class HelloServiceImpl implements HelloService{
+* Tamaya registers a +ServiceListener+ which reads all +java.util.ServiceLoader+ configurations and
+  registers them as OSGI services. Hereby integration is two-way: The core module contains an
+  OSGI +Activator+ that replaces the default +ServiceContext+ with an OSGI based +ServiceContext+ that
+  will consume all services through the OSGI service API. Consequently you can also register Tamaya extensions
+  as OSGI services yourself (e.g. your own +PropertySource+ instances).
+* Tamaya's +ServiceContext+ SPI does not only provide a facade to the OSGI service mechanism it also provides
+  an API for loading of (classpath) resources. In OSGI it delegates to the bundle's +getEntry(String)+ method.
 
-    @Config("example.message")
-    @ConfigDefault("A Tamaya default.")
-    private String message;
+Finally by adding Tamaya's OSGI integration module (+tamaya-osgi+) Tamaya replaces the existing OSGI +ConfigAdmin+ service
+with an istance based on Tamaya. Hereby Tamaya can use the existing +ConfigAdmin+ component as a fallback
+or override source (see configuration options explained later). This does not interfere with any existing
+injection mechanism already in place in your existing OSGI environment.
 
-    @Override
-    public String sayHello() {
-        System.err.println("HELLO: " + message);
-        return message;
-    }
-}
------------------------------------------------
 
+=== Configuring how Tamaya integrates with the existing ConfigAdmin service
+
+Tamaya provides several options that define how it combines it's values with the values provided
+from the additionally installed +ConfigAdmin+ service:
+
+* +org.tamaya.integration.osgi.cm.ranking+ (int) allows to configure the OSGI service ranking used by the Tamaya
+  +BundleActivator+ to register Tamaya's +ConfigAdmin+ service. In OSGI higher ranking precede lower rankings.
+  By default Tamaya's OSGI extending service registration mechanism is reusing any annotated +@Priority+ priority
+  values as corresponsing rankings.
+* +org.tamaya.integration.osgi.cm.override+ (boolean) allows to configure if Tamaya is overriding any existing
+  values from the default +ConfigAdmin+ instance, or only extending them. In other words this setting allows you to
+  define, which configuration subsystem has precedence for evaluating the final values, either Tamaya based
+  configuration (default) or the configuration mechanisms provided by default from your OSGI container (when this flag
+  is set to +false+).
+
+
+=== Mapping of pids and factoryPids
+
+When accessing configuration from the OSGI +ConfigAdmin+ a pid, or factoryPid is passed additionally to
+tell the configuration service, for which bundle configuration is requested. Tamaya, by default, maps
+the OSGI pid or factory pid to a corresponding root section in Tamaya's configuration:
 
-=== SPI
+[source, listing]
+.OSGI default pid mapping
+-----------------------------------------------
+# OSGI parameters
+pid=myBundle
+key=common.net.port
+
+# Tamaya key
+[myBundle]common.net.port
+-----------------------------------------------
 
-By default the OSGI pid or factory pid is mapped to a corresponding root section in Tamaya's configuration. We are
-well aware that this might not always be the desired approach. Therefore there as an SPI service provided that allows
-to determine this mapping:
+This mapping can be adapted if needed by implementing and registering the following OSGI service:
 
 [source, java]
 .OSGIConfigRootMapper
@@ -111,6 +106,47 @@ public interface OSGIConfigRootMapper {
 }
 -----------------------------------------------
 
-Registering your own implementation as an OSGI service allows you to redefine the key mapping.
-By default a configuration mapping for +pid/factoryPid==myBundle+ is mapped to +[bundle:myBundle]+.
-This mapping is used as a prefix when collecting the corresponding entries for the OSGI configuration.
+
+== Tamaya based Injection
+
+=== Overview
+
+OSGI itself already provides injection and configuration mechanism. Since Tamaya is working in the back
+you can continue to use the mechanism of your choice. Nevertheless Tamaya also supports enabling Tamaya
+specific configuration injection.
+
+
+=== Installation
+
+To benefit from Tamaya's injection mechanism in your OSGI services you need additionally to the basic
+OSGI support described earlier in this document:
+
+[source, listing]
+-----------------------------------------------
+org.apache.geronimo.specs:geronimo-atinject_1.0_spec:1.0
+org.apache.tamaya.ext:tamaya-inject-api:{tamaya_version}
+org.apache.tamaya.ext:tamaya-inject-se:{tamaya_version}
+org.apache.tamaya.ext:tamaya-inject-osgi:{tamaya_version}
+-----------------------------------------------
+
+
+=== Example
+
+As an example, what is possible you can implement and register an OSGI service and use Tamaya's injection
+API for configuring it:
+
+[source, java]
+-----------------------------------------------
+public class HelloServiceImpl implements HelloService{
+
+    @Config(value={"example.message"}, defaultValue="A Tamaya default.")
+    private String message;
+
+    @Override
+    public String sayHello() {
+        System.err.println("HELLO: " + message);
+        return message;
+    }
+}
+-----------------------------------------------
+