Course – LS (cat=JSON/Jackson)

Get started with Spring and Spring Boot, through the Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

JSON is a de-facto standard for RESTful applications. Spring uses the Jackson library to convert objects into and from JSON seamlessly. However, sometimes, we want to customize the conversion and provide specific rules.

One such thing is to ignore empty or null values from responses or requests. This might provide performance benefits as we don’t need to send empty values back and forth. Also, this can make our APIs more straightforward.

In this tutorial, we’ll learn how to leverage Jackson mapping to simplify our REST interactions.

2. Null Values

While sending or receiving requests, we often can see the values set to nulls. However, usually, it doesn’t provide us with any useful information as, in most cases, this is a default value for non-defined variables or fields.

Also, the fact that we allow null values passed in JSON complicates the validation process. We can skip the validation and set it to default if the value isn’t present. However, if the value is present, we need to do additional checks to identify if it’s null and if it’s possible to convert it to some reasonable representation.

Jackson provides a convenient way to configure it directly in our classes. We’ll use Include.NON_NULL. It can be used on the class level if the rule applies to all the fields, or we can use it more granularly on the fields, getters, and setters. Let’s consider the following Employee class:

@JsonInclude(Include.NON_NULL)
public class Employee {
    private String lastName;
    private String firstName;
    private long id;
    // constructors, getters and setters
}

If any of the fields is null, and we’re talking only about reference fields, they won’t be included in the generated JSON:

@ParameterizedTest
@MethodSource
void giveEndpointWhenSendEmployeeThanReceiveThatUserBackIgnoringNullValues(Employee expected) throws Exception {
    MvcResult result = sendRequestAndGetResult(expected, USERS);
    String response = result.getResponse().getContentAsString();
    validateJsonFields(expected, response);
}

private void validateJsonFields(Employee expected, String response) throws JsonProcessingException {
    JsonNode jsonNode = mapper.readTree(response);
    Predicate<Field> nullField = s -> isFieldNull(expected, s);
    List<String> nullFields = filterFieldsAndGetNames(expected, nullField);
    List<String> nonNullFields = filterFieldsAndGetNames(expected, nullField.negate());
    nullFieldsShouldBeMissing(nullFields, jsonNode);
    nonNullFieldsShouldNonBeMissing(nonNullFields, jsonNode);
}

Sometimes, we want to replicate a similar behavior for null-like fields, and Jackson also provides a way to handle them.

3. Absent Values

Empty Optional is, technically, a non-null value. However, passing a wrapper for non-existent values in requests or responses makes little sense. The previous annotation won’t handle this case and will try to add some information about the wrapper itself:

{
  "lastName": "John",
  "firstName": "Doe",
  "id": 1,
  "salary": {
    "empty": true,
    "present": false
  }
}

Let’s imagine that every employee in our company can expose their salary if they want to do so:

@JsonInclude(Include.NON_ABSENT)
public class Employee {
    private String lastName;
    private String firstName;
    private long id;
    private Optional<Salary> salary;
    // constructors, getters and setters
}

We can handle it with custom getters and setters that return null values. However, it would complicate the API and disregard the idea behind using Optionals in the first place. To ignore empty Optionals, we can use Include.NON_ABSENT:

private void validateJsonFields(Employee expected, String response) throws JsonProcessingException {
    JsonNode jsonNode = mapper.readTree(response);
    Predicate<Field> nullField = s -> isFieldNull(expected, s);
    Predicate<Field> absentField = s -> isFieldAbsent(expected, s);
    List<String> nullOrAbsentFields = filterFieldsAndGetNames(expected, nullField.or(absentField));
    List<String> nonNullAndNonAbsentFields = filterFieldsAndGetNames(expected, nullField.negate().and(absentField.negate()));
    nullFieldsShouldBeMissing(nullOrAbsentFields, jsonNode);
    nonNullFieldsShouldNonBeMissing(nonNullAndNonAbsentFields, jsonNode);
}

Include.NON_ABSENT handles empty Optional values and nulls so that we can use it for both scenarios.

4. Empty Values

Should we include empty strings or empty collections in the generated JSON? In most cases, it doesn’t make sense. Setting them to nulls or wrapping them with Optionals might not be a good idea and can complicate the interactions with the objects.

Let’s consider some additional information about our employees. As we’re working in an international organization, it would be reasonable to assume that an employee might want to add a phonetic version of their name. Also, they might provide a phone number or numbers to allow others to get in touch with them:

@JsonInclude(Include.NON_EMPTY)
public class Employee {
    private String lastName;
    private String firstName;
    private long id;
    private Optional<Salary> salary;
    private String phoneticName = "";
    private List<PhoneNumber> phoneNumbers = new ArrayList<>();
    // constructors, getters and setters
}

We can use Include.NON_EMPTY to exclude the values if they’re empty. This configuration ignores null and absent values as well:

private void validateJsonFields(Employee expected, String response) throws JsonProcessingException {
    JsonNode jsonNode = mapper.readTree(response);
    Predicate<Field> nullField = s -> isFieldNull(expected, s);
    Predicate<Field> absentField = s -> isFieldAbsent(expected, s);
    Predicate<Field> emptyField = s -> isFieldEmpty(expected, s);
    List<String> nullOrAbsentOrEmptyFields = filterFieldsAndGetNames(expected, nullField.or(absentField).or(emptyField));
    List<String> nonNullAndNonAbsentAndNonEmptyFields = filterFieldsAndGetNames(expected,
      nullField.negate().and(absentField.negate().and(emptyField.negate())));
    nullFieldsShouldBeMissing(nullOrAbsentOrEmptyFields, jsonNode);
    nonNullFieldsShouldNonBeMissing(nonNullAndNonAbsentAndNonEmptyFields, jsonNode);
}

As was mentioned previously, all these annotations can be used more granularly, and we can even apply different strategies to different fields. Additionally, we can configure our mapper globally to apply this rule to any conversion.

5. Custom Mappers

If the above strategies aren’t flexible enough for our needs or need to support specific conventions, we should use Include.CUSTOM or implement a custom serializer:

public class CustomEmployeeSerializer extends StdSerializer<Employee> {
    @Override
    public void serialize(Employee employee, JsonGenerator gen, SerializerProvider provider)
      throws IOException {
        gen.writeStartObject();
        // Custom logic to serialize other fields
        gen.writeEndObject();
    }
}

6. Conclusion

Jackson and Spring can help us develop RESTul applications with minimal configuration from our side. Inclusion strategies can simplify our APIs and reduce the amount of boilerplate code. At the same time, if the default solutions are too restrictive or inflexible, we can extend using custom mappers or filters.

As usual, all the code from this tutorial is available over on GitHub.

Course – LS (cat=Spring)

Get started with Spring and Spring Boot, through the Learn Spring course:

>> THE COURSE
Course – LS (cat=JSON/Jackson)

Get started with Spring and Spring Boot, through the Learn Spring course:

>> CHECK OUT THE COURSE
res – Jackson (eBook) (cat=Jackson)
Comments are closed on this article!