Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

NPI – JPA Buddy – JPA (partner)
announcement - icon

JPA is huge! It covers nearly every aspect of communication between relational databases and the Java application and is deeply integrated into all major frameworks.

If you're using IntelliJ, JPA Buddy is super helpful. The plugin gently guides you through the subtleties of the most popular JPA implementations, visually reminds you of JPA features, generates code that follows best practices, and integrates intelligent inspections to improve your existing persistence code.

More concretely, it provides powerful tooling to generate Spring Data JPA repositories and methods, Flyway Versioned Migrations, Liquibase Differential Changelogs, DDL and SQL statements, DTO objects, and MapStruct interfaces.

Oh, and it actually generates JPA entities from an existing database and gradually update the data model as the database evolves! Yeah.

>> Become a lot more productive with JPA Buddy

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:

>> GET ACCESS NOW

November Discount Launch 2022 – TEMP TOP (NPI)
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:

>> GET ACCESS NOW

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 2.2 API to the project classpath. In a Maven based project, we can simply add its dependency to our pom.xml file:

<dependency>
    <groupId>javax.persistence</groupId>
    <artifactId>javax.persistence-api</artifactId>
    <version>2.2</version>
</dependency>

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>2.7.4</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.2.5</version>
    <scope>runtime</scope>
    <type>bundle</type>
</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 the java.sql.* classes java.sql.Timejava.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 the 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 the 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:

date time

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.

The full source code for these samples can be found over on Github.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:

>> GET ACCESS NOW

Persistence footer banner
Comments are closed on this article!