One aspect that was regularly asked for is working OSGI support. Unfortunately OSGI implements a rather different architecture, where also class and resource-loading does not work similarly as in plain Java. Also the ServiceLoader, which also is used by Tamaya doesn’t work in a plain vanilla OSGI container.
Good news is with the next release 0-4-incubating, Tamaya will come with a working OSGI support. This blog will give some details on the current state.
The features presented in this blog here have not yet been released.
You have to checkout and build locally all Tamaya code repositories:
- API & Core: https://github.com/apache/incubator-tamaya.git
- Extensions: https://github.com/apache/incubator-tamaya-extensions.git
- Sandbox: https://github.com/apache/incubator-tamaya-sandbox.git
Also be aware that the features presented are not yet releases, so you are welcome to give feedback or hints for improvement and also there might be still some minor changes until the final release.
Further you need:
- Java 8
- Maven 3+
- An Apache Karaf installation
Basically running Tamaya in Apache Karaf as of now requires a bit of extra work, since the latest release 0.3-incubating is not yet ready to be usable with OSGI, you have to build the current state from the current HEAD:
git clone https://github.com/apache/incubator-tamaya.git cd incubator-tamaya mvn install cd .. git clone https://github.com/apache/incubator-tamaya-extensions.git cd incubator-tamaya-extensions mvn install cd .. git clone https://github.com/apache/incubator-tamaya-sandbox.git cd incubator-tamaya-sandbox mvn install
Running Tamaya in Apache Karaf
Obviously you need then a working Karaf installation. You can download the current distribution from the Karaf Apache website.
Finally you can copy the build jars from code/api/target and code/core/target into Karaf’s deploy folder:
Now you ready to start the Karaf console. Executing bundle:list in the console you should see all bundles active:
Great! Tamaya is running in OSGI and can be used with it’s APIs. But how it relates to the existing OSGI ConfigurationAdmin service? Currently it does not relate or interfer in any way. But what if you want Tamaya to use for externalizing some of your OSGI configuration? This is where the Tamaya OSGI configuration plugin enters the game…
Tamaya OSGI Configuration Plugin
Tamaya comes with an OSGI specific extension, which integrates with the OSGI ConfigurationAdmin dynamic configuration service. To install the plugin you need the following Tamaya bundles:
- You should already have installed:
- From the extensions repository you need:
- And finally from the sandbox repository:
We will demonstrate a most features using Apache Karaf. The Karaf console commands used are defined in the sandbox repository as well.
After having successsfully installed all required bundles your setup should look similarly as follows:
Having installed the plugin and it’s dependencies you will get the following features:
- It allows to define configuration for OSGI PID identifier by adding configuration entries with a [PID] root section. E.g. the following configuration file would configure a OSGI component with PID a.b.MyComponent:
[a.b.MyComponent]service.logLevel=DEBUG [a.b.MyComponent]service.type=K8S [a.b.MyComponent]service.provider=kubecluster.mycompany.org [a.b.MyComponent]service.id=db-test01
- By default Tamaya actively writes to the default ConfigurationAdmin configurations. An OperationPolicy defines how Tamaya should handle existing configuration entries:
- EXTEND: Tamaya will add new configuration entries not existing in the OSGI configuration with Tamaya configuration, but will never override any existing entries.
- UPDATE_ONLY: Tamaya will override existing values, but will not add any new configuration entries.
- OVERRIDE: Tamaya will override and add values with matching values from the Tamaya configuration.
You can access and also edit the current policy using Tamya’s console commands:
- Additionally it is configurable if Tamaya should actively change any OSGI configuration (by default the feature is deactivated):
- Define a system property tamaya-enabled=true to enable Tamaya OSGI updates by default.
- Use standard OSGI configuration for PID TamayaConfigPlugin and add a property tamaya-enabled with value true/false (with a String typed value).
As you may expect you can also change the default enablement of Tamaya using the console:
As mentioned Tamaya does not interfer with OSGI configuration by default. Nevertheless you can also activate Tamaya selectively for each bundle by
- adding corresponding Manifest entries, or
- OSGI Configuration entries (which override manifest entries)
- tamaya-policy (Manifest: Tamaya-Policy) defines the Policy, how Tamaya overrides or extends existing OSGI configuration.
- tamaya-enabled (Manifest: Tamaya-Enabled) configures if Tamaya should actively change the bundle’s OSGI configuration.
- tamaya-config-root (Manifest: Tamaya-Config-Root) allows additionally to configure explicitly the “root section”,where Tamaya should lookup for corresponding Tamaya’s config entries.
All entries are optional. If not defined the global default settings were used. Summarizing, with the Tamaya ConfigurationPlugin:
- Tamaya allows you to externalize your OSGI configuration.
- You can selectively configure, which bundles should be affected.
- You can selectively configure, how Tamaya interacts with your OSGI configuration (Policy).
- You can configure Tamaya’s default properties with standard OSGI configuration using the PID TamayaConfigPlugin.
As before also the Tamaya default policy can be changed using the console:
Backup and Restore
Tamaya also provides some basic audit and restore features:
- When Tamaya overrides/changes the OSGI configuration for a PID it creates a Backup, which is stored in the plugin’s OSGI configuration.
- All Properties changed are logged in corresponding change events:
- for each single properties
- start and stop events for bundles
Given that you can list and reset changes done with Tamaya’s backup_restore functionality and get a detailed audit trace on the changes performed. If a backup has been restored Tamaya will also update the corresponding OSGI configuration for the given OSGI PID with tamaya-enabled=false to prevent Tamaya from changing the backup again, when the bundle is restarted.
You can get a list of all available backups using the Tamaya console commands:
Before we perform a restore, we will add an arbitrary entry “foo”, which then must disappear later:
Then we perform a restore for the configuration “profile” and will see that our changed entry “foo” is removed again:
Nevertheless there is one one additional entry that did not exist on the original configuration: tamaya-enabled = false. This prevents Tamaya from changing the OSGI configuration in the future again, when the according plugin is reloaded or updated. Of course you can enable Tamaya configuration for this plugin again by simply setting tamaya-enabled = true. When you remove the entry Tamaya will check for a corresponding manifest entry and finally fall back to its default enabled setting to decide, if the bundle should be managed by Tamaya regarding it’s configuration.
Configuration Change History
As mentioned Tamaya also stores a list of changes performed on a single property level. Also these changes can be accessed using console comands. E.g. below you can see the output, where a parameter “foo” has been added by Tamaya:
The history of changes can be filtererd also by the event type, so a list of all changed PIDs can easily extracted as follows:
Explicitly Applying Tamaya Configuration
Also it is possible to manually apply Tamaya configuration to OSGI configuration using the tamaya:tm_applyconfig command:
Given that we made try out a dry run on the profile configuration:
- We simulate a change in Tamaya, by adding an according system property. Since we know that the PID is used in brackets as a configuration entry prefix, we can addd the following system property:
- We then simulate the apply of the changed configuration using dryrun=true to see, if our change is as expected. As we can see the change would be included in the OSGI configuration as expected. We can now simply omit the dryrun parameter, which would apply the change to the OSGI configuration, resulting in a OSGI configuration change event, which may restart any affected bundles.
Getting Information about Tamaya
The shell commands also allow you to inspect Tamayas current setup:
- tamaya:tm_info provides you an overview of the current configuration setup:
- tamaya:tm:propertysource gives you detailed about the configuration values of a propertysource:
- tamaya:tm_propertysources print Tamaya’s propertysource chain, in order of precedence (most signifact last):
- Finally tamaya:tm_propertysource allows to inspect more details on single keys such as the property sources providing values etc.
Automatically update Configuration on Change Detection
How it works
Tamaya also supports updating the OSGI configuration automatically as soon as Tamaya configuration changes for componeent PID. This functionality builds on the solid fundamentals of further Tamaya modules:
- org.apache.tamaya.ext:tamaya-events monitors the current Tamaya configuration for changes and emits ConfigurationChange events to all listeners registered, when change has been detected.
- The Tamaya OSGI plugin already allows to apply for a new configuration (shown before in this blog).
- So the only thing to do is implement a configuration listener that will check for bundle related configuration changes (ones starting with [PID] entries) and triggering corresponding reloads, which in consequence triggers OSGI configuration events to be emitted.
- Obviously also here users may want to fine grained activate or deactivate this feature.
This is implemented by the Tamaya OSGI updater plugin.
The Tamaya Updater Plugin
To install you need the following additional bundles:
- org.apache.tamaya.ext:tamaya-osgi-updater:0.4-incubating-SNAPSHOT (sandbox repo)
- org.apache.tamaya.ext:tamaya-events:0.4-incubating-SNAPSHOT (extensions repo)
After successful installation your bundle list should looks similar to this:
Also this plugin does not do anything, by default. Monitoring on changes must be explicitly enabled by:
- Setting the following property in the TamayaConfigPlugin OSGI configuration: tamaya-update-enabled=true.
- Or using again the corresponding console commands:
After a few seconds the automatic update checks are running and, on change necessary configuration updates are triggered automatically.
To demonstrate this feature, we will start with configuration for the PID org.apache.tamaya.core (effectively it could be any PID). Using the Karaf console we can easily visualize the current configuration entries:
Now let’s define an additional system property foo111=bar111 for the PID org.apache.tamaya.core using standard Karaf console commands:
This will automatically trigger an update of the OSGI configuration for PID org.apache.tamaya.core with the new value added. To ensure, we will look at the logs, where we will find the following entry:
As expected a corresponding change event has been fired. Later in the log we will also see the key/values updated:
Finally we will see our change reflected in the OSGI configuration for the given PID:
It was a long journey to finally support OSGI with Tamaya. But this blog has shown it’s awesome potential:
- It can help OSGI to easily store relevant configuration also on arbitrary external locations.
- It can render any OSGI environment to automatically react on external configuration changes.
- It leverages the OSGI platform with new configuration functionalities and flexibility without interfering with existing OSGI standards or requiring any existing code to be changed to benefit from Tamaya’s flexibility.
Finally there is also a feature, which allows to use the Tamaya injection with OSGI. Hereby Tamaya is based on the current ConfigurationAdmin properties and only adds the injection features on top of. This feature will be shown, when we discuss Tamaya configuration injection in a later blog.