Guide to Java Jackson-jr Library

1. Overview

Jackson-jr is a lightweight JSON processing library for Java, designed to provide a simpler and smaller alternative to the original Jackson library. With its small footprint and easy-to-use API, Jackson-jr is an excellent choice for casual JSON reading and writing scenarios.

In this guide, we will explore the key features and usage of Jackson-jr, along with examples and best practices.

2. Getting Started With Jackson-jr

Jackson-jr offers a lightweight and efficient way to handle JSON data in Java applications. It provides a simple API for working with JSON objects and arrays, making it easier to parse, generate, and manipulate JSON data.

First, we must include the Jackson-jr library in our project. We can do this by adding the desired version of the Jackson-jr dependency to our project’s build configuration file.

For Maven, we can add the dependency to our pom.xml file:

<dependency>
    <groupId>com.fasterxml.jackson.jr</groupId>
    <artifactId>jackson-jr-all</artifactId>
    <version>2.15.2</version>
</dependency> 

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

implementation 'com.fasterxml.jackson.jr:jackson-jr-all:2.15.2'

3. Working with JSON Objects

The base object for working with Jackson-jr is the JSON object. A very important and not to forget fact about the JSON object: every JSON instance is fully immutable and thread-safe. We can use them however we want, a Singleton instance, a Spring Bean, or even construct individual objects. We can pass the same instance between different threads, as it is fully immutable.

3.1. Creating JSON Objects and Arrays

Creating JSON objects and arrays: Jackson-jr provides a convenient API for creating JSON objects and arrays. We can use classes like LinkedHashMap to represent JSON objects and ArrayList to represent JSON arrays.

The JSON object is a LinkedHashMap. We can easily add properties to it using the LinkedHashMap.put() method and get properties with the LinkedHashMap.get() method.

String json = JSON.std
  .with(JSON.Feature.PRETTY_PRINT_OUTPUT)
  .asString(new LinkedHashMap<String, Object>() {{
      put("name", "John Doe");
      put("age", 30);
      put("email", "[email protected]");
  }});

3.2. Jackson-jr Composer

Another nice feature of Jackson-jr is the addition of the Composer interface for generating JSON content in a Builder-like style:

String json = JSON.std.with(JSON.Feature.PRETTY_PRINT_OUTPUT)
  .composeString()
  .startObject()
  .startArrayField("objectArray")
  .startObject()
  .put("name", "name1")
  .put("age", 11)
  .end()  
  .startObject()
  .put("name", "name2")
  .put("age", 12)
  .end()  
  .end()  
  .startArrayField("array")
  .add(1) 
  .add(2) 
  .add(3) 
  .end()  
  .startObjectField("object")
  .put("name", "name3")
  .put("age", 13)
  .end()  
  .put("last", true)
  .end()  
  .finish();

This builder results in the following JSON:

{
  "objectArray" : [ {
    "name" : "name1",
    "age" : 11
  }, {
    "name" : "name2",
    "age" : 12
  } ],
  "array" : [ 1, 2, 3 ],
  "object" : {
    "name" : "name3",
    "age" : 13
  },
  "last" : true
}

4. Serialization and Deserialization

Jackson-jr allows us to easily convert Java objects to JSON strings and vice versa. We can configure the writer with desired options, such as pretty-printing or custom date formats, and then use it to write objects as JSON strings.

Jackson-jr supports complex object structures, including nested objects and arrays. By properly defining the structure of our Java classes and their relationships, Jackson-jr can handle the serialization and deserialization of complex JSON data.

// Serialization
String json = JSON.std.with(JSON.Feature.PRETTY_PRINT_OUTPUT)
  .asString(person);

// Deserialization
json = "{\"name\":\"John Doe\",\"age\":30}";
Person person1 = JSON.std.with(JSON.Feature.PRETTY_PRINT_OUTPUT)
  .beanFrom(Person.class, json);

4.1. Customization in Jackson-jr

Jackson-jr supports various annotations, such as @JsonProperty, to customize the serialization and deserialization process. These annotations allow us to control the names of properties, specify date and time formats, and handle other customization scenarios. We can see a list of all the supported annotations in their official Github project for annotations.

Jackson-jr has a list of feature customization that we can use to customize the input and output of our serialization and deserialization, customization like pretty print, write null properties, etc. The easiest way to see all of them would be right in the base code.

JSON jsonMapper = JSON.std.with(JSON.Feature.PRETTY_PRINT_OUTPUT)
  .with(JSON.Feature.WRITE_NULL_PROPERTIES)
  .with(JSON.Feature.FAIL_ON_DUPLICATE_MAP_KEYS);
String json = jsonMapper.asString(person);

Jackson-jr allows us to create custom serializers and deserializers to handle specific data types or complex serialization scenarios. By implementing the appropriate interfaces, ValueWriter, and extending the provided classes, ValueReader and ReadWriterProvider, we can define how our custom objects should be serialized and deserialized.

Jackson-jr does not support java.time.* package, but we can add this with custom serializers and deserializers:

public class CustomDateSerializer implements ValueWriter {
    @Override
    public void writeValue (JSONWriter jsonWriter, JsonGenerator jsonGenerator, Object o) throws IOException {
        jsonGenerator.writeString(o.toString());
    }

    @Override
    public Class<?> valueType () {
        return LocalDate.class;
    }
}

public class CustomDateDeserializer extends ValueReader {
    private final static DateTimeFormatter dtf = DateTimeFormatter.ofPattern("yyyy-MMM-dd");

    public CustomDateDeserializer () {
        super(LocalDate.class);
    }

    @Override
    public Object read (JSONReader jsonReader, JsonParser jsonParser) throws IOException {
        return LocalDate.parse(jsonParser.getText(), dtf);
    }
}

After we register them, we can start serializing and deserializing LocalDate objects:

public class MyHandlerProvider extends ReaderWriterProvider {

    @Override
    public ValueWriter findValueWriter (JSONWriter writeContext, Class<?> type) {
        if (type == LocalDate.class) {
            return new CustomDateSerializer();
        }
        return null;
    }

    @Override
    public ValueReader findValueReader (JSONReader readContext, Class<?> type) {
        if (type.equals(LocalDate.class)) {
            return new CustomDateDeserializer();
        }
        return null;
    }
}

Person person = new Person("John Doe", 30, LocalDate.now());

JSON jsonMapper = JSON.builder().register(new JacksonJrExtension() {
    @Override
    protected void register (ExtensionContext extensionContext) {
        extensionContext.insertProvider(new MyHandlerProvider());
    }   
}).build().with(JSON.Feature.PRETTY_PRINT_OUTPUT);

String json = jsonMapper.asString(person);
Person deserializedPerson = jsonMapper.beanFrom(Person.class, json);

5. Jackson-jr vs. Jackson

6. Conclusion

Jackson-jr offers a lightweight and user-friendly approach to JSON processing in Java applications. With its simplified API, customization options, and efficient performance, it is an excellent choice for developers who need a lightweight JSON processing library without compromising on functionality.

As always, the source code for the examples is available over on GitHub.