Karaf configuration as Groovy file

Introduction

By deafault, Apache Karaf keeps configuration for bundles in the etc directory as flat properties files. We can override configuration for the storing mechanism by providing own implementation of the org.apache.felix.cm.PersistenceManager interface and use much more readable format for bundle properties, e. g. groovy config.

Turning off built-in Karaf persistence

As we can read in Karaf documentation:

Apache Karaf persists configuration using own persistence manager in case of when available persistence managers do not support that.

We will use our custom implementation of persistence, so Karaf persistence is not needed. We can turn it off by setting variable storage to an empty value:

$ cat etc/org.apache.karaf.config.cfg
storage=

This option is available since version 4.1.3 when this issue was resolved.

Registering custom Persistence Manager

First we have to create and register an OSGi service implementing org.apache.felix.cm.PersistenceManager. If we build and install the bundle with such service while Karaf is running (e.g. by putting jar in the deploy directory), then we should have at least two PersistenceManager services registered:

karaf@root()> ls org.apache.felix.cm.PersistenceManager
[org.apache.felix.cm.PersistenceManager]
----------------------------------------
 service.bundleid = 7
 service.description = Platform Filesystem Persistence Manager
 service.id = 14
 service.pid = org.apache.felix.cm.file.FilePersistenceManager
 service.ranking = -2147483648
 service.scope = singleton
 service.vendor = Apache Software Foundation
Provided by :
 Apache Felix Configuration Admin Service (7)
Used by:
 Apache Felix Configuration Admin Service (7)

[org.apache.felix.cm.PersistenceManager]
----------------------------------------
 osgi.service.blueprint.compname = groovyConfigPersistenceManager
 service.bundleid = 56
 service.id = 117
 service.pid = com.github.alien11689.osgi.util.groovyconfig.impl.GroovyConfigPersistenceManager
 service.ranking = 100
 service.scope = bundle
Provided by :
 groovy-config (56)
Used by:
 Apache Felix Configuration Admin Service (7)

Loaded configurations will be cached by configuration admin. We can use org.apache.felix.cm.NotCachablePersistenceManager interface if we want to implement custom caching strategy.

Creating a new properties file

Let's create a new properties file in groovy, e.g:

$ cat etc/com.github.alien11689.test1.groovy
a = '7'
b {
    c {
        d = 1
        e = 2
    }
    z = 9
}
x.y.z='test'

If we search for properties with pid com.github.alien11689.test1, Karaf will find these.

karaf@root()> config:list '(service.pid=com.github.alien11689.test1)'
----------------------------------------------------------------
Pid:            com.github.alien11689.test1
BundleLocation: null
Properties:
   a = 7
   b.c.d = 1
   b.c.e = 2
   b.z = 9
   service.pid = com.github.alien11689.test1
   x.y.z = test

If we make any change to the file they won't be mapped to properties, because there are no file watchers defined for it.
We could manage such properties using Karaf commands instead.

Managing configuration via Karaf commands

We can define a new pid using Karaf commands:

karaf@root()> config:property-set -p com.github.alien11689.test2 f.a 6
karaf@root()> config:property-set -p com.github.alien11689.test2 f.b 'test'

Since our PersistenceManager has higher service.ranking (100 > -2147483648), new pid will be stored as a groovy file:

$ cat etc/com.github.alien11689.test2.groovy
f {
    b='test'
    a='6'
}

We can also change/remove properties or remove the whole configuration pid using karaf commands and it will all be mapped to groovy configuration files.

Sources

Sources are available on github.

Using Kotlin extensions in Groovy

Extensions in Kotlin and Groovy

Kotlin and Groovy have mechanisms for extending existing classes without using inheritance or decorators. In both languages, the mechanisms are called extension methods. Their source code looks different, but generated bytecode is quite similar. Thanks to that, Groovy is able to use Kotlin extensions just like its own.

Why would I want to use such extensions in Groovy? The main reason is that I want to test my extensions using the best testing framework available for the JVM - Spock Framework.

Code is available here.

Extensions in Kotlin

There are many types of extensions in Kotlin. I decided to focus only on extension functions and properties.

As an example, I extend the java.lang.String class. First, I create an extension function skipFirst, which skips first N characters:

Next, I create an extension property answer, which is the Answer to the Ultimate Question of Life, the Universe, and Everything:

Both extensions are declared in package com.github.alien11689.extensions, in file called StringExtensions. However, the generated class in target directory is named StringExtensionsKt and this is the name that must be used when accessing from other languages. Specific class name can be forced by annotation @file:JvmName.

Using Kotlin extensions in Groovy

There are two ways for using extensions in Groovy that are supported by good IDEs. First, you can declare scope where the extensions are available by use method:

It is acceptable, but is not very convenient. The second and much better way is to use an extension module definition. The extension module is defined in file org.codehaus.groovy.runtime.ExtensionModule in directory src/main/resources/META-INF/services/. The same directory is monitored by ServiceLoader, but the file format is completely different:

The tests look much better now:

OSGi Blueprint visualization

What is blueprint?

Blueprint is a dependency injection framework for OSGi bundles. It could be written by hand or generated using Blueprint Maven Plugin. Blueprint file is only an XML describing beans, services and references. Each OSGi bundle could have one or more blueprint files.

Blueprint files represent architecture of our bundle. Let's visualize it using groovy script and graphviz available in my github repository and analyze.

Example generation

Pre: All you need is groovy and graphviz installed on your OS

I am working mostly with bundles with generated blueprint, so I will use blueprint file generated from Blueprint Maven Plugin tests as example. All examples are included in github repository.

Generation could be invoked by running run.sh script with given destination file prefix (png extension will be added to it) and path to blueprint file:

mkdir -p target

./run.sh target/fullBlueprint fullBlueprint.xml

Visualization is available here.

Separating domains

First if you look at the image, you see that some beans are grouped. You could easily extract such domains with tree roots: beanWithConfigurationProperties and beanWithCallbackMethods to separate blueprint files and bundles in future and generate images from them:

./run.sh target/beanWithCallbackMethods example/firstCut/beanWithCallbackMethods.xml
./run.sh target/beanWithConfigurationProperties example/firstCut/beanWithConfigurationProperties.xml
./run.sh target/otherStuff example/firstCut/otherStuff.xml

Now we have three, a bit cleaner, images: beanWithConfigurationProperties.png, beanWithCallbackMethods.png and otherStuff.png.

We also could generate image from more than one blueprint:

./run.sh target/joinFirstCut example/firstCut/otherStuff.xml example/firstCut/beanWithConfigurationProperties.xml example/firstCut/beanWithCallbackMethods.xml

And the result is here. The image contains beans grouped by file, but if you do not like it, you could force generation without such separation using option --no-group-by-file:

./run.sh target/joinFirstCutGrouped example/firstCut/otherStuff.xml example/firstCut/beanWithConfigurationProperties.xml example/firstCut/beanWithCallbackMethods.xml --no-group-by-file

It will generate image with all beans from all files.

Exclusion

Sometimes it is difficult to spot and extract other domains. It will be easier to do some experiments on blueprint. For example, bean my1 is a dependency for too many other beans. You could consider converting my1 bean to OSGi service and extracting it to another bundle.

Let's exclude my1 bean from generation via -e option and see what happens:

./run.sh target/otherStuffWithoutMy example/firstCut/otherStuff.xml -e my1

Result is available here. Now we see, that tree with root bean myFactoryBeanAsService could be separated and my1 could be inject to it as osgi service in another bundle.

You could exclude more than one bean adding -e switch for each of them, e. g. -e my1 -e m2 -e myBean123.

Conclusion

Blueprint is great for dependency injection for OSGi bundles, but it is easy to create quite big context containing many domains. It is much easier to recognize or search for such domains using blueprint visualizer script.

YOUR CODE HRER