Set Format for Instant Using ObjectMapper

1. Introduction

Formatting dates consistently is essential for maintaining clarity and compatibility in data representation, especially when working with JSON. In this tutorial, we’ll explore various techniques for formatting an Instant field during serialization and parsing it back during deserialization using Jackson’s ObjectMapper. We’ll also discuss the use of @JsonFormat annotations and extending existing serializers and deserializers to achieve full control.

2. Scenario and Setup

To illustrate these techniques, we’ll set up a basic scenario with a predefined date format and DateTimeFormatter:

public interface Instants {

    ZoneOffset TIMEZONE = ZoneOffset.UTC;
    String DATE_FORMAT = "yyyy-MM-dd HH:mm:ss.SSS";
    DateTimeFormatter FORMATTER = DateTimeFormatter.ofPattern(DATE_FORMAT)
      .withZone(ZoneOffset.UTC);
}

For simplicity, we’re using UTC for our timezone. We aim to verify that when using ObjectMapper, we can serialize an Instant field into this format and deserialize it back to the original Instant. So, let’s also include the sample date we’ll use in our tests:

class InstantFormatUnitTest {

    final String DATE_TEXT = "2024-05-27 12:34:56.789";
    final Instant DATE = Instant.from(Instants.FORMATTER.parse(DATE_TEXT));

    // ...
}

Finally, the base for our tests consists of checking if our mapper can serialize an Instant field into the specified format and then deserialize it back to the expected value. We’ll do this by checking if the JSON String contains our expected date text and then if the deserialized field timeStamp matches our DATE object:

void assertSerializedInstantMatchesWhenDeserialized(TimeStampTracker object, ObjectMapper mapper) 
  throws JsonProcessingException {
    String json = mapper.writeValueAsString(object);
    assertTrue(json.contains(DATE_TEXT));

    TimeStampTracker deserialized = mapper.readValue(json, object.getClass());
    assertEquals(DATE, deserialized.getTimeStamp());
}

Since we’ll need different objects to test different approaches, let’s define a simple interface for them:

public interface TimeStampTracker {

    Instant getTimeStamp();
}

3. Full Control With a Custom JsonSerializer

Let’s start with the most standard, universal way to use a specific format to serialize non-standard fields in Jackson, extending JsonSerializer. This class is generic, and we use it to control the serialization of any field. So, let’s write one for Instant types:

public class CustomInstantSerializer extends JsonSerializer<Instant> {

    @Override
    public void serialize(Instant instant, JsonGenerator json, SerializerProvider provider) 
      throws IOException {
        // ...
    }
}

When overriding serialize(), we’re primarily interested in the JsonGenerator parameter, which we use to write the formatted instant value using our formatter:

json.writeString(Instants.FORMATTER.format(instant));

With serialization covered, let’s ensure we can deserialize objects with this specific format.

3.1. Custom JsonDeserializer

For deserialization, we’ll follow a similar route by extending JsonDeserializer:

public class CustomInstantDeserializer extends JsonDeserializer<Instant> {

    @Override
    public Instant deserialize(JsonParser json, DeserializationContext context) 
      throws IOException {
        // ...
    }
}

When overriding deserialize(), we’ll get a JSON parser instead of a generator. Let’s call json.getText(), which holds the field value, and pass it to our formatter for parsing:

return Instant.from(Instants.FORMATTER.parse(json.getText()));

3.2. Using the Custom Serializer and Deserializer

Using our custom serializer and deserializer requires the @JsonSerialize and @JsonDeserialize annotations. Let’s pass our implementations to them:

public class Event implements TimeStampTracker {

    @JsonSerialize(using = CustomInstantSerializer.class)
    @JsonDeserialize(using = CustomInstantDeserializer.class)
    private Instant timeStamp;

    // standard getters and setters
}

Let’s test it, asserting that the generated JSON contains the expected formatted date and that, when deserialized, the instant field matches our original date:

@Test
void givenDefaultMapper_whenUsingCustomSerializerDeserializer_thenExpectedInstantFormat() 
  throws JsonProcessingException {
    Event object = new Event();
    object.setTimeStamp(DATE);

    ObjectMapper mapper = new ObjectMapper();

    assertSerializedInstantMatchesWhenDeserialized(object, mapper);
}

This method is helpful if we have a few classes with Instant fields for dates or want to use a specific serialization/deserialization technique in some classes.

4. Adding the JavaTimeModule Extension

Since Instant isn’t one of the default date types supported by Jackson, we have to add the JavaTimeModule dependency to our pom.xml:

<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>1.17.1</version>
</dependency>

Without it, if we try to serialize a class that contains an Instant field, we’ll get an error:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
  Java 8 date/time type `java.time.Instant` not supported by default

This dependency includes the JavaTimeModule class, which we’ll use later.

4.1. Choosing a Custom Format With @JsonFormat

By default, ObjectMapper serializes date fields as numeric timestamps. When calling disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS), we can turn off this behavior on the JsonMapper.builder(), but it won’t let us set a specific format. This is because calling defaultDateFormat() only works for Date and long values. So, one way to use a particular format is with the @JsonFormat annotation:

public class Session implements TimeStampTracker {

    @JsonFormat(pattern = Instants.DATE_FORMAT, timezone = "UTC")
    private Instant timeStamp;

    // standard getters and setters
}

It’s also essential to set the timezone property. Since we’re using “UTC“, we’ll reuse it here, along with the date format we specified at the beginning in the pattern field.

4.2. Testing Our Solution

Let’s put it all together to test serialization and deserialization:

@Test
void givenTimeModuleMapper_whenJsonFormat_thenExpectedInstantFormat() 
  throws JsonProcessingException {
    Session object = new Session();
    object.setTimeStamp(DATE);

    ObjectMapper mapper = JsonMapper.builder()
      .addModule(new JavaTimeModule())
      .build();

    assertSerializedInstantMatchesWhenDeserialized(object, mapper);
}

Disabling WRITE_DATES_AS_TIMESTAMPS won’t matter since we’re using @JsonFormat, so we won’t deactivate it here.

5. Extending InstantSerializer With a Custom Format

Jackson bundles with serializers for most types, including the InstantSerializer, which provides a singleton we can use with the JavaTimeModule:

JavaTimeModule module = new JavaTimeModule();
module.addSerializer(Instant.class, InstantSerializer.INSTANCE);

Unfortunately, this alternative also locks us from using different formats. And, since InstantSerializer doesn’t contain public constructors, we’ll extend it:

public class GlobalInstantSerializer extends InstantSerializer {

    public GlobalInstantSerializer() {
        super(InstantSerializer.INSTANCE, false, false, Instants.FORMATTER);
    }
}

We’re using the constructor that takes the singleton as the base implementation along with a formatter. We also pass false to useTimestamp and useNanoseconds since we want a specific format for our Instant fields. And this time, we don’t need any annotations in our class:

public class History implements TimeStampTracker {

    private Instant timeStamp;

    // standard getters and setters
}

5.1. Extending InstantDeserializer With a Custom Format

Conversely, to use a specific format when deserializing, we’ll need to extend InstantDeserializer and construct it with the InstantDeserializer.INSTANT constant and our formatter:

public class GlobalInstantDeserializer extends InstantDeserializer<Instant> {

    public GlobalInstantDeserializer() {
        super(InstantDeserializer.INSTANT, Instants.FORMATTER);
    }
}

Notably, unlike the serializer, the deserializer is generic and can take any Temporal type as a return type for deserialization.

5.2. Using Our Implementations of InstantSerializer/InstantDeserializer

Finally, let’s configure the Java Time Module to use our serializer and deserializer and test it:

@Test
void givenTimeModuleMapper_whenSerializingAndDeserializing_thenExpectedInstantFormat() 
  throws JsonProcessingException {
    JavaTimeModule module = new JavaTimeModule();
    module.addSerializer(Instant.class, new GlobalInstantSerializer());
    module.addDeserializer(Instant.class, new GlobalInstantDeserializer());

    History object = new History();
    object.setTimeStamp(DATE);

    ObjectMapper mapper = JsonMapper.builder()
      .addModule(module)
      .build();

    assertSerializedInstantMatchesWhenDeserialized(object, mapper);
}

This solution is the most efficient and flexible because we don’t need to use annotations in our classes, and it works for any class with Instant fields.

6. Conclusion

In this article, we extended Jackson’s built-in serializers and deserializers and got a clear understanding of custom ones. We leveraged these techniques by including the @JsonFormat annotation and using extension modules. Ultimately, we can format Instant fields consistently and according to our specifications. This enhances the readability and compatibility of JSON data and provides flexibility and control over the representation of date and time information across different parts of our application.