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.

You May Also Like

[:en] Operational problems with Zookeeper

This post is a summary of what has been presented by Kathleen Ting on StrangeLoop conference. You can watch the original here: http://www.infoq.com/presentations/Misconfiguration-ZooKeeper I've decided to put this selection here for quick reference. ...This post is a summary of what has been presented by Kathleen Ting on StrangeLoop conference. You can watch the original here: http://www.infoq.com/presentations/Misconfiguration-ZooKeeper I've decided to put this selection here for quick reference. ...

Need to make a quick json fixes – JSONPath for rescue

From time to time I have a need to do some fixes in my json data. In a world of flat files I do this with grep/sed/awk tool chain. How to handle it for JSON? Searching for a solution I came across the JSONPath. It quite mature tool (from 2007) but I haven't hear about it so I decided to share my experience with others.

First of all you can try it without pain online: http://jsonpath.curiousconcept.com/. Full syntax is described at http://goessner.net/articles/JsonPath/



But also you can download python binding and run it from command line:
$ sudo apt-get install python-jsonpath-rw
$ sudo apt-get install python-setuptools
$ sudo easy_install -U jsonpath

After that you can use inside python or with simple cli wrapper:
#!/usr/bin/python
import sys, json, jsonpath

path = sys.argv[
1]

result = jsonpath.jsonpath(json.load(sys.stdin), path)
print json.dumps(result, indent=2)

… you can use it in your shell e.g. for json:
{
"store": {
"book": [
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{
"category": "fiction",
"author": "Evelyn Waugh",
"title": "Sword of Honour",
"price": 12.99
},
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fiction",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
}
}

You can print only book nodes with price lower than 10 by:
$ jsonpath '$..book[?(@.price 

Result:
[
{
"category": "reference",
"price": 8.95,
"title": "Sayings of the Century",
"author": "Nigel Rees"
},
{
"category": "fiction",
"price": 8.99,
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"author": "Herman Melville"
}
]

Have a nice JSON hacking!From time to time I have a need to do some fixes in my json data. In a world of flat files I do this with grep/sed/awk tool chain. How to handle it for JSON? Searching for a solution I came across the JSONPath. It quite mature tool (from 2007) but I haven't hear about it so I decided to share my experience with others.