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-274 Added OSGI documentation.
Date Tue, 10 Oct 2017 22:41:41 GMT
Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master 3403800e8 -> 860152305


TAMAYA-274 Added 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/86015230
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/86015230
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/86015230

Branch: refs/heads/master
Commit: 860152305995d2c37f3f03f6d81189b7c55751e7
Parents: 3403800
Author: Anatole Tresch <anatole.tresch@trivadis.com>
Authored: Wed Oct 11 00:41:34 2017 +0200
Committer: Anatole Tresch <anatole.tresch@trivadis.com>
Committed: Wed Oct 11 00:41:34 2017 +0200

----------------------------------------------------------------------
 content/documentation/extensions/mod_osgi.adoc | 384 +++++++++++++++++---
 1 file changed, 333 insertions(+), 51 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/86015230/content/documentation/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_osgi.adoc b/content/documentation/extensions/mod_osgi.adoc
index 4392042..9059af6 100644
--- a/content/documentation/extensions/mod_osgi.adoc
+++ b/content/documentation/extensions/mod_osgi.adoc
@@ -1,7 +1,7 @@
 :jbake-type: page
 :jbake-status: published
 
-= Apache Tamaya - Extensions: OSGI Integrations
+= Apache Tamaya - Extensions: OSGI Integration
 
 toc::[]
 
@@ -14,20 +14,23 @@ Tamaya _OSGI_ is an extension module. Refer to the link:../extensions.html[exten
 
 === What functionality this module provides ?
 
-Tamaya _OSGI_ provides 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 instead.
+Tamaya _OSGI_ provides support for integration with OSGI. Hereby Tamaya does actively override
or extend the OSGI
++ConfigAdmin+ based configuration with entries stored and managed by Tamaya. Tamaya provides
also shell extensions
+to enable/perform configuration loading and restoring actions.
+Optionally Tamaya also provides extension for automatically trigger configuration updates,
when configuration has
+been changed and configuration injection using Tamaya's injection API.
 
 
 === Compatibility
 
-All module described are based on Java 7, so it will run on Java 7 and beyond.
+All module described are based on Java 8, so it will run on Java 8 and beyond.
 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 (tbc)
+* Apache Karaf, version 4.0.7
 * Apache Felix, version 5.6.1
-* tbd: Eclipse Equinox, version x.x.x.
+* Eclipse Equinox, version x.x.x.
+
 
 === Installation
 
@@ -48,74 +51,353 @@ org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
 -----------------------------------------------
 
 
-=== How Tamaya deals with OSGI Specialities
+=== Tamaya Service Loading in OSGI
 
-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:
+Important to know is that within OSGI class- and resource loading is not compatible with
standard Java SE. Also
+in OSGI, bundles can be loaded or unloaded at any time, so Tamaya's logic must cope with
this as well.
+These constraints are handled by Tamaya (implemented in +tamaya-core+ and +tamaya-osgi+)
as follows:
 
-* Tamaya registers a +ServiceListener+ which reads all +java.util.ServiceLoader+ configurations
and
+* Tamaya registers a +OSGIServiceContext+ 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.
+  OSGI +Activator+ that replaces Tamaya's default +ServiceContext+ with an OSGI based implementation
that
+  will consume all services from the OSGI service API. Consequently you can also register
Tamaya extensions
+  as OSGI services using standard OSGI tooling (e.g. your own +PropertySource+ instances).
Tamaya hereby
+  also does not store any service references, so the dynamic nature of OSGI is fully honored.
+* Tamaya's +ServiceContext+ SPI does additionally provide functionality for loading of (classpath)
+  resources using the bundle's +getEntry(String)+ method.
+* Tamaya similarly checks the classpath of all bundles for Tamaya SPI services to be registered
thus
+  implementing the +ServiceLoader+ logic in OSGI. Hereby Tamaya will only register services
with the
+  +org.apache.tamaya+ as root package.
+
+NOTE: Tamaya actually does not replace any existing +ConfigAdmin+ component, Tamaya modifies
any existing OSGI
+      configuration on changes detected and stores backups of any OSGI configuration before
applying any
+      changes.
+
+=== Configuring Bundles
+==== Mapping of pids and factoryPids
+
+When accessing configuration from the OSGI +ConfigAdmin+ a pid and an optional location can
be provided.
+Tamaya requires all configuration for a PID to be located in keys starting [PID]:
 
-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.
+[source, listing]
+.OSGI pid mapping
+-----------------------------------------------
+# OSGI settings
+pid=myBundle
+key=common.net.port
 
+# Corresponding key in Tamaya configuration
+[myBundle]key=common.net.port
+-----------------------------------------------
 
-=== Configuring how Tamaya integrates with the existing ConfigAdmin service
+==== Enabling/Disabling Tamaya
 
-Tamaya provides several options that define how it combines it's values with the values provided
-from the additionally installed +ConfigAdmin+ service:
+By default, Tamaya doesn't do anything, unless it is told to so so. So having installed the
Tamaya OSGI plugin,
+you will see the bundles are loaded, but your OSGI environment still works the same. This
is not accidentally, since
+configuration is a crucial part. This means Tamaya, by default, is disabled for all bundles.
You have now several
+options to enabled Tamaya:
 
-* +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+).
+* you can enable Tamaya for *all* bundles by default by
+  ** setting the +-Dtamaya-enabled=true+ system property.
+  ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the PID +TamayaConfigPlugin+.
+* you can enable Tamaya for a single bundle by
+  ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the given bundle.
+  ** by adding +Tamaya-Enabled: true+ to the bundle's MANIFEST.
 
+Similarly you can also combine these options the other way round:
 
-=== Mapping of pids and factoryPids
+* You can enable Tamaya by default as shown above.
+* You can disable Tamaya for bundles by
+  ** by setting +tamaya-enabled=false+ in the OSGI Configuration for the given bundle.
+  ** by adding +Tamaya-Enabled: false+ to the bundle's MANIFEST.
 
-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:
+==== Controlling How Tamaya changes your OSGI Configuration
 
-[source, listing]
-.OSGI default pid mapping
------------------------------------------------
-# OSGI parameters
-pid=myBundle
-key=common.net.port
+Tamaya supports different policies that define how Tamaya is changing the OSGI configuration:
+
+* *EXTEND*: Only add properties not existing in the OSGI configuration, but never override
+            or remove existing properties.
+* *OVERRIDE*: Override existing properties and also add new properties.
+* *UPDATE_ONLY*: Only override existing properties but do not add any properties.
+
+By default, Tamaya uses the _OVERRIDE_ policy. Also this policy can be configured in several
+ways and with different scopes:
+
+* You can define the _default_ policy applied, by
+  ** setting the +-Dtamaya-policy=POLICY+ system property.
+  ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the PID +TamayaConfigPlugin+.
+
+Hereby, _POLICY_ must be one of +OVERRIDE, EXTEND, UPDATE_ONLY+.
+
+* You can also configure the policy individually for a bundle by
+  ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the given bundle.
+  ** by adding +Tamaya-Policy: POLICY+ to the bundle's MANIFEST.
+
+==== OSGI Configuration Backup
+
+Before Tamaya changes any OSGI configuration it creates a _Backup_ of the existing OSGI
+configuration dictionary and stores it in serialized form in the plugin's OSGI configuration.
+This allows you to restore the original OSGI configuration in case of problems. Hereby Tamaya
+automatically sets the +tamaya-enabled=false+ property to disable Tamaya for the given
+configuration (bundle).
+
+The history can be accessed from the Tamaya Configuration Plugin Service
+(shown later).
+
+==== OSGI Configuration Change Log
+
+All changes applied by Tamaya are logged as well using
++ConfigHistory+ entry items. The history can be accessed from the Tamaya Configuration Plugin
Service
+(shown later):
 
-# Tamaya key
-[myBundle]common.net.port
+[source, Java]
+.OSGI ConfigHistory Entry
 -----------------------------------------------
+public final class ConfigHistory implements Serializable{
 
-This mapping can be adapted if needed by implementing and registering the following OSGI
service:
+    [...]
 
-[source, java]
-.OSGIConfigRootMapper
+    public enum TaskType{
+        PROPERTY,
+        BEGIN,
+        END,
+    }
+
+    // ***
+    // Entry = attributes
+    // ***
+
+    public TaskType getType(){...}
+
+    public String getPid() {... }
+
+    public Object getPreviousValue() {... }
+
+    public ConfigHistory setPreviousValue(Object previousValue) {... }
+
+    public Object getValue() {...}
+
+    public ConfigHistory setValue(Object value) {...}
+
+    public String getKey() {...}
+
+    public ConfigHistory setKey(String key) {...}
+
+}
 -----------------------------------------------
-public interface OSGIConfigRootMapper {
 
-    String getTamayaConfigRoot(String pid, String factoryPid);
+==== The Tamaya OSGI Configuration Service
+
+As mentioned Tamaya exposes it's OSGI functionality, allowing programmatic access to Tamaya
configuration
+logic with the +TamayaConfigService+ OSGI service:
+
+[source, Java]
+.The exposed +TamayaConfigService+
+-----------------------------------------------
+public interface TamayaConfigService{
+    /** The system/config property to set Tamaya's {@link Policy}. */
+    String TAMAYA_POLICY_PROP = "tamaya-policy";
+    /** The MANIFEST property to set Tamaya's {@link Policy}. */
+    String TAMAYA_POLICY_MANIFEST = "Tamaya-Policy";
+    /** The system/config property to define a customized Tamaya's configuration root, replacing
the {@code [PID]} default
+     * prefix used. */
+    String TAMAYA_CUSTOM_ROOT_PROP = "tamaya-config-root";
+    /** The MANIFEST property to define a customized Tamaya's configuration root, replacing
the {@code [PID]} default
+     * prefix used. */
+    String TAMAYA_CUSTOM_ROOT_MANIFEST = "Tamaya-Config-Root";
+    /** The system/config property to enable Tamaya. */
+    String TAMAYA_ENABLED_PROP = "tamaya-enabled";
+    /** The MANIFEST property to enable Tamaya. */
+    String TAMAYA_ENABLED_MANIFEST = "Tamaya-Enabled";
+    /** The system/config property to enable Tamaya automatic updates (requires Tamaya's
Updater plugin to be loaded as well). */
+    String TAMAYA_AUTO_UPDATE_ENABLED_PROP = "tamaya-update-enabled";
+    /** The MANIFEST property to enable Tamaya automatic updates (requires Tamaya's Updater
plugin to be loaded as well). */
+    String TAMAYA_AUTO_UPDATE_ENABLED_MANIFEST = "Tamaya-Update-Enabled";
+
+    /**
+     * Enables/disables automatic updates (requires Tamaya's Updater plugin to be loaded
as well).
+     * @param enabled set to true to enable updates.
+     */
+    void setAutoUpdateEnabled(boolean enabled);
+
+    /**
+     * Enables/disables Tamaya config by default.
+     * @param enabled set to true to enable Tamaya for all bundles by default.
+     */
+    void setTamayaEnabledByDefault(boolean enabled);
+
+    /**
+     * Get the flag, if Tamaya is enabled by default for all bundles.
+     * @return true if Tamaya is enabled.
+     */
+    boolean isTamayaEnabledByDefault();
+
+    /**
+     * Get the default policy Tamaya is using for adapting OSGI configuration.
+     * @return the default policy, never null.
+     */
+    Policy getDefaultPolicy();
+
+    /**
+     * Set the default policy Tamaya is using for adapting OSGI configuration.
+     * @param policy the policy, not null.
+     */
+    void setDefaultPolicy(Policy policy);
+
+    /**
+     * Updates the given OSGI configuration with Tamaya configuration.
+     * @param pid the target PID, not null.
+     * @return the new configuration.
+     */
+    Dictionary<String,Object> updateConfig(String pid);
+
+    /**
+     * Updates the given OSGI configuration with Tamaya configuration.
+     * @param pid the target PID, not null.
+     * @param dryRun if true, the changes will not be applied to the OSGI configuration.
+     * @return the configuration that would be applied, has been applied.
+     */
+    Dictionary<String,Object> updateConfig(String pid, boolean dryRun);
+
+    /**
+     * Updates the given OSGI configuration with Tamaya configuration.
+     * @param pid the target PID, not null.
+     * @param policy the updating policy to be used, by default.
+     * @param forcePolicy if set to true, the given policy will be used, even if an alternate
policy is configured
+     *                    for the given PID.
+     * @param dryRun if true, the changes will not be applied to the OSGI configuration.
+     * @return the configuration that would be applied, has been applied.
+     */
+    Dictionary<String,Object> updateConfig(String pid, Policy policy, boolean forcePolicy,
boolean dryRun);
+
+    /**
+     * Checks if a bundle is enabled for Tamaya configuration.
+     * @param bundle the bundle, not null.
+     * @return true, if the bundle is enabled.
+     */
+    boolean isBundleEnabled(Bundle bundle);
+
+    /**
+     * Get the flag if automatic updates for config changes are enabled.
+     * @return true, if automatic updates for config changes are enabled.
+     */
+    boolean isAutoUpdateEnabled();
+
+    /**
+     * Get the backup written for a PID.
+     * @param pid the pid, not null.
+     * @return the backup, or null, if no backup is present.
+     */
+    Dictionary<String,?> getBackup(String pid);
+
+    /**
+     * Get all current known PIDs for which backups are registered.
+     * @return all known PIDs for which backups are registered.
+     */
+    Set<String> getBackupPids();
+
+    /**
+     * Restores a backup, replacing the current OSGI configuration with the backup and
+     * disabling Tamaya for this PID.
+     * @param pid the PID, not null.
+     * @return true, if a backup has been restored successfully.
+     */
+    boolean restoreBackup(String pid);
+
+    /**
+     * Stores the current OSGI configuration as a backup (only if no backup is existing).
+     * @param pid the target PID, not null.
+     * @return true, if a backup has been stored successfully.
+     */
+    boolean createBackup(String pid);
+
+    /**
+     * Deletes a backup, if existing.
+     * @param pid the target PID, not null.
+     * @return true, if a backup has been restored successfully.
+     */
+    boolean deleteBackup(String pid);
+
+    /**
+     * Sets the maximum getHistory size.
+     * @param maxHistory the max getHistory size. {@code 0} disables the getHistory function.
+     */
+    void setMaxHistorySize(int maxHistory);
+
+    /**
+     * Get the max getHistory size.
+     * @return the max getHistory size. {@code 0} means the getHistory function is disabled.
+     */
+    int getMaxHistorySize();
+
+    /**
+     * Access the current (full) change getHistory.
+     * @return the current getHistory, never null.
+     */
+    List<ConfigHistory> getHistory();
+
+    /**
+     * Clears the getHistory.
+     */
+    void clearHistory();
+
+    /**
+     * Clears the getHistory for a PID.
+     * @param pid the target PID, not null.
+     */
+    void clearHistory(String pid);
+
+    /**
+     * Get the getHistory for a PID.
+     * @param pid the target PID, not null.
+     * @return the PID's getHistory, never null.
+     */
+    List<ConfigHistory> getHistory(String pid);
+
+    /**
+     * Access the current OSGI configuration for a PID.
+     * @param pid the target PID, not null.
+     * @param section a subsection to be filter (using startsWith).
+     * @return the (optionally filtered) OSGI configuration.
+     */
+    Dictionary<String,Object> getOSGIConfiguration(String pid, String section);
+
+    /**
+     * Checks if a backup exists.
+     * @param pid the target PID, not null.
+     * @return true, if a backup exists.
+     */
+    boolean containsBackup(String pid);
 }
 -----------------------------------------------
 
 
 === Special OSGI Platform support
 
-==== Apache Karaf
+==== Apache Karaf Shell
+
+Apache Tamaya provides a Karaf Shell Extension providing commands for performing several
actions related
+to Tamaya configuration. To use them, simply add the +org.apache.tamaya.ext:tamaya-osgi-karaf-shell+
bundle
+to your OSGI runtime. The extension will add the following commands to your Karaf conaole
(with prefix +tamaya+):
+
+[width="100%",frame="1",options="header",grid="all"]
+|=======
+|_Artifact_
+|_Description_
+|_Options_
+
+| +tm_info+
+| Gives an overview on the current loaded default configuration.
+| -
+
+| +tm_info+
+| Gives an overview on the current loaded default configuration.
+| -
+|=======
+
+tbd...
+
+==== Apache Karaf Ferature
 
 Apache Tamaya provides a Karaf feature with all required dependencies
 as +org.apache.tamaya.ext:tamaya-karaf-features:{tamaya-version}:features:xml+.


Mime
View raw message