Java, Web and Mobile

Blog

JSON-B is coming

|
Java EE

Java EE & JSON

For years, I have been working with Java EE in combination with REST services. Vast majority of REST services today use JSON as data format. However, there is no real standard for binding java objects to JSON and reverse. Gson and Jackson have established as a kind of de facto standard. Nevertheless, I hardly remember any project not facing issues regarding JSON conversion (Just think about date and time adapters).

Java EE7 introduced JSON-P, which is supposed to standardize processing and parsing of JSON. However, this approach uses the builder pattern to create JSON programmatically and does not support binding to POJOs. In Q3 of this year, EE8 now brings ‘Java API for JSON Binding’ (JSON-B) to close that gap. Time for a closer look.

Getting started

Using maven we need to add at least three dependencies to our pom.xml:

Artifact javax.json.bind-api provides the standard API, yasson provides the reference implementation. As you can see, there are no finales released yet. Therefore, you may need to add the project’s snapshot repositories as shown in listing 2.

A first example

Now, we are ready to write our converter:

Looks easy and reminds me of Gson. JsonbBuilder has two tasks: First, it encapsulates access to provider specific implementation (in this case Yasson). Second, it creates an object of type Jsonb that will be used for JSON binding operations.

Having that, we start binding a simple entity with some primitive data types. Listing 4 shows a first unit test.

Binding works! Using standard behaviour our simple class Entity does not need any annotations.

Collections, transient fields & co.

Of course, we can also handle typical use-cases including transient fields, collections or custom data types. Listing 5 extends our Entity class.

As you can see, lists are supported out of the box and do not need any mapping metadata. In contrast, to tell JSON-B to ignore field ignoredAttribute when serializing an object we need to add annotation JsonbTransient.

Complex attributes (such as class SubEntity) are mapped recursively by default. However, if you want to setup a custom mapping, add annotation JsonbTypeAdapter naming the JsonbAdapter to be used for binding. A JsonbAdapter defines a mapping from any custom data type to a primitive data type. Listing 6 shows a basic implementation.

Date and time out of the box

In projects I have spent hours for discussions and bugs regarding date and time conversion. JSON-B brings support for Java 8 date and time API out of the box. Listing 7 shows how to easily bind date or time values.

JSON-B automatically supports dates and times without any self-written type adapters. By default, a valid ISO 8601 date format will be applied. If you want to change date format or locale, just use annotation JsonbDateFormat.

JSON to Pojo

Until now, we just looked at the conversion from Pojos to JSON. Of course, JSON-B supports the opposite direction. Listing 8 extends our JsonConverter.

The code looks similar to Listing 2. Again, we create an instance of Jsonb. To bind a JSON string we need to provide the target class’ type. The unit test in listing 9 shows our converter in action.

Use-case specific binding

For now, we added JsonbXXX annotations to our sample entity. If you want to setup a global standard within your project, you can either apply annotations on package level or configure the JsonbBuilder as shown in listing 10.

Production ready?

Well, no. Looking at the JCP process the Proposed Final Draft is still outstanding. However, the API seems to be feature complete. Having Yasson, there is already a working reference implementation. Yasson just published the first milestone release. Nevertheless, this release still includes a couple of snapshot dependencies. In addition, my hands-on revealed some bugs (or just missing features) using the custom JsonbConfig.

In the end, I am really looking forward to the final JSON-B release. In EE world, JSON-B has the potential to replace Gson or Jackson.