How Apache Johnzon makes JSONP/JSONB a real option for configuration

In an older post I explained how to use JSON-P and Johzon proprietary mapper to bind configuration files on java code. Since this post was published, JSON-B was released and Johnzon implementation as well. Therefore here is the update explaining how to keep the configuration file oriented.

The main difference between a machine configuration file which is pretty close to a webservice in terms of 'aspect' since the configuration file is generated but will never be read by a human, and an user oriented configuration file - read by a human, is concentrated in three points the first configuration does not have to meet whereas the last one must have it:

1. It must be readable so text/string based (XML, JSON, INI, properties matching this rule),
2. It must be formatted - not inlined - to keep the readability point,
3. It must enable to use comments.

As explained in the post mentionned at the beginning of this post, JSON is very tempting but it rarely supports comments. Luckily for us, Apache Johnzon made it an option very early and my previous post was about it. The missing part was the JSON-B support, let see how to enable that comment feature for JSON-B.

The first thing to do is to ensure you have the right dependencies:

1. The JSON-P (underlying JSON reader/parser implementation for JSON-B), JSON-B API,
2. Apache Johnzon JSON-B implementation.

Here is what it looks like in a Maven pom:

<dependencies>
  <!-- spec API - you can use javax ones as well -->
  <dependency>
    <groupId>org.apache.geronimo.specs</groupId>
    <artifactId>geronimo-jsonb_1.0_spec</artifactId>
    <version>1.1</version>
  </dependency>
  <dependency>
    <groupId>org.apache.geronimo.specs</groupId>
    <artifactId>geronimo-json_1.1_spec</artifactId>
    <version>1.1</version>
  </dependency>

  <!-- implementation -->
  <dependency>
    <groupId>org.apache.johnzon</groupId>
    <artifactId>johnzon-jsonb</artifactId>
    <version>1.1.12</version>
  </dependency>
</dependencies>

Now the next step is to have some java code activating the configuration friendly options:

final JsonbConfig jsonbConfig = new JsonbConfig()
        .withFormatting(true) // 1
        .setProperty("org.apache.johnzon.supports-comments", true); // 2

1. The formatting is a standard property of JSON-B, it is useful only when when writing so in most cases - where you read the configuration - you will just ignore this line,
2. The property org.apache.johnzon.supports-comments is a Apache Johnzon specific property of JSON-P implementation which enables to skip comments when reading and not fail which enables to have commented configuration files. Since JSON-B relies on JSON-P this property works while passed to the underlying JsonProvider.

Then we must ensure the JSON-P implementation used relies on previous property and in case there is also Yasson implementation in the classpath that Johnzon is used - otherwise the configuration wouldn't be used:

final JsonbBuilder jsonbBuilder = JsonbBuilder
        .newBuilder()
        .withProvider(new org.apache.johnzon.core.JsonProviderImpl()) // 1
        .withConfig(jsonbConfig); // 2

1. We enforce Johzon implementation,
2. We pass our configuration enabling comments support.

Finally we just have to build our Jsonb instance calling the build() method of the builder and use it normally:

try (final Jsonb jsonb = jsonbBuilder.build();
     final Reader reader = Files.newBufferedReader(Paths.get("configuration.json"))) {
    final Config config = jsonb.fromJson(reader, Config.class);
    System.out.println(config);
}

If you care about being portable, you can wrap the withProvider within a try/catch block to ensure it will be ignored if Johnzon is not present - which means you will loose the comments feature but the parsing of a standard JSON file will still work.

It can look a detail but enabling to use comments in a configuration is key to ensure it is usable. It can be as simple as don't modify this count because the database will not support it or as a this was a probably too large value which can require more tuning. The point is that configuration files are also communication files so they must support comments to ensure the documentation stay close to the entries, maintained and aligned on the actual configuration.

The other key point of a configuration file is to be able to be validated to let the user know it is invalid and nto silently loose some configuration, Apache Johnzon also has some tools to help you doing that - and you can fine it at the bottom of this page - but this is another story post ;).