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 <anat...@apache.org> Authored: Sun Dec 25 12:19:22 2016 +0100 Committer: anatole <anat...@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; + } +} +----------------------------------------------- +
