# Jackson ObjectMapper ## About `ObjectMapper` is a core class provided by the **Jackson** library, used for converting between Java objects and JSON. It allows us to: * Serialize Java objects to JSON * Deserialize JSON to Java objects * Work with Maps, Lists, and generic types * Configure inclusion/exclusion rules * Register modules for special data types like Java 8 date/time, Java records, etc. Although Jackson is not a Spring-native library, **Spring Boot auto-configures Jackson** and provides seamless integration out-of-the-box, making `ObjectMapper` one of the most commonly used utilities in Spring-based applications. ## **Dependency** If we are using Spring Boot with web or REST modules, Jackson is included automatically via the `spring-boot-starter-web` dependency: ```xml org.springframework.boot spring-boot-starter-web ``` This transitively includes: ```xml com.fasterxml.jackson.core jackson-databind ``` If we are not using Spring Boot or want to include Jackson manually, add: ```xml com.fasterxml.jackson.core jackson-databind 2.17.0 ``` ## **Spring Integration** ### **How Spring Boot Uses Jackson Internally ?** Spring Boot uses Jackson as the default JSON processor. When we build a REST API or web application with `spring-boot-starter-web`, it: * Automatically includes the Jackson library (`jackson-databind`) * Registers a **singleton `ObjectMapper` bean** in the Spring context * Uses that bean for: * Serializing controller response objects (`@ResponseBody`) * Deserializing request bodies into Java objects (`@RequestBody`) * JSON conversion in `RestTemplate`, `WebClient`, and Feign clients We can inject and use this same ObjectMapper throughout our application: ```java @Autowired private ObjectMapper objectMapper; ``` ### **Default Behavior in Spring Boot** When using Spring Boot, the default `ObjectMapper` is configured with sensible defaults. #### **Example Defaults**
FeatureDefault Behavior
Include null fields in JSONYes
Pretty-print JSONNo
Fail on unknown JSON propertiesNo (FAIL_ON_UNKNOWN_PROPERTIES is disabled)
Support for Java 8 Date/Time typesYes (via jackson-datatype-jsr310)
Use of ISO-8601 for date serializationYes
Support for Java 8 Optional typesYes
Snake case supportNo (uses camelCase by default)
We can override these behaviors either: 1. Through application properties 2. By providing a custom `ObjectMapper` bean ### Customizing ObjectMapper via `application.yml` ```yaml spring: jackson: # Include strategy for properties # Options: always, non_null, non_absent, non_default, non_empty default-property-inclusion: non_null # Exclude null fields from JSON output # Serialization settings serialization: indent_output: true # Pretty-print the JSON output (adds newlines and spaces) # Deserialization settings deserialization: fail-on-unknown-properties: false # Do not fail if JSON has unknown fields # Date and time formatting date-format: yyyy-MM-dd'T'HH:mm:ss # Custom global date-time format time-zone: Asia/Kolkata # Time zone to use for date/time serialization # Naming strategy for property names # Options: SNAKE_CASE, LOWER_CAMEL_CASE (default), UPPER_CAMEL_CASE, KEBAB_CASE, etc. property-naming-strategy: SNAKE_CASE # Converts Java fields like "firstName" to "first_name" # Enable/disable features (serialization/deserialization-level) mapper: # Allow use of getter methods as creators (if no constructor present) allow-getters-as-setters: true # Visibility control (used less frequently) visibility: # Property-level visibility configuration field: any # Detect all fields regardless of access modifier getter: none # Ignore getters is-getter: none # Ignore "isX()" methods for booleans setter: any # Detect all setters creator: any # Detect constructors and factory methods ``` ### Internally, Spring Boot does this Spring Boot binds these properties into a `Jackson2ObjectMapperBuilder` and applies them when initializing the `ObjectMapper` bean. This is equivalent to doing this programmatically: ```java ObjectMapper mapper = new ObjectMapper(); mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); mapper.enable(SerializationFeature.INDENT_OUTPUT); mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss")); ``` ### Overriding the Default ObjectMapper If we need full control, define our own `@Bean` of type `ObjectMapper`. Spring Boot will use our version instead of the default. ```java @Configuration public class JacksonConfig { @Bean public ObjectMapper customObjectMapper() { ObjectMapper mapper = new ObjectMapper(); mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); mapper.enable(SerializationFeature.INDENT_OUTPUT); mapper.registerModule(new JavaTimeModule()); mapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE); return mapper; } } ``` > Note: If we do this, make sure to register required modules like `JavaTimeModule`, otherwise date/time parsing may break. ## Use Cases ### 1. **Serialization: Java Object to JSON** Convert a Java object into a JSON string. ```java Person person = new Person("John", 30); String json = objectMapper.writeValueAsString(person); ``` Write to file or output stream: ```java objectMapper.writeValue(new File("person.json"), person); ``` Pretty-printing: ```java objectMapper.enable(SerializationFeature.INDENT_OUTPUT); String prettyJson = objectMapper.writeValueAsString(person); ``` ### 2. **Deserialization: JSON to Java Object** Convert a JSON string to a Java object. ```java String json = "{\"name\":\"John\",\"age\":30}"; Person person = objectMapper.readValue(json, Person.class); ``` From file: ```java Person person = objectMapper.readValue(new File("person.json"), Person.class); ``` ### 3. **Convert Between Java Objects (Object to Object Mapping)** Convert one type to another using intermediate JSON conversion. Useful for mapping DTOs to entities. ```java UserDTO dto = new UserDTO("john.doe", "Admin"); UserEntity entity = objectMapper.convertValue(dto, UserEntity.class); ``` ### 4. Convert to and from Map #### **POJO Class** ```java public class User { private String name; private int age; // Constructors, getters, setters } ``` #### **Convert POJO to Map** ```java User user = new User("Alice", 25); Map map = objectMapper.convertValue(user, new TypeReference<>() {}); System.out.println(map); ``` ``` {name=Alice, age=25} ``` #### **Convert Map to POJO** ```java map = new HashMap<>(); map.put("name", "Bob"); map.put("age", 30); User user = objectMapper.convertValue(map, User.class); System.out.println(user.getName()); // Bob System.out.println(user.getAge()); // 30 ``` ### 5. **Handling Collections and Generics** Deserialize a JSON array into a list of objects: ```java String json = "[{\"name\":\"John\",\"age\":30},{\"name\":\"Jane\",\"age\":25}]"; List people = objectMapper.readValue( json, new TypeReference>() {} ); ``` Deserialize a nested structure: ```java String json = "{\"group\":\"team1\",\"members\":[{\"name\":\"John\"},{\"name\":\"Jane\"}]}"; Group group = objectMapper.readValue(json, Group.class); ``` ### **6. Deserialization with Unknown or Partial JSON** #### **POJO Class** ```java public class Product { private String name; private double price; // Constructors, getters, setters } ``` #### **JSON with Extra Field (unknown)** ```java String json = """ { "name": "Laptop", "price": 999.99, "warranty": "2 years" // Not present in Product class } """; ``` #### **Default Behavior (in Spring Boot)** By default, Spring Boot configures `ObjectMapper` to **ignore unknown fields**, so this will **work fine**. ```java Product product = objectMapper.readValue(json, Product.class); System.out.println(product.getName()); // Laptop System.out.println(product.getPrice()); // 999.99 ``` #### **Manually Ensuring it Ignores Unknown Fields** If we are not in Spring Boot, or just want to be sure: ```java objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); ``` #### **Partial JSON** ```java String partialJson = """ { "name": "Phone" } """; ``` If `price` is missing, it will be set to its default value (e.g., `0.0` for `double`). ```java Product product = objectMapper.readValue(partialJson, Product.class); System.out.println(product.getName()); // Phone System.out.println(product.getPrice()); // 0.0 ``` ## **Serialization Inclusion Strategies** Serialization inclusion strategies determine **what data gets included** in the JSON output. This is important to reduce unnecessary data in API responses, especially when dealing with large objects or REST services. #### **Options**
StrategyDescription
Include.ALWAYSAlways include the property (default)
Include.NON_NULLExclude null values
Include.NON_EMPTYExclude empty values (empty string, empty list, etc.)
Include.NON_DEFAULTExclude fields with default values
Include.NON_ABSENTExclude nulls and Java 8 Optional.empty()
#### **Global Configuration** ```java objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); ``` #### **Field-Level Configuration** ```java public class User { @JsonInclude(JsonInclude.Include.NON_EMPTY) private List tags; } ``` #### **Spring Boot Configuration (application.yml)** ```yaml spring: jackson: default-property-inclusion: non_null ``` #### **Use Case Example** You may not want to return null or empty fields to reduce response payload size: ```json { "name": "John", "email": null } ``` With `NON_NULL`, `email` will be excluded. ## **Date and Time Handling** Working with dates and times in Java can be tricky, especially when serializing and deserializing JSON in REST APIs. Jackson provides powerful capabilities for formatting and parsing date/time types, and Spring Boot makes this integration seamless—but only if you configure it correctly. #### **Why Special Handling Is Needed** Java 8 introduced a new Date-Time API under `java.time.*` packages like: * `LocalDate` * `LocalDateTime` * `ZonedDateTime` * `Instant` These types are **not supported natively** by Jackson without additional configuration. Jackson treats them differently than older types like `java.util.Date`, and without proper setup, they are either: * Serialized as **arrays** (e.g. `[2024, 6, 20]`) * Serialized as **timestamps** * Or cause **deserialization errors** #### **Solution** To handle Java 8 time types correctly: 1. **Register `JavaTimeModule`** 2. **Disable writing as timestamps** ```java ObjectMapper mapper = new ObjectMapper(); mapper.registerModule(new JavaTimeModule()); mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); ``` This enables human-readable ISO-8601 strings like: ```json "2024-06-20T15:45:00" ``` instead of: ```json [2024, 6, 20, 15, 45, 0] ``` #### **Field-Level Formatting** Use `@JsonFormat` to define a custom date format for individual fields: ```java public class Event { @JsonFormat(pattern = "yyyy-MM-dd") private LocalDate date; @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") private LocalDateTime dateTime; } ``` This ensures consistent formatting even if the global `ObjectMapper` is shared across the application. #### **Global Formatting in Spring Boot** Spring Boot allows configuring date/time formats centrally using `application.yml` or `application.properties`. **YAML Configuration** ```yaml spring: jackson: date-format: yyyy-MM-dd'T'HH:mm:ss time-zone: Asia/Kolkata ``` **Effect** This: * Sets the format for all `java.util.Date` and `Calendar` * Does **not** apply to Java 8 `java.time.*` types unless you register `JavaTimeModule` > To apply it for both, combine Spring config + `JavaTimeModule` registration. #### **Timezone Handling** When serializing or deserializing time-zone-aware types like `ZonedDateTime` or `OffsetDateTime`, Jackson can: * Use default system time zone * Apply a specific time zone via config * Respect explicit time zone in the string **Set Global Time Zone** ```java mapper.setTimeZone(TimeZone.getTimeZone("Asia/Kolkata")); ``` Or via Spring config: ```yaml spring: jackson: time-zone: Asia/Kolkata ``` #### **Deserialization Considerations** When parsing strings, Jackson expects them to match the format defined by: * `@JsonFormat` (if present) * `application.yml` format (if configured) * ISO-8601 (default fallback for `JavaTimeModule`) Mismatched formats will cause `JsonParseException`. ## **Field Naming Strategy** Field naming strategies control how Java field names are mapped to JSON keys. #### **Default: camelCase** ```java firstName → "firstName" ``` #### **snake\_case:** ```java mapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE); ``` ```java firstName → "first_name" ``` #### **Spring Boot Configuration** ```yaml spring: jackson: property-naming-strategy: SNAKE_CASE ``` #### **Use Case** Aligns backend field names with frontend naming conventions, especially in REST APIs. ## **Working with JSON Tree (JsonNode)** Use `JsonNode` when working with **dynamic, partially known, or schema-less** JSON structures. #### **Parsing JSON as Tree** ```java String json = "{\"name\":\"Alice\", \"age\":30}"; JsonNode root = objectMapper.readTree(json); String name = root.get("name").asText(); // "Alice" int age = root.get("age").asInt(); // 30 ``` #### **Modifying Tree** ```java ((ObjectNode) root).put("name", "Bob"); ``` #### **Traversing Nested Nodes** ```java JsonNode address = root.path("address"); String city = address.path("city").asText(); ``` #### **Creating a Tree Manually** ```java ObjectNode node = objectMapper.createObjectNode(); node.put("username", "john"); node.put("active", true); ``` #### **Use Case** Perfect for generic filters, form submissions, or when schema is not static. ## **Annotations for Fine-Grained Control** Jackson provides annotations to control serialization/deserialization behavior per class or field. #### **Common Annotations**
AnnotationPurpose
@JsonPropertyRename JSON property
@JsonIgnoreExclude field
@JsonIncludeConditional inclusion
@JsonFormatFormat dates
@JsonAliasAccept multiple names
@JsonCreatorConstructor/factory-based deserialization
@JsonValueSerialize enum or custom object as a value
#### **Examples** ```java public class Product { @JsonProperty("item_name") private String name; @JsonIgnore private String internalCode; @JsonFormat(pattern = "yyyy-MM-dd") private LocalDate releaseDate; @JsonAlias({"cost", "price_value"}) private double price; } ``` #### **Use Case** * Maintain compatibility with legacy JSON. * Adjust naming or formatting without changing the class model. * Control visibility per API contract. ## **Working with JSON Tree (JsonNode)** Use `JsonNode` when working with **dynamic, partially known, or schema-less** JSON structures. #### **Parsing JSON as Tree** ```java String json = "{\"name\":\"Alice\", \"age\":30}"; JsonNode root = objectMapper.readTree(json); String name = root.get("name").asText(); // "Alice" int age = root.get("age").asInt(); // 30 ``` #### **Modifying Tree** ```java ((ObjectNode) root).put("name", "Bob"); ``` #### **Traversing Nested Nodes** ```java JsonNode address = root.path("address"); String city = address.path("city").asText(); ``` #### **Creating a Tree Manually** ```java ObjectNode node = objectMapper.createObjectNode(); node.put("username", "john"); node.put("active", true); ``` #### **Use Case** Perfect for generic filters, form submissions, or when schema is not static. ## **Exception Handling** Jackson can throw several checked and runtime exceptions during JSON processing. It’s essential to handle these gracefully, especially in REST APIs. #### **Common Exceptions**
ExceptionCause
UnrecognizedPropertyExceptionJSON has fields not found in the POJO
MismatchedInputExceptionType mismatch (e.g., expecting object but got array)
JsonMappingExceptionProblems mapping between JSON and object
JsonParseExceptionMalformed JSON syntax
JsonProcessingExceptionParent class for all exceptions
#### **Spring REST Exception Handler** ```java @ControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(JsonProcessingException.class) public ResponseEntity handleJsonException(JsonProcessingException e) { return ResponseEntity.badRequest().body("Invalid JSON: " + e.getOriginalMessage()); } } ``` ## **Custom Serializers and Deserializers** In most applications, Jackson’s default serialization and deserialization behavior is sufficient. However, certain situations call for **custom logic**, such as: * Encrypting/masking sensitive data * Transforming legacy formats * Applying business rules during serialization or deserialization * Interacting with non-standard or inconsistent APIs Jackson makes this easy with `JsonSerializer` and `JsonDeserializer` interfaces. ### **1. Custom Serializer** #### **Goal:** Control how a Java object or field is written to JSON. #### **Steps:** **a) Create a serializer class:** ```java public class MaskingSerializer extends JsonSerializer { @Override public void serialize(String value, JsonGenerator gen, SerializerProvider serializers) throws IOException { gen.writeString("***"); // Replace actual value with *** } } ``` **b) Use it in our model:** ```java public class User { private String name; @JsonSerialize(using = MaskingSerializer.class) private String ssn; // Sensitive data } ``` **Output:** ```json { "name": "John", "ssn": "***" } ``` ### **2. Custom Deserializer** #### **Goal:** Control how JSON is parsed into a Java object or field. #### **Steps:** **a) Create a deserializer class:** ```java public class UppercaseDeserializer extends JsonDeserializer { @Override public String deserialize(JsonParser p, DeserializationContext ctxt) throws IOException { return p.getText().toUpperCase(); } } ``` **b) Use it in our model:** ```java public class Product { private String code; @JsonDeserialize(using = UppercaseDeserializer.class) private String category; } ``` **Input:** ```json { "code": "PRD-101", "category": "electronics" } ``` **Output:** ```java product.getCategory(); // "ELECTRONICS" ``` ### **3. Apply to Entire Class** We can serialize/deserialize an entire class with custom logic if we need control beyond a field level. #### **Example: Serialize full object to flat string** ```java public class Coordinates { public double lat; public double lng; } ``` **Custom Serializer:** ```java public class CoordinatesSerializer extends JsonSerializer { @Override public void serialize(Coordinates value, JsonGenerator gen, SerializerProvider serializers) throws IOException { gen.writeString(value.lat + "," + value.lng); } } ``` **Use:** ```java @JsonSerialize(using = CoordinatesSerializer.class) public class Coordinates { ... } ``` **Output:** ```json "12.9716,77.5946" ``` ### **4. Global Registration** Instead of annotating each model field or class, we can register custom (de)serializers globally. ```java @Configuration public class JacksonConfig { @Bean public ObjectMapper objectMapper() { ObjectMapper mapper = new ObjectMapper(); SimpleModule module = new SimpleModule(); module.addSerializer(String.class, new MaskingSerializer()); module.addDeserializer(String.class, new UppercaseDeserializer()); mapper.registerModule(module); return mapper; } } ``` > This affects **every** `String` field across the application. Be cautious with global registration. ### **5. Use with Spring Boot's Default ObjectMapper** If we don’t want to override Spring Boot’s default `ObjectMapper` but want to **add custom behavior**, use a `Jackson2ObjectMapperBuilderCustomizer`: ```java @Bean public Jackson2ObjectMapperBuilderCustomizer customizer() { return builder -> { SimpleModule module = new SimpleModule(); module.addSerializer(String.class, new MaskingSerializer()); builder.modules(module); }; } ``` This allows customization **without replacing** the default Spring Boot configuration.