JPA Support for java.time Types

1. Overview

The JPA 2.2 version has officially introduced the support for Java 8 Date and Time API. Before that, either we had to rely on a proprietary solution, or we had to use the JPA Converter API.

In this tutorial, we’ll show how to map the various Java 8 Date and Time types. We’ll especially focus on the ones that take into account the offset information.

2. Maven Dependencies

Before we start, we need to include the JPA 3.1 API in the project classpath. In a Maven-based project, we can simply add its dependency to our pom.xml file:

<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <version>3.1.0</version>
</dependency>

NOTE: If we include the hibernate-core dependency the jakarta persistence will be automatically fetched as a transient dependency and we will not need to add it explicitly.

Additionally, to run the project, we need a JPA implementation and the JDBC driver of the database that we’ll be working with. In this tutorial, we’ll use EclipseLink and the PostgreSQL database:

<dependency>
    <groupId>org.eclipse.persistence</groupId>
    <artifactId>eclipselink</artifactId>
    <version>4.0.1</version>
    <scope>runtime</scope>
    <exclusions>
      <exclusion>
         <groupId>jakarta.xml.bind</groupId>
         <artifactId>jakarta.xml.bind-api</artifactId>
      </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.5.4</version>
    <scope>runtime</scope>
</dependency>

Feel free to check the latest versions of JPA API, EclipseLink, and PostgreSQL JDBC driver on Maven Central.

Of course, we can use other databases or JPA implementations like Hibernate.

3. TimeZone Support

We can work with any database, but first, we should check the support for these Standard SQL Types, as the JDBC 4.2 is based on:

• TIMESTAMP(n) WITH TIME ZONE
• TIMESTAMP(n) WITHOUT TIME ZONE
• TIME(n) WITH TIME ZONE
• TIME(n) WITHOUT TIME ZONE

Here, n is the fractional seconds precision and is between 0 and 9 digits. WITHOUT TIME ZONE is optional and can be omitted. If WITH TIME ZONE is specified, the timezone name or the offset to UTC is required.

We can represent the timezone in one of these two formats:

• Timezone name
• Offset from UTC or the letter Z for UTC

For our example, we’ve chosen the PostgreSQL database thanks to its full support for the SQL Type TIME WITH TIME ZONE.

Note that other databases may not support these types.

4. Mapping Date Types Before Java 8

Before Java 8, we usually had to map the generic SQL types TIME, DATE, and TIMESTAMP, to either java.sql.* classes java.sql.Time, java.sql.Date, and java.sql.Timestamp, respectively, or to java.util types java.util.Date and java.util.Calendar.

First, let’s see how to use the java.sql types. Here, we’re simply defining the attributes with java.sql types as part of an @Entity class:

@Entity
public class JPA22DateTimeEntity {

    private java.sql.Time sqlTime;
    private java.sql.Date sqlDate;
    private java.sql.Timestamp sqlTimestamp;
    
    // ...
}

While the java.sql types work like any other types without any additional mapping, the java.util types need to specify the corresponding temporal types.

This is done through the @Temporal annotation whose value attribute allows us to specify the corresponding JDBC type, using the TemporalType enumeration:

@Temporal(TemporalType.TIME)
private java.util.Date utilTime;

@Temporal(TemporalType.DATE)
private java.util.Date utilDate;

@Temporal(TemporalType.TIMESTAMP)
private java.util.Date utilTimestamp;

Note that if we’re using Hibernate as an implementation, this doesn’t support mapping Calendar to TIME.

Similarly, we can use the Calendar class:

@Temporal(TemporalType.TIME)
private Calendar calendarTime;

@Temporal(TemporalType.DATE)
private Calendar calendarDate;

@Temporal(TemporalType.TIMESTAMP)
private Calendar calendarTimestamp;

None of these types have support for the timezone or the offset. To deal with those pieces of information, we traditionally had to store the UTC time.

5. Mapping Java 8 Date Types

Java 8 has introduced java.time packages and the JDBC 4.2 API added support for the additional SQL types TIMESTAMP WITH TIME ZONE and TIME WITH TIME ZONE.

We can now map the JDBC Types TIME, DATE, and TIMESTAMP to java.time types – LocalTime, LocalDate, and LocalDateTime:

@Column(name = "local_time", columnDefinition = "TIME")
private LocalTime localTime;

@Column(name = "local_date", columnDefinition = "DATE")
private LocalDate localDate;

@Column(name = "local_date_time", columnDefinition = "TIMESTAMP")
private LocalDateTime localDateTime;

Additionally, we have support for the offset local timezone to UTC through the OffsetTime and OffsetDateTime classes:

@Column(name = "offset_time", columnDefinition = "TIME WITH TIME ZONE")
private OffsetTime offsetTime;

@Column(name = "offset_date_time", columnDefinition = "TIMESTAMP WITH TIME ZONE")
private OffsetDateTime offsetDateTime;

The corresponding mapped column types should be TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE. Unfortunately, not all databases support these two types.

As we can see, JPA supports these five classes as basic types, and there’s no additional information needed to distinguish between the date and/or the time information.

After saving a new instance of our entity class, we can check that data has been inserted correctly:

6. Conclusion

Before Java 8 and JPA 2.2, developers usually had to convert date/time types to UTC before persisting them. JPA 2.2 now supports this feature out of the box by supporting the offset to UTC and by leveraging JDBC 4.2 support for the timezone.