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/08 17:00:34 UTC
incubator-tamaya git commit: TAMAYA-129: OSGI Support: Added
documentation.
Repository: incubator-tamaya
Updated Branches:
refs/heads/master 062109a95 -> 8799b3448
TAMAYA-129: OSGI Support: Added 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/8799b344
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/8799b344
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/8799b344
Branch: refs/heads/master
Commit: 8799b3448ee9be21dd622d631a326df3f74139d9
Parents: 062109a
Author: anatole <an...@apache.org>
Authored: Tue Dec 8 16:59:56 2015 +0100
Committer: anatole <an...@apache.org>
Committed: Tue Dec 8 16:59:56 2015 +0100
----------------------------------------------------------------------
src/site/asciidoc/extensions/index.adoc | 16 ++--
src/site/asciidoc/extensions/mod_osgi.adoc | 105 ++++++++++++++++++++----
2 files changed, 96 insertions(+), 25 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8799b344/src/site/asciidoc/extensions/index.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/index.adoc b/src/site/asciidoc/extensions/index.adoc
index 4498a9c..87d8df7 100644
--- a/src/site/asciidoc/extensions/index.adoc
+++ b/src/site/asciidoc/extensions/index.adoc
@@ -42,6 +42,12 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati
|=======
|_Artifact_ |_Description_ |_Links_
| | N/A: currently no extensions have reached that maturity level. | -
+|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:mod_resolver.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:mod_formats.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:mod_functions.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:mod_optional.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:mod_spi-support.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:modjson.html[Documentation]
|=======
@@ -57,19 +63,13 @@ NOTE All extensions currently run on Java 7 as well as on Java 8.
|_Artifact_ |_Description_ |_Links_
|+org.apache.tamaya.ext:tamaya-builder+ |Provides a fluent-style builder for configurations | link:mod_builder.html[Documentation]
|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:mod_resources.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:mod_resolver.html[Documentation]
|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:mod_events.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:mod_formats.html[Documentation]
|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:mod_injection.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:modjson.html[Documentation]
|+org.apache.tamaya.ext:tamaya-model+ |Provides support documenting ang validating configuration during runtime. |link:mod_model.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:mod_functions.html[Documentation]
|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:mod_management.html[Documentation]
|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:mod_remote.html[Documentation]
|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a http service. |link:mod_server.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:mod_optional.html[Documentation]
|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:mod_classloader_support.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:mod_spi-support.html[Documentation]
|=======
== Integrations
@@ -83,6 +83,7 @@ from a sledgehammer to a scalpell:
|+org.apache.tamaya.ext:tamaya-cdi+ | Java EE/standalone compliant CDI integration | link:mod_cdi.html[Documentation]
|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:mod_camel.html[Documentation]
|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:mod_spring.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:mod_osgi.html[Documentation]
|=======
@@ -109,9 +110,6 @@ very carefully and especially give us feedback, so we can improve them before pr
[width="100%",frame="1",options="header",grid="all"]
|=======
|_Artifact_ |_Description_ |_Links_
-|+org.apache.tamaya.ext:tamaya-osgi-felix+ |Provides support for Apache Felix PersistenceManager SPI. | -
-|+org.apache.tamaya.ext:tamaya-osgi-general+ |Provides support for implementing the OSGI ConfigAdmin service. | -
-|+org.apache.tamaya.ext:tamaya-osgi-injection+ |Provides support for configuration injection into services. | -
|+org.apache.tamaya.ext:tamaya-store+ |SPI for writing configuration. | -
|+org.apache.tamaya.ext:tamaya-store-file+ |Store SPI implementation using file storage. | -
|+org.apache.tamaya.ext:tamaya-store-hazelcast+ |Store SPI implementation using a Hazelcast Datagrid. | -
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8799b344/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
index 8f906d4..7244ea8 100644
--- a/src/site/asciidoc/extensions/mod_osgi.adoc
+++ b/src/site/asciidoc/extensions/mod_osgi.adoc
@@ -53,26 +53,99 @@ an OSGI context:
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
+ ** 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 _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.
+. 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.
=== Compatibility
-All module described are based on Java 7, so it will not run on Java 7 and beyond.
-TBD: OSGI version required.
+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.
+
+
+=== Installation
+
+To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime
+environment:
+
+[source, listing]
+-----------------------------------------------
+# API and core
+org.apache.tamaya:tamaya-api:{tamayaVersion}
+org.apache.tamaya:tamaya-core:{tamayaVersion}
+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:{tamayaVersion}
+org.apache.tamaya.ext:tamaya-injection:{tamayaVersion}
+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:{tamayaVersion}
+org.apache.tamaya.ext:tamaya-functions:{tamayaVersion}
+-----------------------------------------------
+
+
+=== Usage
+
+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:
+
+[source, java]
+-----------------------------------------------
+public class HelloServiceImpl implements HelloService{
+
+ @Config("example.message")
+ @ConfigDefault("A Tamaya default.")
+ private String message;
+
+ @Override
+ public String sayHello() {
+ System.err.println("HELLO: " + message);
+ return message;
+ }
+}
+-----------------------------------------------
+
+
+=== SPI
+
+By defauklt 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:
+
+[source, java]
+.OSGIConfigRootMapper
+-----------------------------------------------
+public interface OSGIConfigRootMapper {
+ String getTamayaConfigRoot(String pid, String factoryPid);
+}
+-----------------------------------------------
+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.