content/documentation/extensions/mod_osgi.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extensions: OSGi Integration

toc::[]


[[OSGi]]
== Tamaya OSGi Support

Tamaya _OSGi_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.


=== What functionality this module provides ?

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 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
* Apache Felix, version 5.6.1
* Eclipse Equinox, version x.x.x.


=== Installation

To benefit from Tamaya in an OSGi context you must deploy at least the following modules to
your OSGi runtime environment:

[source, listing, subs=attributes+]
-----------------------------------------------
# Runtime with OSGi ConfigAdmin support, e.g.
org.apache.felix:org.apache.felix.configadmin:{felix_version}
# API and core
org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0
org.apache.tamaya:tamaya-api:{tamaya_version}
org.apache.tamaya:tamaya-spisupport:{tamaya_version}
org.apache.tamaya:tamaya-core:{tamaya_version}
# Required extensions
org.apache.tamaya.ext:tamaya-functions:{tamaya_version}
org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
-----------------------------------------------


=== Tamaya Service Loading in OSGi

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 +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 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]:

[source, listing]
.OSGi pid mapping
-----------------------------------------------
# OSGi settings
pid=myBundle
key=common.net.port

# Corresponding key in Tamaya configuration
[myBundle]key=common.net.port
-----------------------------------------------

==== Enabling/Disabling Tamaya

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:

* 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:

* 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.


==== Controlling How Tamaya changes your OSGi Configuration

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.

==== 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
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):

[source, Java]
.OSGi ConfigHistory Entry
-----------------------------------------------
public final class ConfigHistory implements Serializable{

    [...]

    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) {...}

}
-----------------------------------------------

==== 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);
}
-----------------------------------------------


==== The Tamaya OSGi Configuration Service

Finally Tamaya also provides support for using Tamaya's injection API with your OSGi project. To enable injection
you must install a few additional bundles:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
   <groupId>org.apache.tamaya.ext</groupId>
   <artifactId>tamaya-osgi-injection</artifactId>
   <version>{tamaya_version}</version>
</dependency>
<dependency>
   <groupId>org.apache.tamaya.ext</groupId>
   <artifactId>tamaya-injection</artifactId>
   <version>{tamaya_version}</version>
</dependency>
<dependency>
   <groupId>org.apache.tamaya.ext</groupId>
   <artifactId>injection-api</artifactId>
   <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------

Given that you can inject configuration entries

* on your services by
  ** setting +tamaya-config-inject=true+ in your service properties.
  ** setting +Tamaya-Config-Inject: true+ in your bundle's manifest.
* or by using the registered +ConfigInjectionService+:

[source, java]
-----------------------------------------------
public interface ConfigInjectionService {
    /** The manifest entry to enable Tamaya injection. */
    String TAMAYA_INJECTION_ENABLED_MANIFEST = "Tamaya-Config-Inject";
    /** The OSGi config entry to enable Tamaya injection. */
    String TAMAYA_INJECTION_ENABLED_PROP = "tamaya-config-inject";

    /**
     * Checks if injection is enabled on the given service.
     * @param reference the service reference, not null.
     * @return true, if enjection is enabled.
     */
    boolean isInjectionEnabled(ServiceReference reference);

    /**
     * Checks if injection is enabled on the given service.
     * @param bundle the bundle, not null.
     * @return true, if enjection is enabled.
     */
    boolean isInjectionEnabled(Bundle bundle);

    /**
     * Configures the passed instance.
     * @param instance the instance, not null.
     * @param <T> the input and return type.
     * @param pid the target PID, not null.
     * @param location the optional location
     * @return the configured instance.
     */
    <T> T configure(String pid, String location, T instance);

    /**
     * Creates a suzpplier, which supplies events as created by the basic supplier, which are
     * automatically configured, when supplying.
     * @param supplier the base supplier, not null.
     * @param pid the target PID, not null.
     * @param location the optional location
     * @param <T> the type
     * @return a configuring supplier.
     */
    <T> Supplier<T> getConfiguredSupplier(String pid, String location, java.util.function.Supplier<T> supplier);

    /**
     * Creates a template implementing the annotated methods based on current configuration data.
     *
     * @param <T> the type of the template.
     * @param templateType the type of the template to be created.
     * @param pid the target PID, not null.
     * @param location the optional location
     * @return the configured template.
     */
    <T> T createTemplate(String pid, String location, Class<T> templateType);

    /**
     * Configures the passed instance.
     * @param instance the instance, not null.
     * @param <T> the input and return type.
     * @param bundle the target bundle, not null.
     * @return the configured instance.
     */
    <T> T configure(Bundle bundle, T instance);

    /**
     * Creates a supplier, which supplies events as created by the basic supplier, which are
     * automatically configured, when supplying.
     * @param supplier the base supplier, not null.
     * @param bundle the target bundle, not null.
     * @param <T> the type
     * @return a configuring supplier.
     */
    <T> Supplier<T> getConfiguredSupplier(Bundle bundle, java.util.function.Supplier<T> supplier);

    /**
     * Creates a template implementing the annotated methods based on current configuration data.
     *
     * @param <T> the type of the template.
     * @param templateType the type of the template to be created.
     * @param bundle the target bundle, not null.
     * @return the configured template.
     */
    <T> T createTemplate(Bundle bundle, Class<T> templateType);
}
-----------------------------------------------

NOTE: Injection hereby is based on the OSGi ConfigAdmin values only. To use Tamaya configuration you have to additionally
install the Tamaya common OSGi support as described in the previous sections.

More details on Tamaya's injection API can be found in the corresponding link:mod_injection.html[API documentation].

=== Special OSGi Platform support

==== 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_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 Tamaya.
| +++
<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 Tamaya 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 Tamaya 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+
| Show the 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>
+++

|=======

==== 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.