Introduction to Jsoniter

1. Introduction

JavaScript Object Notation, or JSON, has gained a lot of popularity as a data interchange format in recent years. Jsoniter is a new JSON parsing library aimed at offering a more flexible and more performant JSON parsing than the other available parsers.

In this tutorial, we'll see how to parse JSON objects using the Jsoniter library for Java.

2. Dependencies

The latest version of Jsoniter can be found from the Maven Central repository.

Let's start by adding the dependencies to the pom.xml:

<dependency>
    <groupId>com.jsoniter<groupId> 
    <artifactId>jsoniter</artifactId>
    <version>0.9.23</version>
</dependency>

Similarly, we can add the dependency to our build.gradle file:

compile group: 'com.jsoniter', name: 'jsoniter', version: '0.9.23'

3. JSON Parsing Using Jsoniter

Jsoniter provides 3 APIs to parse JSON documents:

• Bind API
• Any API
• Iterator API

Let's look into each of the above APIs.

3.1. JSON Parsing Using the Bind API

The bind API uses the traditional way of binding the JSON document to Java classes.

Let's consider the JSON document with student details:

{"id":1,"name":{"firstName":"Joe","surname":"Blogg"}}

Let's now define the Student and Name schema classes to represent the above JSON:

public class Student {
    private int id;
    private Name name;
    
    // standard setters and getters
}

public class Name {
    private String firstName;
    private String surname;
    
    // standard setters and getters
}

De-serializing the JSON to a Java object using the bind API is very simple. We use the deserialize method of JsonIterator:

@Test
public void whenParsedUsingBindAPI_thenConvertedToJavaObjectCorrectly() {
    String input = "{\"id\":1,\"name\":{\"firstName\":\"Joe\",\"surname\":\"Blogg\"}}";
    
    Student student = JsonIterator.deserialize(input, Student.class);

    assertThat(student.getId()).isEqualTo(1);
    assertThat(student.getName().getFirstName()).isEqualTo("Joe");
    assertThat(student.getName().getSurname()).isEqualTo("Blogg");
}

The Student schema class declares the id to be of int datatype. However, what if the JSON that we receive contains a String value for the id instead of a number? For example:

{"id":"1","name":{"firstName":"Joe","surname":"Blogg"}}

Notice how the id in the JSON is a string value “1” this time. Jsoniter provides Maybe decoders to deal with this scenario.

3.2. Maybe Decoders

Jsoniter's Maybe decoders come in handy when the datatype of a JSON element is fuzzy. The datatype for the student.id field is fuzzy — it can either be a String or an int. To handle this, we need to annotate the id field in our schema class using the MaybeStringIntDecoder:

public class Student {
    @JsonProperty(decoder = MaybeStringIntDecoder.class)
    private int id;
    private Name name;
    
    // standard setters and getters
}

We can now parse the JSON even when the id value is a String:

@Test
public void givenTypeInJsonFuzzy_whenFieldIsMaybeDecoded_thenFieldParsedCorrectly() {
    String input = "{\"id\":\"1\",\"name\":{\"firstName\":\"Joe\",\"surname\":\"Blogg\"}}";
    
    Student student = JsonIterator.deserialize(input, Student.class);

    assertThat(student.getId()).isEqualTo(1); 
}

Similarly, Jsoniter offers other decoders such as MaybeStringLongDecoder and MaybeEmptyArrayDecoder.

Let's now imagine that we were expecting to receive a JSON document with the Student details but we receive the following document instead:

{"error":404,"description":"Student record not found"}

What happened here? We were expecting a success response with Student data but we received an error response. This is a very common scenario but how would we handle this?

One way is to perform a null check to see if we received an error response before extracting the Student data. However, the null checks can lead to some hard-to-read code, and the problem is made worse if we have a multi-level nested JSON.

Jsoniter's parsing using the Any API comes to the rescue.

3.3. JSON Parsing Using the Any API

When the JSON structure itself is dynamic, we can use Jsoniter's Any API that provides a schema-less parsing of the JSON. This works similarly to parsing the JSON into a Map<String, Object>.

Let's parse the Student JSON as before but using the Any API this time:

@Test
public void whenParsedUsingAnyAPI_thenFieldValueCanBeExtractedUsingTheFieldName() {
    String input = "{\"id\":1,\"name\":{\"firstName\":\"Joe\",\"surname\":\"Blogg\"}}";
    
    Any any = JsonIterator.deserialize(input);

    assertThat(any.toInt("id")).isEqualTo(1);
    assertThat(any.toString("name", "firstName")).isEqualTo("Joe");
    assertThat(any.toString("name", "surname")).isEqualTo("Blogg"); 
}

Let's understand this example. First, we use the JsonIterator.deserialize(..) to parse the JSON. However, we do not specify a schema class in this instance. The result is of type Any.

Next, we read the field values using the field names. We read the “id” field value using the Any.toInt method. The toInt method converts the “id” value to an integer. Similarly, we read the “name.firstName” and “name.surname” field values as string values using the toString method.

Using the Any API, we can also check if an element is present in the JSON. We can do this by looking up the element and then inspecting the valueType of the lookup result. The valueType will be INVALID when the element is not present in the JSON.

For example:

@Test
public void whenParsedUsingAnyAPI_thenFieldValueTypeIsCorrect() {
    String input = "{\"id\":1,\"name\":{\"firstName\":\"Joe\",\"surname\":\"Blogg\"}}";
    
    Any any = JsonIterator.deserialize(input);

    assertThat(any.get("id").valueType()).isEqualTo(ValueType.NUMBER);
    assertThat(any.get("name").valueType()).isEqualTo(ValueType.OBJECT);
    assertThat(any.get("error").valueType()).isEqualTo(ValueType.INVALID);
}

The “id” and “name” fields are present in the JSON and hence their valueType is NUMBER and OBJECT respectively. However, the JSON input does not have an element by the name “error” and so the valueType is INVALID.

Going back to the scenario mentioned at the end of the previous section, we need to detect whether the JSON input we received is a success or an error response. We can check if we received an error response by inspecting the valueType of the “error” element:

String input = "{\"error\":404,\"description\":\"Student record not found\"}";
Any response = JsonIterator.deserialize(input);

if (response.get("error").valueType() != ValueType.INVALID) {
    return "Error!! Error code is " + response.toInt("error");
}
return "Success!! Student id is " + response.toInt("id");

When run, the above code will return “Error!! Error code is 404”.

Next, we'll look at using the Iterator API to parse JSON documents.

3.4. JSON Parsing Using the Iterator API

If we wish to perform the binding manually, we can use Jsoniter's Iterator API. Let's consider the JSON:

{"firstName":"Joe","surname":"Blogg"}

We'll use the Name schema class that we used earlier to parse the JSON using the Iterator API:

@Test
public void whenParsedUsingIteratorAPI_thenFieldValuesExtractedCorrectly() throws Exception {
    Name name = new Name();    
    String input = "{\"firstName\":\"Joe\",\"surname\":\"Blogg\"}";
    JsonIterator iterator = JsonIterator.parse(input);

    for (String field = iterator.readObject(); field != null; field = iterator.readObject()) {
        switch (field) {
            case "firstName":
                if (iterator.whatIsNext() == ValueType.STRING) {
                    name.setFirstName(iterator.readString());
                }
                continue;
            case "surname":
                if (iterator.whatIsNext() == ValueType.STRING) {
                    name.setSurname(iterator.readString());
                }
                continue;
            default:
                iterator.skip();
        }
    }

    assertThat(name.getFirstName()).isEqualTo("Joe");
    assertThat(name.getSurname()).isEqualTo("Blogg");
}

Let's understand the above example. First, we parse the JSON document as an iterator. We use the resulting JsonIterator instance to iterate over the JSON elements:

1. We start by invoking the readObject method which returns the next field name (or a null if the end of the document has been reached).
2. If the field name is not of interest to us, we skip the JSON element by using the skip method. Otherwise, we inspect the data type of the element by using the whatIsNext method. Invoking the whatIsNext method is not mandatory but is useful when the datatype of the field is unknown to us.
3. Finally, we extract the value of the JSON element using the readString method.

4. Conclusion

In this article, we discussed the various approaches offered by Jsoniter for parsing the JSON documents as Java objects.

First, we looked at the standard way of parsing a JSON document using a schema class.

Next, we looked at handling fuzzy data types and the dynamic structures when parsing JSON documents using the Maybe decoders and Any datatype, respectively.

Finally, we looked at the Iterator API for binding the JSON manually to a Java object.

As always the source code for the examples used in this article is available over on GitHub.