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

Inconsistent Dependency Injection to domains with Grails

I've encountered strange behavior with a domain class in my project: services that should be injected were null. I've became suspicious as why is that? Services are injected properly in other domain classes so why this one is different?

Constructors experiment

I've created an experiment. I've created empty LibraryService that should be injected and Book domain class like this:

class Book {
    def libraryService

    String author
    String title
    int pageCount

    Book() {
        println("Finished constructor Book()")
    }

    Book(String author) {
        this()
        this.@author = author
        println("Finished constructor Book(String author)")
    }

    Book(String author, String title) {
        super()
        this.@author = author
        this.@title = title
        println("Finished constructor Book(String author, String title)")
    }

    Book(String author, String title, int pageCount) {
        this.@author = author
        this.@title = title
        this.@pageCount = pageCount
        println("Finished constructor Book(String author, String title, int pageCount)")
    }

    void logInjectedService() {
        println("    Service libraryService is injected? -> $libraryService")
    }
}
class LibraryService {
    def serviceMethod() {
    }
}

Book has 4 explicit constructors. I want to check which constructor is injecting dependecies. This is my method that constructs Book objects and I called it in controller: 

class BookController {
    def index() {
        constructAndExamineBooks()
    }

    static constructAndExamineBooks() {
        println("Started constructAndExamineBooks")
        Book book1 = new Book().logInjectedService()
        Book book2 = new Book("foo").logInjectedService()
        Book book3 = new Book("foo", 'bar').logInjectedService()
        Book book4 = new Book("foo", 'bar', 100).logInjectedService()
        Book book5 = new Book(author: "foo", title: 'bar')
        println("Finished constructor Book(Map params)")
        book5.logInjectedService()
    }
}

Analysis

Output looks like this:

Started constructAndExamineBooks
Finished constructor Book()
    Service libraryService is injected? -> eu.spoonman.refaktor.LibraryService@2affcce2
Finished constructor Book()
Finished constructor Book(String author)
    Service libraryService is injected? -> eu.spoonman.refaktor.LibraryService@2affcce2
Finished constructor Book(String author, String title)
    Service libraryService is injected? -> null
Finished constructor Book(String author, String title, int pageCount)
    Service libraryService is injected? -> null
Finished constructor Book()
Finished constructor Book(Map params)
    Service libraryService is injected? -> eu.spoonman.refaktor.LibraryService@2affcce2

What do we see?

  1. ✔

    Empty constructor injects dependencies.

  2. ✔

    Constructor that invokes empty constructor explicitly injects dependencies.

  3. ✘

    Constructor that invokes parent's constructor explicitly does not inject dependencies.

  4. ✘

    Constructor without any explicit call declared does not call empty constructor thus it does not inject dependencies.

  5. ✔

    Constructor provied by Grails with a map as a parameter invokes empty constructor and injects dependencies.

Conclusion

Always explicitily invoke empty constructor in your Grail domain classes to ensure Dependency Injection! I didn't know until today either!