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 2016/12/26 08:52:03 UTC
incubator-tamaya-site git commit: TAMAYA-145: Updated OSGI
documentation.
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 <an...@apache.org>
Authored: Sun Dec 25 12:19:22 2016 +0100
Committer: anatole <an...@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;
+ }
+}
+-----------------------------------------------
+