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 2017/10/13 22:51:34 UTC
incubator-tamaya-site git commit: TAMAYA-300 Added OSGI docu.
Repository: incubator-tamaya-site
Updated Branches:
refs/heads/master 860152305 -> 8d151f359
TAMAYA-300 Added OSGI docu.
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/8d151f35
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/8d151f35
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/8d151f35
Branch: refs/heads/master
Commit: 8d151f35905e7f13109b8a3d96554323b5e70cba
Parents: 8601523
Author: Anatole Tresch <an...@trivadis.com>
Authored: Sat Oct 14 00:51:23 2017 +0200
Committer: Anatole Tresch <an...@trivadis.com>
Committed: Sat Oct 14 00:51:23 2017 +0200
----------------------------------------------------------------------
content/documentation/extensions/mod_osgi.adoc | 310 +++++++++++++++++++-
1 file changed, 300 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8d151f35/content/documentation/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_osgi.adoc b/content/documentation/extensions/mod_osgi.adoc
index 9059af6..111c890 100644
--- a/content/documentation/extensions/mod_osgi.adoc
+++ b/content/documentation/extensions/mod_osgi.adoc
@@ -111,6 +111,7 @@ Similarly you can also combine these options the other way round:
** by setting +tamaya-enabled=false+ in the OSGI Configuration for the given bundle.
** by adding +Tamaya-Enabled: false+ to the bundle's MANIFEST.
+
==== Controlling How Tamaya changes your OSGI Configuration
Tamaya supports different policies that define how Tamaya is changing the OSGI configuration:
@@ -133,6 +134,60 @@ Hereby, _POLICY_ must be one of +OVERRIDE, EXTEND, UPDATE_ONLY+.
** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the given bundle.
** by adding +Tamaya-Policy: POLICY+ to the bundle's MANIFEST.
+==== Mapping OSGI PIDs to Tamaya Configuration
+
+Tamaya configuration is a single +Map<String,String> with String keys and String values. Whereas OSGI configuration are
+multiple +Dictionary<String,?>+ (for several PIDs). The Tamaya OSGI extension implements the following mapping:
+
+As an example refer to the followinf Tamaya configuration entries:
+
+[source, listing]
+.Tamaya configuration for PID 'MyPlugin'
+-----------------------------------------------
+[MyPlugin]ch.base.pack.Main.customer=Native Inc
+[MyPlugin]ch.base.pack.Main.use=234
+[MyPlugin]ch.base.pack.Main.encoding=UTF-8
+-----------------------------------------------
+
+The OSGI Configuration Plugin now provides the following configuration for PID:
+
+[source, listing]
+.OSGI configuration for PID 'MyPlugin'
+-----------------------------------------------
+ch.base.pack.Main.use=100 (Integer)
+ch.base.pack.Main.switch=on (Boolean)
+ch.base.pack.Main.customer=NONE (String)
+-----------------------------------------------
+
+Now using +Policy.OVERRIDE+ (as desribed in the previous section), Tamaya will change the OSGI configuration
+as follows:
+
+[source, listing]
+.OSGI configuration after Tamaya update for PID 'MyPlugin'
+-----------------------------------------------
+ch.base.pack.Main.use=234 (Integer)
+ch.base.pack.Main.switch=on (Boolean)
+ch.base.pack.Main.customer=Native Inc (String)
+[MyPlugin]ch.base.pack.Main.encoding=UTF-8 (String)
+-----------------------------------------------
+
+So Tamaya configuration mapping can be summarized as follows:
+
+* The OSGI PID is mapped to a Tamaya prefix +[PID]+.
+* The OSGI keys are the exact same keys as from Tamaya with the _[PID]_ prefix removed.
+* New entries are added (depending on the +Policy+) as +String+ values.
+* Types of existing entries are preserved on update (this requires the Tamaya entries to be convertable into
+ the required target types. Refer to Tamaya's core documentation for supported types and how
+ to add custom converters).
+
+Finally, the mapping of the OSGI _PID_ to the Tamaya _[PID]_ prefix also can be customized by
+
+* adding +tamaya-config-root+ as an OSGI configuration property to the OSGI configuration.
+* adding +Tamaya-Config-Root+ as a MANIFEST entry to the bundle.
+
+The root will replace the default _[PID]_ prefix with the value configured.
+
+
==== OSGI Configuration Backup
Before Tamaya changes any OSGI configuration it creates a _Backup_ of the existing OSGI
@@ -382,22 +437,257 @@ to your OSGI runtime. The extension will add the following commands to your Kara
[width="100%",frame="1",options="header",grid="all"]
|=======
-|_Artifact_
-|_Description_
-|_Options_
+|_Artifact_ |_Description_ |_Options_
+
+| +tm_apply_config+
+| Show the current Tamaya configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_apply_config [options] pid
+<b>ARGUMENTS</b>
+<i>pid</i> The target OSGI component PID.
+<b>OPTIONS</b>
+<i>operationMode, -m, --opmode</i> Explicitly set (override) the operation mode to use.
+<i>dryRun, -d, --dryrun</i> If set to true no OSGI configuration gets changed.
+</pre>
++++
+
+| +tm_backup_create+
+| Creates a backup of a current OSGI configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_backup_create [options] pid
+<b>ARGUMENTS</b>
+<i>pid</i> The target pid to backup.
+<b>OPTIONS</b>
+<i>--force, -f</i> Forces to (over)write a backup, even if one already exists.
+</pre>
++++
+
+| +tm_backup_delete+
+| Deletes the OSGI configuration backup of Tamya.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_backup_delete pid
+<b>ARGUMENTS</b>
+<i>pid</i> Allows to filter on the given PID. '*' removes all backups.
+</pre>
++++
+
+| +tm_backup_list+
+| List the backed-up OSGI configuration before Tamya applied changes.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_backup_list [pid]
+<b>ARGUMENTS</b>
+<i>pid</i> Allows to filter on the given PID.
+</pre>
++++
+
+| +tm_backup_restore+
+| Restores the OSGI configuration backup of Tamya and disabled the PID for Tamaya configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_backup_restore pid
+<b>ARGUMENTS</b>
+<i>pid</i> The target PID. '*' restores all backups.
+</pre>
++++
+
+| +tm_config+
+| Show the current Tamaya configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_config [options]
+<b>OPTIONS</b>
+<i>pi, -p, --pid</i> Apply filtering for the given OSGI component PID.
+<i>section, -s, --section</i> A starting expression selecting the section to be filtered.
+</pre>
++++
+
+| +tm_enable+
+| Enables or disable Tamaya by default for all bundles/services (default: enabled=false). Disabling still allows to explicitly enable
+ bundles using 'tamaya-enable' manifest or OSGI config entries.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_enable enabled
+<b>ARGUMENTS</b>
+<i>enabled</i> The boolean value to enabled/disable Tamaya by default.
+</pre>
++++
+
+| +tm_enabled+
+| Check if Tamaya is currently by default enabled for all bundles/services (default: enabled=false). If disabled still Tamaya allows to
+ explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_enabled
+</pre>
++++
+
+| +tm_history+
+| Gets the getHistory of changes Tamaya applied to the OSGI configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_history [options] [pid]
+<b>ARGUMENTS</b>
+<i>pid</i> Allows to filter on the given PID.
+<i>--type, -t</i> Allows to filter the events types shown.
+</pre>
++++
+
+| +tm_history_delete+
+| Deletes the getHistory of changes Tamaya applied to the OSGI configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_history_delete pid
+<b>ARGUMENTS</b>
+<i>pid</i> Allows to filter on the given PID.
+</pre>
++++
+
+| +tm_history_delete_all+
+| Deletes the full getHistory of changes Tamaya applied to the OSGI configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_history_delete_all
+</pre>
++++
+
+
+| +tm_history_maxsize+
+| Gets the maximal size of stored getHistory entries.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_history_maxsize
+</pre>
++++
+
+| +tm_history_maxsize_set+
+| Sets the maximal size of Tamaya getHistory entries.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_history_maxsize_set size
+<b>ARGUMENTS</b>
+<i>size</i>: The maximum number of entries in the getHistory.
++++
| +tm_info+
-| Gives an overview on the current loaded default configuration.
-| -
+| Show he current Tamaya status.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_info
+</pre>
++++
+
+| +tm_osgi_config+
+| Show the current OSGI configuration.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_osgi_config [options] pid
+<b>ARGUMENTS</b>
+<i>pid</i> The target OSGI component PID.
+<b>OPTIONS</b>
+<i>section, -s, --section</i>: A starting expression selecting the keys to be filtered.
+</pre>
++++
+
+| +tm_policy+
+| Get the current Tamaya overriding policy.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_policy
+</pre>
++++
+
+| +tm_policy_set+
+| Sets the current Tamaya operation policy.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_policy_set tm_policy_set
+<b>ARGUMENTS</b>
+<i>tm_policy_set</i>: The operation policy how Tamaya intercepts OSGI configuration.
++++
+
+| +tm_propagate_updates+
+| Flag if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.
+| +++
+<pre>
+<b>SYNTAX</b>
+tm_propagate_updates
++++
+
+| +tm_propagate_updates_set+
+| Configure if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_propagate_updates_set enabled
+<b>ARGUMENTS</b>
+<i>enabled</i>: Set to true to enable Tamaya's updating trigger.
+</pre>
++++
+
+| +tm_property+
+| Get a Tamaya property.
+| +++
+<pre><b>SYNTAX</b>
+tamaya:tm_property [options] [key]
+<b>ARGUMENTS</b>
+<i>key</i>: The target property source id.
+<b>OPTIONS</b>
+<i>extended,e</i>: Also print extended property value attributes.
+<i>propertysource, ps</i>: The target property source id.
+</pre>
++++
+
+| +tm_propertysource+
+| Show the current Tamaya entries of a propertysource.
+| +++
+<pre><b>SYNTAX</b>
+tamaya:tm_propertysource [propertysource]
+<b>ARGUMENTS</b>
+<i>propertysource</i>: The target property source id.
++++
+
+| +tm_propertysources+
+| Get a list of currently registered propertysources.
+| +++
+<pre>
+<b>SYNTAX</b>
+tamaya:tm_propertysources
+</pre>
++++
-| +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+.
+
+
+
+==== Apache Felix Gogo Console
+
+Apache Tamaya also provides the same commands as described for _Karaf_, but executable in
+plaing Gogo console as used by Apache Felix and Equinox as
++org.apache.tamaya.ext:tamaya-gogo-shell:{tamaya-version}+. Refer to the previous sections for
+a detailed command description.
\ No newline at end of file