DDevelopment & Design

Tired of exporting your OSGI metatype to client manually?

Feel my pain

We use OSGi, but we don’t deploy our bundles further than testing environment. It is our client who deploys it to production. However, they rarely read the metatypes – as metatype files are hidden deep inside jars and their format is not very user-friendly (who wants to read XMLs?). This is why they don’t know how to configure the application.

Sharing metatypes

If you work with OSGi metatype files, you have to find some way of informing your client what configuration is necessary for your application. There are a few ways of sharing this information:

  • You can send configuration options by e-mail or Jira/Redmine/(paste your issue tracker here). However, this might cause a big mess, searching is horrible, and it becomes outdated faster than you can say I hate sending metatypes.
  • You can share your repository with the client so that they always have up-to-date XMLs. Nevertheless, XML files are difficult to read and are scattered across whole modules.
  • You can keep your configuration in some document (e.g. Markdown), providing easy access for the client, but you must remember to synchronize it every time you change metatype.

metatype-exporter-maven-plugin to the rescue!

Our new Maven plugin allows us to automatically generate Markdown file from metatype files. Just add the plugin and enjoy automatically generated configuration created without any effort. Sample configuration may look like below.

<project ...>

    ...

    <pluginRepositories>
        <pluginRepository>
            <id>touk</id>
            <url>https://philanthropist.touk.pl/nexus/content/repositories/releases</url>
            <!-- we are not on central, but we are going to be there soon -->
        </pluginRepository>
    </pluginRepositories>
    <build>
        <plugins>
            <plugin>
                <groupId>pl.touk.osgi</groupId>
                <artifactId>metatype-exporter-maven-plugin</artifactId>
                <version>@metatype-exporter-maven-plugin.version@</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>export</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <destination>${project.build.directory}/classes/documentation</destination>
                    <outputFileName>ConfigurationDescription.md</outputFileName>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

 

Markdown produced by this configuration may look like this:

# Properties name (theseAreProperties) for pid this.is.first.pid

Description goes here

| ID  | Name  | Required | Type    | Default value | Options                         | Description |
| --- | ----- | -------- | ------- | ------------- | ------------------------------- | ----------- |
| id1 | name1 | Yes      | String  |               |                                 | desc1       |
| id2 |       | No       | Long    | 123           |                                 | desc2       |
| id3 |       | Yes      | Integer |               | <ul><li>15</li><li>30</li></ul> |             |

# Properties name (secondProps) for pid this.is.second.pid

| ID  | Required | Type   |
| --- | -------- | ------ |
| id1 | Yes      | String |

Markdown files are great because many git repositories like Gitlab or Github render Markdown files nicely. You can view the above file here: https://gist.github.com/piotrekfus91/ba36404341664c48df19576350a2340f.

Definitely more readable, huh?

Change language if your client doesn’t speak English

If you want to change the language of generated files, just add a resource bundle named MarkdownBundle, change locale in plugin configuration and enjoy your custom language. English and Polish are available out of the box.

<project ...>

    ...

    <build>
        <plugins>
            <plugin>
                <groupId>pl.touk.osgi</groupId>
                <artifactId>metatype-exporter-maven-plugin</artifactId>
                <version>@metatype-exporter-maven-plugin.version@</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>export</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <language>de</language>
                    <country>DE</country>
                </configuration>
                <depenedencies>
                    <dependency>
                        <!-- maven coordinates of the jar with resource bundle -->
                    </dependency>
                <depenedencies>
            </plugin>
        </plugins>
    </build>
</project>

Resource bundle (for example MarkdownBundle_de.properties)

forPid=...
attributeHeaderId=...
attributeHeaderName=...
attributeHeaderDescription=...
attributeHeaderOptions=...
attributeHeaderType=...
attributeHeaderDefaultValue=...
attributeHeaderRequired=...
attributeRequiredTrue=...
attributeRequiredFalse=...

Summary

Our problem – client doesn’t know how to configure the application – was solved with our new Maven plugin. The sources may be found on https://github.com/TouK/metatype-exporter-maven-plugin.

What’s next?

We are planning to add other output formats or enable users to provide custom templates. If you have any suggestions for enhancements or found a bug, just let us know in a Github issue.

— Previous article

Using Kotlin extensions in Groovy

Next article —

Gerrit notifications via Rocket.Chat

You May Also Like
DDevelopment & Design

Spock, Java and Maven

Few months ago I've came across Groovy - powerful language for JVM platform which combines the power of Java with abilities typical for scripting languages (dynamic typing, metaprogramming).

Together with Groovy I've discovered spock framework (https://code.google.com/p/spock/) - specification framework for Groovy (of course you can test Java classes too!). But spock is not only test/specification framework - it also contains powerful mocking tools.

Even though spock is dedicated for Groovy there is no problem with using it for Java classes tests. In this post I'm going to describe how to configure Maven project to build and run spock specifications together with traditional JUnit tests.


Firstly, we need to prepare pom.xml and add necessary dependencies and plugins.

Two obligatory libraries are:
<dependency>
    <groupid>org.spockframework</groupId>
    <artifactid>spock-core</artifactId>
    <version>0.7-groovy-2.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupid>org.codehaus.groovy</groupId>
    <artifactid>groovy-all</artifactId>
    <version>${groovy.version}</version>
    <scope>test</scope>
</dependency>
Where groovy.version is property defined in pom.xml for more convenient use and easy version change, just like this: 
<properties>
    <gmaven-plugin.version>1.4</gmaven-plugin.version>
    <groovy.version>2.1.5</groovy.version>
</properties>

I've added property for gmaven-plugin version for the same reason ;)

Besides these two dependencies, we can use few additional ones providing extra functionality:
  • cglib - for class mocking
  • objenesis - enables mocking classes without default constructor
To add them to the project put these lines in <dependencies> section of pom.xml:
<dependency>
    <groupid>cglib</groupId>
    <artifactid>cglib-nodep</artifactId>
    <version>3.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupid>org.objenesis</groupId>
    <artifactid>objenesis</artifactId>
    <version>1.3</version>
    <scope>test</scope>
</dependency>

And that's all for dependencies section. Now we will focus on plugins necessary to compile Groovy classes. We need to add gmaven-plugin with gmaven-runtime-2.0 dependency in plugins section:
<plugin>
    <groupid>org.codehaus.gmaven</groupId>
    <artifactid>gmaven-plugin</artifactId>
    <version>${gmaven-plugin.version}</version>
    <configuration>
        <providerselection>2.0</providerSelection>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>compile</goal>
                <goal>testCompile</goal>
            </goals>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupid>org.codehaus.gmaven.runtime</groupId>
            <artifactid>gmaven-runtime-2.0</artifactId>
            <version>${gmaven-plugin.version}</version>
            <exclusions>
                <exclusion>
                    <groupid>org.codehaus.groovy</groupId>
                    <artifactid>groovy-all</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupid>org.codehaus.groovy</groupId>
            <artifactid>groovy-all</artifactId>
            <version>${groovy.version}</version>
        </dependency>
    </dependencies>
</plugin>

With these configuration we can use spock and write our first specifications. But there is one issue: default settings for maven-surefire plugin demand that test classes must end with "..Test" postfix, which is ok when we want to use such naming scheme for our spock tests. But if we want to name them like CommentSpec.groovy or whatever with "..Spec" ending (what in my opinion is much more readable) we need to make little change in surefire plugin configuration:
<plugin>
    <groupid>org.apache.maven.plugins</groupId>
    <artifactid>maven-surefire-plugin</artifactId>
    <version>2.15</version>
    <configuration>
        <includes>
            <include>**/*Test.java</include>
            <include>**/*Spec.java</include>
        </includes>
    </configuration>
</plugin>

As you can see there is a little trick ;) We add include directive for standard Java JUnit test ending with "..Test" postfix, but there is also an entry for spock test ending with "..Spec". And there is a trick: we must write "**/*Spec.java", not "**/*Spec.groovy", otherwise Maven will not run spock tests (which is strange and I've spent some time to figure out why Maven can't run my specs).

Little update: instead of "*.java" postfix for both types of tests we can write "*.class" what is in my opinion more readable and clean:
<include>**/*Test.class</include>
<include>**/*Spec.class</include>
(thanks to Tomek Pęksa for pointing this out!)

With such configuration, we can write either traditional JUnit test and put them in src/test/java directory or groovy spock specifications and place them in src/test/groovy. And both will work together just fine :) In one of my next posts I'll write something about using spock and its mocking abilities in practice, so stay in tune.