Jackson Modules: JavaTimeModule, Parameterized Types & Type Handling

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.json.JsonMapper;
import com.fasterxml.jackson.datatype.jdk8.Jdk8Module;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZonedDateTime;
import java.util.Optional;

public class TimeAndOptional {

    record Booking(LocalDate day, Instant created, ZonedDateTime start, Duration length,
            Optional<String> note) {
    }

    public static void main(String[] args) throws Exception {
        Booking b = new Booking(LocalDate.of(2026, 3, 1), Instant.parse("2026-01-15T09:30:00Z"),
                ZonedDateTime.parse("2026-03-01T14:00:00+01:00[Europe/Oslo]"),
                Duration.ofMinutes(90), Optional.of("window seat"));

        // Without Jdk8Module, Optional is rejected
        ObjectMapper timeOnly = JsonMapper.builder().addModule(new JavaTimeModule())
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS).build();
        try {
            timeOnly.writeValueAsString(b);
        } catch (InvalidDefinitionException e) {
            System.out.println("no Jdk8Module: InvalidDefinitionException for Optional");
        }

        JsonMapper full = JsonMapper.builder()
                .addModule(new JavaTimeModule())
                .addModule(new Jdk8Module())
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
                .disable(SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS)
                .build();
        String json = full.writeValueAsString(b);
        System.out.println("with both modules:\n  " + json);

        Booking back = full.readValue(json, Booking.class);
        System.out.println("zone kept after reading: " + back.start().getZone());
        System.out.println("same instant: "
                + back.start().toInstant().equals(b.start().toInstant())
                + ", equal objects: " + back.equals(b));

        // Keep the zone: write its ID and do not convert to UTC when reading
        ObjectMapper zoned = full.rebuild()
                .enable(SerializationFeature.WRITE_DATES_WITH_ZONE_ID)
                .disable(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE)
                .build();
        String zonedJson = zoned.writeValueAsString(b.start());
        System.out.println("with zone ID: " + zonedJson + ", read back equal: "
                + zoned.readValue(zonedJson, ZonedDateTime.class).equals(b.start()));

        // findAndAddModules registers every module found on the classpath
        ObjectMapper auto = JsonMapper.builder().findAndAddModules().build();
        System.out.println("modules found automatically: " + auto.getRegisteredModuleIds());
    }
}

import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;

public class TimeFormats {

    record Times(Instant created, LocalDate day, LocalDateTime local, LocalTime at) {
    }

    // Per-field formats override the mapper-wide setting
    record Invoice(@JsonFormat(pattern = "dd.MM.yyyy") LocalDate due,
            @JsonFormat(shape = JsonFormat.Shape.NUMBER) Instant paid) {
    }

    public static void main(String[] args) throws Exception {
        Times t = new Times(Instant.parse("2026-01-15T09:30:00.123Z"), LocalDate.of(2026, 3, 1),
                LocalDateTime.of(2026, 3, 1, 14, 5), LocalTime.of(8, 0, 30));

        ObjectMapper timestamps = JsonMapper.builder().addModule(new JavaTimeModule()).build();
        System.out.println("timestamps (default): " + timestamps.writeValueAsString(t));

        ObjectMapper millis = JsonMapper.builder().addModule(new JavaTimeModule())
                .disable(SerializationFeature.WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS).build();
        System.out.println("timestamps as millis: " + millis.writeValueAsString(t));

        ObjectMapper iso = JsonMapper.builder().addModule(new JavaTimeModule())
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS).build();
        System.out.println("ISO-8601 strings:     " + iso.writeValueAsString(t));

        // Reading accepts several forms for the same Instant
        for (String json : new String[] {"\"2026-01-15T09:30:00.123Z\"", "1768469400.123",
                "1768469400123"}) {
            System.out.printf("read %-28s -> %s%n", json, iso.readValue(json, Instant.class));
        }

        // An integer is read as seconds unless nanosecond reading is turned off
        ObjectMapper millisReader = JsonMapper.builder().addModule(new JavaTimeModule())
                .disable(DeserializationFeature.READ_DATE_TIMESTAMPS_AS_NANOSECONDS).build();
        System.out.println("as millis: 1768469400123 -> "
                + millisReader.readValue("1768469400123", Instant.class));

        Invoice inv = new Invoice(LocalDate.of(2026, 4, 30), Instant.parse("2026-04-02T10:00:00Z"));
        String json = iso.writeValueAsString(inv);
        System.out.println("@JsonFormat fields:   " + json);
        System.out.println("read back equal:      "
                + iso.readValue(json, Invoice.class).equals(inv));
    }
}

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.fasterxml.jackson.datatype.jdk8.Jdk8Module;
import java.util.Optional;
import java.util.OptionalInt;

public class OptionalDetails {

    record Profile(String name, Optional<String> nickname, OptionalInt age) {
    }

    public static void main(String[] args) throws Exception {
        JsonMapper mapper = JsonMapper.builder().addModule(new Jdk8Module()).build();

        Profile full = new Profile("Ana", Optional.of("an"), OptionalInt.of(30));
        Profile empty = new Profile("Ben", Optional.empty(), OptionalInt.empty());
        System.out.println("present: " + mapper.writeValueAsString(full));
        System.out.println("empty:   " + mapper.writeValueAsString(empty));

        // NON_ABSENT leaves out nulls and empty Optionals; NON_NULL only nulls
        for (JsonInclude.Include inc : new JsonInclude.Include[] {JsonInclude.Include.NON_NULL,
                JsonInclude.Include.NON_ABSENT}) {
            ObjectMapper m = mapper.rebuild()
                    .defaultPropertyInclusion(JsonInclude.Value.construct(inc, inc)).build();
            System.out.printf("%-10s: %s%n", inc, m.writeValueAsString(empty));
        }

        // Reading: an explicit null and a missing field both give an empty Optional
        System.out.println("null:    " + mapper.readValue(
                "{\"name\":\"Cho\",\"nickname\":null,\"age\":null}", Profile.class));
        System.out.println("missing: " + mapper.readValue("{\"name\":\"Dee\"}", Profile.class));
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.fasterxml.jackson.module.paramnames.ParameterNamesModule;
import java.lang.reflect.Constructor;
import java.lang.reflect.Parameter;

public class ParameterNames {

    // An immutable class with no Jackson annotations at all
    public static class Point {
        private final int x;
        private final int y;

        public Point(int x, int y) {
            this.x = x;
            this.y = y;
        }

        public int getX() {
            return x;
        }

        public int getY() {
            return y;
        }

        @Override
        public String toString() {
            return "Point(" + x + ", " + y + ")";
        }
    }

    public static void main(String[] args) throws Exception {
        Constructor<?> c = Point.class.getConstructor(int.class, int.class);
        for (Parameter p : c.getParameters()) {
            System.out.println("parameter " + p.getName() + ", name in class file: "
                    + p.isNamePresent());
        }

        String json = "{\"x\":3,\"y\":4}";
        try {
            new ObjectMapper().readValue(json, Point.class);
        } catch (Exception e) {
            System.out.println("without module: " + e.getClass().getSimpleName());
        }
        ObjectMapper withNames = JsonMapper.builder()
                .addModule(new ParameterNamesModule()).build();
        System.out.println("with ParameterNamesModule: " + withNames.readValue(json, Point.class));
    }
}

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonDeserializer;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.KeyDeserializer;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializerProvider;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.fasterxml.jackson.databind.module.SimpleModule;
import java.io.IOException;
import java.util.Map;

public class CustomModule {

    // A value type from our own domain, with no Jackson annotations
    record Sku(String code) {
        @Override
        public String toString() {
            return code;
        }
    }

    static class SkuSerializer extends JsonSerializer<Sku> {
        @Override
        public void serialize(Sku v, JsonGenerator g, SerializerProvider p) throws IOException {
            g.writeString(v.code());
        }
    }

    static class SkuDeserializer extends JsonDeserializer<Sku> {
        @Override
        public Sku deserialize(JsonParser p, DeserializationContext c) throws IOException {
            return new Sku(p.getValueAsString().toUpperCase());
        }
    }

    // Map keys are always strings in JSON, so keys need their own deserializer
    static class SkuKeyDeserializer extends KeyDeserializer {
        @Override
        public Object deserializeKey(String key, DeserializationContext c) {
            return new Sku(key.toUpperCase());
        }
    }

    static SimpleModule skuModule() {
        return new SimpleModule("sku-module")
                .addSerializer(Sku.class, new SkuSerializer())
                .addDeserializer(Sku.class, new SkuDeserializer())
                .addKeyDeserializer(Sku.class, new SkuKeyDeserializer());
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper plain = new ObjectMapper();
        System.out.println("no module:  " + plain.writeValueAsString(new Sku("a-1")));

        ObjectMapper mapper = JsonMapper.builder().addModule(skuModule()).build();
        System.out.println("with module: " + mapper.writeValueAsString(new Sku("a-1")));
        Map<Sku, Integer> stock = mapper.readValue("{\"a-1\":5,\"b-2\":0}",
                new TypeReference<Map<Sku, Integer>>() { });
        System.out.println("map with Sku keys: " + stock + ", key type "
                + stock.keySet().iterator().next().getClass().getSimpleName());
        System.out.println("written back: " + mapper.writeValueAsString(stock));

        // Registering a module twice is ignored; it is identified by its type id
        ObjectMapper twice = JsonMapper.builder().addModule(skuModule()).addModule(skuModule())
                .build();
        System.out.println("registered ids: " + twice.getRegisteredModuleIds());

        // Two different modules for the same type: the one added last wins
        SimpleModule loud = new SimpleModule("loud").addSerializer(Sku.class,
                new JsonSerializer<Sku>() {
                    @Override
                    public void serialize(Sku v, JsonGenerator g, SerializerProvider p)
                            throws IOException {
                        g.writeString(v.code().toUpperCase() + "!");
                    }
                });
        ObjectMapper both = JsonMapper.builder().addModule(skuModule()).addModule(loud).build();
        System.out.println("sku-module then loud: " + both.writeValueAsString(new Sku("a-1")));
    }
}

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

public class GenericTypes {

    record Page<T>(int page, List<T> items) {
    }

    record User(String name, int age) {
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        String json = "{\"page\":1,\"items\":[{\"name\":\"Ana\",\"age\":30},"
                + "{\"name\":\"Ben\",\"age\":25}]}";

        // Class literals cannot express Page<User>: the items become LinkedHashMaps
        Page<?> raw = mapper.readValue(json, Page.class);
        Object first = raw.items().get(0);
        System.out.println("Page.class item type: " + first.getClass().getSimpleName());
        try {
            @SuppressWarnings("unchecked")
            Page<User> wrong = (Page<User>) raw;
            String name = wrong.items().get(0).name();            // fails here, not above
            System.out.println(name);
        } catch (ClassCastException e) {
            System.out.println("using it as Page<User>: ClassCastException");
        }

        // TypeReference captures the full generic type
        Page<User> page = mapper.readValue(json, new TypeReference<Page<User>>() { });
        System.out.println("TypeReference item type: "
                + page.items().get(0).getClass().getSimpleName() + ", first name "
                + page.items().get(0).name());

        // JavaType, built at run time, for generic code that receives a Class<T>
        JavaType type = mapper.getTypeFactory().constructParametricType(Page.class, User.class);
        Page<User> viaJavaType = mapper.readValue(json, type);
        System.out.println("JavaType: " + viaJavaType.items());

        Map<String, List<Integer>> scores = mapper.readValue("{\"ana\":[90,85],\"ben\":[70]}",
                new TypeReference<Map<String, List<Integer>>>() { });
        System.out.println("nested generics: " + scores + ", element type "
                + scores.get("ana").get(0).getClass().getSimpleName());
    }
}