Mastering Jackson: Practical JSON Handling Techniques for Java Backend

In modern Java development, JSON handling is a fundamental skill. Jackson, as an industry‑leading JSON library, is chosen for its high performance, flexibility, and rich features.

This article combines real‑world scenarios to demonstrate practical Jackson usage and provides a well‑encapsulated utility class to help you efficiently process JSON data.

1. Typical Use Cases and Solutions

Scenario 1: Serialization and Deserialization of Complex Objects

Requirement: Convert Java objects to JSON strings and vice versa.

Solution: Use Jackson's ObjectMapper for basic conversion and control serialization behavior with annotations.

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.time.LocalDateTime;

// User class example
@JsonInclude(JsonInclude.Include.NON_NULL)
class User {
    @JsonProperty("user_id")
    private String userId;
    private String username;
    private LocalDateTime createTime;
    // Constructors, getters, setters omitted
}

public class JacksonUtils {
    private static final ObjectMapper mapper = new ObjectMapper();

    // Object to JSON string
    public static String toJson(Object obj) {
        try {
            return mapper.writeValueAsString(obj);
        } catch (Exception e) {
            throw new RuntimeException("JSON serialization failed", e);
        }
    }

    // JSON string to object
    public static <T> T toObject(String json, Class<T> clazz) {
        try {
            return mapper.readValue(json, clazz);
        } catch (Exception e) {
            throw new RuntimeException("JSON deserialization failed", e);
        }
    }
}

User user = new User("1001", "john_doe", LocalDateTime.now());
String json = JacksonUtils.toJson(user);
User parsedUser = JacksonUtils.toObject(json, User.class);

Scenario 2: Handling Date Formats

Requirement: Standardize date formats in JSON, supporting types such as java.util.Date and java.time.LocalDateTime.

Solution: Register JavaTimeModule and configure date formatting.

import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.fasterxml.jackson.datatype.jsr310.deser.LocalDateTimeDeserializer;
import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateTimeSerializer;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class JacksonUtils {
    private static final ObjectMapper mapper;
    private static final String DATE_TIME_FORMAT = "yyyy-MM-dd HH:mm:ss";

    static {
        mapper = new ObjectMapper();
        JavaTimeModule timeModule = new JavaTimeModule();
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern(DATE_TIME_FORMAT);
        timeModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(formatter));
        timeModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(formatter));
        mapper.registerModule(timeModule);
    }

    public static String toJsonWithFormat(Object obj) {
        return toJson(obj); // uses the configured mapper
    }
}

Scenario 3: Processing Nested Objects and Collections

Requirement: Handle JSON data with complex nested structures such as user orders or product categories.

Solution: Use generics and TypeReference to process collection types.

import com.fasterxml.jackson.core.type.TypeReference;
import java.util.List;
import java.util.Map;

// Order class example
class Order {
    private String orderId;
    private List<Product> products;
    private Map<String, Object> extraInfo;
    // Constructors, getters, setters omitted
}

// Product class example
class Product {
    private String productId;
    private String name;
    private double price;
    // Constructors, getters, setters omitted
}

public class JacksonUtils {
    // JSON string to List
    public static <T> List<T> toList(String json, Class<T> elementClass) {
        try {
            return mapper.readValue(json, mapper.getTypeFactory().constructCollectionType(List.class, elementClass));
        } catch (Exception e) {
            throw new RuntimeException("JSON to List failed", e);
        }
    }

    // JSON string to complex object (e.g., nested Map)
    public static <T> T toComplexObject(String json, TypeReference<T> typeReference) {
        try {
            return mapper.readValue(json, typeReference);
        } catch (Exception e) {
            throw new RuntimeException("JSON to complex object failed", e);
        }
    }
}

String jsonList = "[{\"productId\":\"P001\",\"name\":\"iPhone\",\"price\":9999.0}]";
List<Product> productList = JacksonUtils.toList(jsonList, Product.class);

TypeReference<Map<String, List<Order>>> typeRef = new TypeReference<>() {};
Map<String, List<Order>> resultMap = JacksonUtils.toComplexObject(jsonString, typeRef);

Scenario 4: Dynamic Field Filtering

Requirement: Dynamically control which fields are serialized or deserialized in different contexts (e.g., filter sensitive information).

Solution: Use @JsonFilter annotation together with SimpleFilterProvider.

import com.fasterxml.jackson.databind.ser.FilterProvider;
import com.fasterxml.jackson.databind.ser.impl.SimpleBeanPropertyFilter;
import com.fasterxml.jackson.databind.ser.impl.SimpleFilterProvider;

@JsonFilter("userFilter")
class User {
    private String userId;
    private String username;
    private String password; // sensitive field
    private String email;
    // Constructors, getters, setters omitted
}

public class JacksonUtils {
    public static String toJsonWithFilter(Object obj, String filterName, String... fieldsToExclude) {
        try {
            FilterProvider filters = new SimpleFilterProvider()
                .addFilter(filterName, SimpleBeanPropertyFilter.serializeAllExcept(fieldsToExclude));
            return mapper.writer(filters).writeValueAsString(obj);
        } catch (Exception e) {
            throw new RuntimeException("Filtered JSON serialization failed", e);
        }
    }
}

User user = new User("1001", "john_doe", "123456", "[email protected]");
String safeJson = JacksonUtils.toJsonWithFilter(user, "userFilter", "password");

Scenario 5: Working with JSON Tree Model

Requirement: Directly manipulate JSON structure, dynamically add, delete, or modify nodes.

Solution: Use Jackson's tree model API ( JsonNode).

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;

public class JacksonUtils {
    public static JsonNode toJsonNode(String json) {
        try {
            return mapper.readTree(json);
        } catch (Exception e) {
            throw new RuntimeException("JSON to JsonNode failed", e);
        }
    }

    public static String getNodeValue(JsonNode node, String fieldName) {
        JsonNode valueNode = node.get(fieldName);
        return valueNode != null ? valueNode.asText() : null;
    }

    public static String modifyNode(String json, String fieldName, Object newValue) {
        try {
            ObjectNode node = (ObjectNode) mapper.readTree(json);
            if (newValue instanceof String) {
                node.put(fieldName, (String) newValue);
            } else if (newValue instanceof Integer) {
                node.put(fieldName, (Integer) newValue);
            } else if (newValue instanceof Boolean) {
                node.put(fieldName, (Boolean) newValue);
            } else if (newValue instanceof Double) {
                node.put(fieldName, (Double) newValue);
            } else {
                node.putPOJO(fieldName, newValue);
            }
            return node.toString();
        } catch (Exception e) {
            throw new RuntimeException("Modify JSON node failed", e);
        }
    }
}

String json = "{\"name\":\"Alice\",\"age\":30}";
JsonNode node = JacksonUtils.toJsonNode(json);
String name = JacksonUtils.getNodeValue(node, "name"); // "Alice"
String modifiedJson = JacksonUtils.modifyNode(json, "age", 31);

2. Complete Utility Class Wrapper

The following is a full Jackson utility class that integrates all the above functionalities.

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.databind.ser.FilterProvider;
import com.fasterxml.jackson.databind.ser.impl.SimpleBeanPropertyFilter;
import com.fasterxml.jackson.databind.ser.impl.SimpleFilterProvider;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.fasterxml.jackson.datatype.jsr310.deser.LocalDateTimeDeserializer;
import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateTimeSerializer;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.List;
import java.util.Map;

/**
 * Jackson JSON processing utility class
 * Provides object‑JSON conversion, date formatting, field filtering, etc.
 */
public class JacksonUtils {
    private static final ObjectMapper mapper;
    private static final String DATE_TIME_FORMAT = "yyyy-MM-dd HH:mm:ss";

    static {
        mapper = new ObjectMapper();
        mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        JavaTimeModule timeModule = new JavaTimeModule();
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern(DATE_TIME_FORMAT);
        timeModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(formatter));
        timeModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(formatter));
        mapper.registerModule(timeModule);
    }

    public static String toJson(Object obj) {
        try {
            return mapper.writeValueAsString(obj);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("JSON serialization failed", e);
        }
    }

    public static <T> T toObject(String json, Class<T> clazz) {
        try {
            return mapper.readValue(json, clazz);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("JSON deserialization failed", e);
        }
    }

    public static <T> List<T> toList(String json, Class<T> elementClass) {
        try {
            return mapper.readValue(json, mapper.getTypeFactory().constructCollectionType(List.class, elementClass));
        } catch (JsonProcessingException e) {
            throw new RuntimeException("JSON to List failed", e);
        }
    }

    public static <T> T toComplexObject(String json, TypeReference<T> typeReference) {
        try {
            return mapper.readValue(json, typeReference);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("JSON to complex object failed", e);
        }
    }

    public static String toJsonWithFilter(Object obj, String filterName, String... fieldsToExclude) {
        try {
            FilterProvider filters = new SimpleFilterProvider()
                .addFilter(filterName, SimpleBeanPropertyFilter.serializeAllExcept(fieldsToExclude));
            return mapper.writer(filters).writeValueAsString(obj);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("Filtered JSON serialization failed", e);
        }
    }

    public static JsonNode toJsonNode(String json) {
        try {
            return mapper.readTree(json);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("JSON to JsonNode failed", e);
        }
    }

    public static String getNodeValue(JsonNode node, String fieldName) {
        JsonNode valueNode = node.get(fieldName);
        return valueNode != null ? valueNode.asText() : null;
    }

    public static String modifyNode(String json, String fieldName, Object newValue) {
        try {
            ObjectNode node = (ObjectNode) mapper.readTree(json);
            if (newValue instanceof String) {
                node.put(fieldName, (String) newValue);
            } else if (newValue instanceof Integer) {
                node.put(fieldName, (Integer) newValue);
            } else if (newValue instanceof Boolean) {
                node.put(fieldName, (Boolean) newValue);
            } else if (newValue instanceof Double) {
                node.put(fieldName, (Double) newValue);
            } else {
                node.putPOJO(fieldName, newValue);
            }
            return node.toString();
        } catch (JsonProcessingException e) {
            throw new RuntimeException("Modify JSON node failed", e);
        }
    }
}

3. Best Practice Recommendations

Singleton Pattern: ObjectMapper is thread‑safe and should be shared globally.

Exception Handling: Encapsulate try‑catch in the utility class to avoid repetitive code.

Date Consistency: Prefer Java 8 date‑time API over java.util.Date to avoid thread‑safety issues.

Field Control: Use annotations like @JsonInclude and filters to dynamically control serialization.

Performance Optimization: For large data sets, consider Jackson's streaming API ( JsonParser / JsonGenerator).