Map LocalDateTime to Instant in MapStruct

1. Overview

When working with dates and times in Java, we often encounter different formats, such as LocalDateTime and Instant. While LocalDateTime represents a date-time without a time zone, Instant represents a specific point in time, usually with reference to the epoch (January 1, 1970, 00:00:00 UTC). In many scenarios, we need to map between these two types. Fortunately, MapStruct, a powerful Java mapping framework, allows us to do this easily.

In this tutorial, we’ll learn how to map LocalDateTime to Instant in MapStruct.

2. Understanding LocalDateTime and Instant

There are several reasons why we might need to map LocalDateTime to Instant.

LocalDateTime is useful for representing events that occur at a specific local time, without considering time zones. We commonly use it to store timestamps in databases and log files. LocalDateTime is a good choice for applications where all users operate in the same time zone.

Instant is great for tracking global events, ensuring time zone consistency and providing a reliable format for interacting with external systems or APIs. In addition, it’s also useful for storing timestamps in a database with a need for time zone consistency.

We’ll deal with LocalDateTime and Instant values and convert them frequently.

3. Mapping Scenario

Let’s suppose that we’re implementing an order processing service. We have two flavours of orders – order and local order. Order uses Instant to support global order processing whereas the local order uses LocalDateTime to represent the local time.

Here is the implementation of the order model:

public class Order {
    private Long id;
    private Instant created;
    // other fields
    // getters and setters
}

Then, we have the implementation of the local order:

public class LocalOrder {
    private Long id;
    private LocalDateTime created;
    // other fields
    // getters and setters
}

4. Mapping LocalDateTime to Instant

Let’s now learn how to implement the mapper to convert LocalDateTime to Instant.

Let’s start with the OrderMapper interface: :

@Mapper
public interface OrderMapper {
    OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);
 
    ZoneOffset DEFAULT_ZONE = ZoneOffset.UTC;
    @Named("localDateTimeToInstant")
    default Instant localDateTimeToInstant(LocalDateTime localDateTime) {
        return localDateTime.toInstant(DEFAULT_ZONE);
    }
    @Mapping(target = "id", source = "id")
    @Mapping(target = "created", source = "created", qualifiedByName = "localDateTimeToInstant")
    Order toOrder(LocalOrder source);
}

This OrderMapper interface is a MapStruct mapper that converts a LocalOrder object to an Order object while handling a custom conversion for date-time fields. It declares a constant DEFAULT_ZONE with a value of ZoneOffset.UTC, which represents the UTC timezone.

The localDateTimeToInstant() method, annotated with @Named, converts a LocalDateTime into an Instant using the specified ZoneOffset.

The toOrder() method maps LocalOrder to Order. It uses @Mapping to define how fields are mapped. The id field is directly mapped from source to target. For the created field, it applies the custom localDateTimeToInstant() method by specifying qualifiedByName = “localDateTimeToInstant”. This ensures that the LocalDateTime in LocalOrder is properly converted to Instant in Order.

MapStruct uses conventions for mapping data types. Mapping complex objects with nested properties or converting between certain data types can raise errors. Default methods in a MapStruct interface can define explicit conversions between types that MapStruct doesn’t natively support. These methods resolve ambiguities and provide necessary instructions for conversion. That ensures accurate and reliable mappings. In addition, they’re also useful for complex or nested property mapping. In conclusion, they’re a best practice for maintaining clean, maintainable code in MapStruct mappings.

Let’s test our mapper:

class OrderMapperUnitTest {
    private OrderMapper mapper = OrderMapper.INSTANCE;
    
    @Test
    void whenLocalOrderIsMapped_thenGetsOrder() {
        LocalDateTime localDateTime = LocalDateTime.now();
        long sourceEpochSecond = localDateTime.toEpochSecond(OrderMapper.DEFAULT_ZONE);
        LocalOrder localOrder = new LocalOrder();
        localOrder.setCreated(localDateTime);
      
        Order target = mapper.toOrder(localOrder);
      
        Assertions.assertNotNull(target);
        long targetEpochSecond = target.getCreated().getEpochSecond();
        Assertions.assertEquals(sourceEpochSecond, targetEpochSecond);
    }
}

This test case checks if OrderMapper correctly converts a LocalOrder to an Order, focusing on the created field mapping from LocalDateTime to Instant. It creates a LocalDateTime, calculates its epoch second value, sets it to a new LocalOrder, maps it to an Order, and checks if the result isn’t null. Finally, it compares the epoch second values between the LocalDateTime of LocalOrder and the Instant of Order. If they match, the test passes.

5. Mapping Instant to LocalDateTime

Now we’ll see how to map the Instant back to LocalDateTime:

@Mapper
public interface OrderMapper {
    OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);
    ZoneOffset DEFAULT_ZONE = ZoneOffset.UTC;
    @Named("instantToLocalDateTime")
    default LocalDateTime instantToLocalDateTime(Instant instant) {
        return LocalDateTime.ofInstant(instant, DEFAULT_ZONE);
    }
  
    @Mapping(target = "id", source = "id")
    @Mapping(target = "created", source = "created", qualifiedByName = "instantToLocalDateTime")
    LocalOrder toLocalOrder(Order source);
}

The OrderMapper now defines a mapping that converts Order objects to LocalOrder objects. It includes a custom mapping method, instantToLocalDateTime(), which converts Instant to LocalDateTime using a predefined ZoneOffset (UTC).

The @Mapping annotations in toLocalOrder() indicate that the id field is directly mapped from Order to LocalOrder. Then it uses the custom method (qualifiedByName = “instantToLocalDateTime”) for the created field and converts Instant to LocalDateTime.

Let’s verify our mapping:

@Test
void whenOrderIsMapped_thenGetsLocalOrder() {
    Instant source = Instant.now();
    long sourceEpochSecond = source.getEpochSecond();
    Order order = new Order();
    order.setCreated(source);
    
    LocalOrder target = mapper.toLocalOrder(order);
    
    Assertions.assertNotNull(target);
    long targetEpochSecond = target.getCreated().toEpochSecond(OrderMapper.DEFAULT_ZONE);
    Assertions.assertEquals(sourceEpochSecond, targetEpochSecond);
}

This test verifies that the OrderMapper correctly converts an Order object to a LocalOrder object, focusing on mapping Instant to LocalDateTime.

The test creates an Instant object with the current timestamp and calculates its epoch second. It then creates an Order object and sets the Instant value to its created field.

The test maps the Order object to LocalOrder using mapper.toLocalOrder(). It checks that the resulting LocalOrder isn’t null and verifies that the epoch second of the LocalDateTime in LocalOrder matches the epoch second of the Instant in Order, ensuring correct mapping with the specified ZoneOffset.

6. Conclusion

In this article, we learned how to map LocalDateTime to Instant and vice versa using MapStruct. We saw how to create custom mapping methods with @Named to convert between these types, along with the correct use of @Mapping and qualifiedByName. This approach ensures smooth data transformation and time zone consistency in Java applications.

As always, the complete code samples for this article can be found over on GitHub.