Jackson ObjectMapper Configuration: Features, Builders & ObjectReader/Writer

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.exc.MismatchedInputException;
import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

public class Basics {

    // A classic JavaBean: Jackson finds properties through public getters and setters
    public static class Customer {
        private String first;
        private String last;
        private boolean active;
        private String internalNote = "not exposed";   // no getter, so not serialized

        public Customer() {
        }

        public Customer(String first, String last, boolean active) {
            this.first = first;
            this.last = last;
            this.active = active;
        }

        public String getFirst() {
            return first;
        }

        public void setFirst(String first) {
            this.first = first;
        }

        public String getLast() {
            return last;
        }

        public void setLast(String last) {
            this.last = last;
        }

        public boolean isActive() {
            return active;
        }

        public void setActive(boolean active) {
            this.active = active;
        }

        public String getFullName() {                 // derived getter: becomes a property
            return first + " " + last;
        }

        String note() {
            return internalNote;
        }
    }

    // A record: Jackson 2.12+ uses the components and the canonical constructor
    record Point(int x, int y) {
    }

    // No default constructor and no creator annotation
    public static class Money {
        private final long cents;

        public Money(long cents) {
            this.cents = cents;
        }

        public long getCents() {
            return cents;
        }
    }

    // The fix: tell Jackson which constructor to call and how parameters map to JSON
    public static class Money2 {
        private final long cents;

        @JsonCreator
        public Money2(@JsonProperty("cents") long cents) {
            this.cents = cents;
        }

        public long getCents() {
            return cents;
        }
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();

        String json = mapper.writeValueAsString(new Customer("Ana", "Silva", true));
        System.out.println("bean   -> " + json);
        Customer back = mapper.readValue(
                "{\"first\":\"Ben\",\"last\":\"Ode\",\"active\":false}", Customer.class);
        System.out.println("bean   <- " + back.getFullName() + ", active=" + back.isActive()
                + ", note=" + back.note());

        String pj = mapper.writeValueAsString(List.of(new Point(1, 2), new Point(3, 4)));
        System.out.println("record -> " + pj);
        Point[] points = mapper.readValue(pj, Point[].class);
        System.out.println("record <- " + points[1]);

        // Writing to a file and reading bytes back
        Path file = Files.createTempFile("customer", ".json");
        mapper.writeValue(file.toFile(), new Customer("Cho", "Kim", true));
        byte[] bytes = Files.readAllBytes(file);
        System.out.println("file has " + bytes.length + " bytes: " + new String(bytes,
                StandardCharsets.UTF_8));
        try {
            mapper.readValue(bytes, Customer.class);   // fullName has no setter
        } catch (UnrecognizedPropertyException e) {
            System.out.println("read back: UnrecognizedPropertyException for \""
                    + e.getPropertyName() + "\", known " + e.getKnownPropertyIds());
        }
        Files.delete(file);

        // Serializing works, deserializing needs a way to construct the object
        System.out.println("Money  -> " + mapper.writeValueAsString(new Money(1999)));
        try {
            mapper.readValue("{\"cents\":1999}", Money.class);
        } catch (MismatchedInputException e) {
            System.out.println("Money  <- " + e.getOriginalMessage());
        }
        System.out.println("Money2 <- cents=" + mapper.readValue("{\"cents\":1999}",
                Money2.class).getCents());
    }
}

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.databind.exc.InvalidDefinitionException;
import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import java.time.LocalDate;
import java.util.List;

public class MapperBasics {

    record Order(long id, String customer, List<String> items, LocalDate placed) {
    }

    record Product(String sku, double price) {
    }

    public static void main(String[] args) throws Exception {
        // Out of the box, Jackson 2 cannot handle java.time types
        ObjectMapper plain = new ObjectMapper();
        Order order = new Order(42, "Ana", List.of("pen", "pad"), LocalDate.of(2026, 1, 15));
        try {
            plain.writeValueAsString(order);
        } catch (InvalidDefinitionException e) {
            System.out.println("no JavaTimeModule: InvalidDefinitionException");
        }

        // With the module, dates are written as arrays unless that feature is turned off
        ObjectMapper withTime = JsonMapper.builder().addModule(new JavaTimeModule()).build();
        System.out.println("module only:     " + withTime.writeValueAsString(order));
        ObjectMapper iso = JsonMapper.builder().addModule(new JavaTimeModule())
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS).build();
        String json = iso.writeValueAsString(order);
        System.out.println("ISO dates:       " + json);
        System.out.println("round trip equal: " + iso.readValue(json, Order.class).equals(order));

        // Unknown properties fail by default
        String newerApi = "{\"sku\":\"A1\",\"price\":9.5,\"currency\":\"EUR\"}";
        try {
            plain.readValue(newerApi, Product.class);
        } catch (UnrecognizedPropertyException e) {
            System.out.println("unknown \"" + e.getPropertyName()
                    + "\": UnrecognizedPropertyException");
        }
        ObjectMapper lenient = JsonMapper.builder()
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES).build();
        System.out.println("lenient mapper:  " + lenient.readValue(newerApi, Product.class));

        // Missing primitive fields silently become 0 unless this feature is on
        String missingPrice = "{\"sku\":\"B2\"}";
        System.out.println("missing price:   " + plain.readValue(missingPrice, Product.class));
        ObjectMapper strict = JsonMapper.builder()
                .enable(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES).build();
        try {
            strict.readValue("{\"sku\":\"B2\",\"price\":null}", Product.class);
        } catch (Exception e) {
            System.out.println("null for a double with FAIL_ON_NULL_FOR_PRIMITIVES: "
                    + e.getClass().getSimpleName());
        }
    }
}

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.MapperFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.databind.json.JsonMapper;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;

public class Features {

    enum Status { ACTIVE, SUSPENDED }

    record Account(String userName, Status status, int loginCount, List<String> roles) {
    }

    static class Empty {
    }

    public static void main(String[] args) throws Exception {
        Account acc = new Account("ana", Status.ACTIVE, 3, List.of("admin"));
        ObjectMapper plain = new ObjectMapper();
        System.out.println("default:        " + plain.writeValueAsString(acc));

        // Naming strategy and alphabetical order, set once on the builder
        ObjectMapper snake = JsonMapper.builder()
                .propertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
                .enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
                .build();
        System.out.println("snake + sorted: " + snake.writeValueAsString(acc));

        // Map keys keep insertion order unless ORDER_MAP_ENTRIES_BY_KEYS is on
        Map<String, Integer> scores = new java.util.LinkedHashMap<>();
        scores.put("zoe", 1);
        scores.put("adam", 2);
        ObjectMapper ordered = JsonMapper.builder()
                .enable(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS).build();
        System.out.println("map default:    " + plain.writeValueAsString(scores));
        System.out.println("map ordered:    " + ordered.writeValueAsString(scores));
        System.out.println("TreeMap equal:  " + ordered.writeValueAsString(new TreeMap<>(scores))
                .equals(ordered.writeValueAsString(scores)));

        // An object with no properties fails by default
        try {
            plain.writeValueAsString(new Empty());
        } catch (Exception e) {
            System.out.println("empty bean:     " + e.getClass().getSimpleName());
        }
        ObjectMapper allowEmpty = JsonMapper.builder()
                .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS).build();
        System.out.println("empty allowed:  " + allowEmpty.writeValueAsString(new Empty()));

        // Lenient reading: a single value where an array is expected, case, unknown enums
        String loose = "{\"USERNAME\":\"ben\",\"status\":\"DELETED\",\"loginCount\":1,"
                + "\"roles\":\"user\"}";
        try {
            plain.readValue(loose, Account.class);
        } catch (JsonMappingException e) {
            System.out.println("strict read:    " + e.getClass().getSimpleName() + " at "
                    + e.getPathReference());
        }
        ObjectMapper lenient = JsonMapper.builder()
                .enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES)
                .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
                .enable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL)
                .build();
        System.out.println("lenient read:   " + lenient.readValue(loose, Account.class));

        // Floating point numbers in untyped JSON
        String price = "{\"price\":0.1000000000000000055511151231257827}";
        System.out.println("as Double:      " + plain.readValue(price, Map.class));
        ObjectMapper exact = JsonMapper.builder()
                .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS).build();
        Map<?, ?> m = exact.readValue(price, Map.class);
        System.out.println("as BigDecimal:  " + m + " (" + m.get("price").getClass()
                .getSimpleName() + ")");

        // rebuild() starts a new builder from an existing mapper's settings
        ObjectMapper pretty = ((JsonMapper) snake).rebuild()
                .enable(SerializationFeature.INDENT_OUTPUT).build();
        System.out.println("rebuilt + INDENT_OUTPUT:\n" + pretty.writeValueAsString(acc));
        System.out.println("original unchanged: "
                + !snake.isEnabled(SerializationFeature.INDENT_OUTPUT));
    }
}

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectReader;
import com.fasterxml.jackson.databind.ObjectWriter;
import com.fasterxml.jackson.databind.json.JsonMapper;
import java.util.List;
import java.util.Map;
import java.util.stream.IntStream;

public class ReadersWriters {

    record User(String name, String email, Integer age) {
    }

    public static class Settings {
        public String theme = "light";
        public int fontSize = 12;
    }

    // One configured mapper for the whole application
    static final ObjectMapper MAPPER = JsonMapper.builder()
            .defaultPropertyInclusion(JsonInclude.Value.construct(
                    JsonInclude.Include.NON_NULL, JsonInclude.Include.NON_NULL))
            .build();

    public static void main(String[] args) throws Exception {
        User ana = new User("Ana", null, 30);

        // ObjectWriter: an immutable, per-use variation of the mapper's settings
        ObjectWriter pretty = MAPPER.writerWithDefaultPrettyPrinter();
        System.out.println("compact: " + MAPPER.writeValueAsString(ana));
        System.out.println("pretty:\n" + pretty.writeValueAsString(ana));

        // ObjectReader bound to a generic type, created once and reused
        ObjectReader listReader = MAPPER.readerFor(new TypeReference<List<User>>() { });
        List<User> users = listReader.readValue(
                "[{\"name\":\"Ben\",\"age\":25},{\"name\":\"Cho\",\"email\":\"c@x.io\"}]");
        System.out.println("list of records: " + users);

        // Without type information, JSON becomes Maps, Lists and boxed numbers
        Object untyped = MAPPER.readValue("{\"a\":1,\"b\":[true,2.5]}", Object.class);
        System.out.println("untyped: " + untyped + " as " + untyped.getClass().getSimpleName());
        Map<?, ?> map = (Map<?, ?>) untyped;
        System.out.println("  \"a\" is " + map.get("a").getClass().getSimpleName());

        // The configured mapper is thread-safe: use it from many threads at once
        long ok = IntStream.range(0, 10_000).parallel().filter(i -> {
            try {
                User u = MAPPER.readValue(MAPPER.writeValueAsString(new User("u" + i, null, i)),
                        User.class);
                return u.age() == i;
            } catch (Exception e) {
                return false;
            }
        }).count();
        System.out.println("parallel round trips correct: " + ok + " of 10000");

        // convertValue: object to object through Jackson's model, without JSON text
        Map<?, ?> asMap = MAPPER.convertValue(ana, Map.class);
        System.out.println("convertValue to Map: " + asMap);
        User fromMap = MAPPER.convertValue(Map.of("name", "Dee", "age", 41), User.class);
        System.out.println("convertValue to User: " + fromMap);

        // readerForUpdating: apply a partial JSON document to an existing object
        Settings settings = new Settings();
        MAPPER.readerForUpdating(settings).readValue("{\"theme\":\"dark\"}");
        System.out.println("updated settings: theme=" + settings.theme + ", fontSize="
                + settings.fontSize);
    }
}

import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.core.StreamReadFeature;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;
import java.util.List;

public class Errors {

    record Line(String sku, int qty) {
    }

    record Order(long id, List<Line> lines) {
    }

    static void tryRead(ObjectMapper mapper, String label, String json) {
        try {
            mapper.readValue(json, Order.class);
            System.out.println(label + ": ok");
        } catch (JsonProcessingException e) {
            System.out.println(label + ": " + e.getClass().getSimpleName());
            System.out.println("  message:  " + e.getOriginalMessage().lines().findFirst()
                    .orElse(""));
            System.out.println("  location: line " + e.getLocation().getLineNr() + ", column "
                    + e.getLocation().getColumnNr());
            if (e instanceof JsonMappingException jme) {
                String path = jme.getPathReference();
                System.out.println("  path:     " + (path.isEmpty() ? "(root)" : path));
            }
        }
    }

    public static void main(String[] args) {
        ObjectMapper mapper = new ObjectMapper();
        tryRead(mapper, "missing comma", "{\"id\":1 \"lines\":[]}");
        tryRead(mapper, "wrong type  ", """
                {"id": 7,
                 "lines": [{"sku": "A1", "qty": 2},
                           {"sku": "B2", "qty": "two"}]}""");
        tryRead(mapper, "array for object", "[1, 2]");

        // Since Jackson 2.16 the source text is left out of messages by default
        ObjectMapper withSource = JsonMapper.builder()
                .enable(StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION).build();
        try {
            withSource.readValue("{\"id\":true}", Order.class);
        } catch (JsonProcessingException e) {
            String full = e.getMessage();
            System.out.println("with source: " + full.substring(full.indexOf("[Source")));
        }

        // The exception hierarchy: all are IOExceptions
        for (Class<?> c = com.fasterxml.jackson.databind.exc.InvalidFormatException.class;
                c != Exception.class; c = c.getSuperclass()) {
            System.out.print(c.getSimpleName() + " > ");
        }
        System.out.println("Exception");
        System.out.println("JsonParseException is a JsonMappingException: "
                + JsonMappingException.class.isAssignableFrom(JsonParseException.class));
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectReader;
import com.fasterxml.jackson.databind.ObjectWriter;
import java.util.List;

public class MapperSpeed {

    record Item(String sku, int qty, double price) {
    }

    record Order(long id, String customer, List<Item> items) {
    }

    interface Task {
        void run() throws Exception;
    }

    static final int N = 20_000;
    static long sink;

    static long bestOf3(Task task) throws Exception {
        long best = Long.MAX_VALUE;
        task.run();                                           // warm-up run, not counted
        for (int run = 0; run < 3; run++) {
            long t0 = System.nanoTime();
            task.run();
            best = Math.min(best, System.nanoTime() - t0);
        }
        return best;
    }

    public static void main(String[] args) throws Exception {
        Order order = new Order(42, "Ana", List.of(new Item("A1", 2, 9.5), new Item("B2", 1, 3)));
        ObjectMapper shared = new ObjectMapper();
        ObjectWriter writer = shared.writerFor(Order.class);
        ObjectReader reader = shared.readerFor(Order.class);
        String json = shared.writeValueAsString(order);
        System.out.println(json.length() + "-char order, " + N + " operations per run");

        long fresh = bestOf3(() -> {
            for (int i = 0; i < N / 10; i++) {                // 10x fewer: it is slow
                sink += new ObjectMapper().writeValueAsString(order).length();
            }
        }) * 10;
        long reuse = bestOf3(() -> {
            for (int i = 0; i < N; i++) {
                sink += shared.writeValueAsString(order).length();
            }
        });
        long viaWriter = bestOf3(() -> {
            for (int i = 0; i < N; i++) {
                sink += writer.writeValueAsString(order).length();
            }
        });
        long read = bestOf3(() -> {
            for (int i = 0; i < N; i++) {
                sink += shared.readValue(json, Order.class).items().size();
            }
        });
        long viaReader = bestOf3(() -> {
            for (int i = 0; i < N; i++) {
                sink += reader.<Order>readValue(json).items().size();
            }
        });
        System.out.printf("write, new mapper each time: %6.0f ns per call%n", fresh / (double) N);
        System.out.printf("write, shared mapper:        %6.0f ns per call%n", reuse / (double) N);
        System.out.printf("write, shared ObjectWriter:  %6.0f ns per call%n",
                viaWriter / (double) N);
        System.out.printf("read,  shared mapper:        %6.0f ns per call%n", read / (double) N);
        System.out.printf("read,  shared ObjectReader:  %6.0f ns per call%n",
                viaReader / (double) N);
        System.out.printf("new mapper is %.0fx slower than reuse%n", fresh / (double) reuse);
        if (sink == 0) {
            System.out.println("nothing was measured");
        }
    }
}

import java.time.LocalDate;
import java.util.List;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.json.JsonMapper;

// The same calls with Jackson 3 (package tools.jackson)
public class Jackson3 {

    record Order(long id, String customer, List<String> items, LocalDate placed) {
    }

    record Product(String sku, double price) {
    }

    public static class Bean {
        public int zeta = 1;
        public int alpha = 2;
    }

    static void read(ObjectMapper mapper, String label, String json) {
        try {
            System.out.println(label + mapper.readValue(json, Product.class));
        } catch (JacksonException e) {
            System.out.println(label + e.getClass().getSimpleName());
        }
    }

    public static void main(String[] args) {
        ObjectMapper mapper = JsonMapper.builder().build();
        Order order = new Order(42, "Ana", List.of("pen", "pad"), LocalDate.of(2026, 1, 15));

        // java.time support is built in, and dates are ISO strings by default
        String json = mapper.writeValueAsString(order);              // no checked exception
        System.out.println("Jackson 3 default: " + json);
        System.out.println("round trip equal:  " + mapper.readValue(json, Order.class)
                .equals(order));
        System.out.println("field order:       " + mapper.writeValueAsString(new Bean()));

        read(mapper, "unknown property:  ", "{\"sku\":\"A1\",\"price\":9.5,\"currency\":\"EUR\"}");
        read(mapper, "missing price:     ", "{\"sku\":\"B2\"}");
        read(mapper, "null price:        ", "{\"sku\":\"B2\",\"price\":null}");
        System.out.println("FAIL_ON_NULL_FOR_PRIMITIVES on: "
                + mapper.isEnabled(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES));

        // Mappers are immutable; rebuild() gives a builder with the same settings
        ObjectMapper pretty = mapper.rebuild().enable(SerializationFeature.INDENT_OUTPUT).build();
        System.out.println("rebuilt mapper indents: "
                + pretty.writeValueAsString(new Product("C3", 1.0)).contains("\n"));
        System.out.println("JacksonException is unchecked: "
                + RuntimeException.class.isAssignableFrom(JacksonException.class));
    }
}