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: TAMAYA-145: Updated OSGI documentation.
Date Mon, 26 Dec 2016 08:52:03 GMT
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;
+    }
+}
+-----------------------------------------------
+


Mime
View raw message