JPA 2.2 Support for Java 8 Date/Time Types – JPA 2.2对Java 8日期/时间类型的支持

最后修改: 2019年 1月 20日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

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.

JPA 2.2版本正式引入了对Java 8 日期和时间 API的支持。在此之前，我们要么依靠专有的解决方案，要么只能使用JPA转换器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.

在本教程中，我们将展示如何映射各种Java 8 Date和Time类型。我们将特别关注那些考虑到偏移信息的类型。

2. Maven Dependencies

2.Maven的依赖性

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:

在开始之前，我们需要将JPA 2.2 API纳入项目的classpath。在基于Maven的项目中，我们可以简单地将其依赖性添加到pom.xml文件中。

<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:

此外，为了运行该项目，我们需要一个JPA实现和我们要使用的数据库的JDBC驱动。在本教程中，我们将使用EclipseLink和PostgreSQL数据库。

<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.

请随时在Maven中心查看JPA API、EclipseLink和PostgreSQL JDBC驱动程序的最新版本。

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

当然，我们可以使用其他数据库或JPA实现，如Hibernate。

3. TimeZone Support

3.时区支持

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:

我们可以使用任何数据库，但首先，我们应该检查对这些标准SQL类型的支持，因为JDBC 4.2是基于此。

  • 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.

这里，n是小数秒的精度，在0到9位之间。WITHOUT TIME ZONE是可选的，可以省略。如果WITH TIME ZONE被指定，则需要时区名称或对UTC的偏移。

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.

对于我们的例子，我们选择了PostgreSQL数据库，因为它完全支持SQL类型TIME WITH TIME ZONE。

Note that other databases may not support these types.

请注意，其他数据库可能不支持这些类型。

4. Mapping Date Types Before Java 8

4.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.Time, java.sql.Date, and java.sql.Timestamp, respectively, or to java.util types java.util.Date and java.util.Calendar.

在 Java 8 之前，我们通常需要将通用 SQL 类型 TIME、DATE 和 TIMESTAMP 分别映射到 java.sql.* 类 java.sql.Time、java.sql.Date 和 java.sql.Timestamp 中。时间、java.sql.Date和java.sql.Timestamp，或者是java.util类型java.util.Date和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:

首先，让我们看看如何使用java.sql类型。在这里，我们只是用java.sql类型来定义属性，作为@Entity类的一部分。

@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.

虽然java.sql类型像其他类型一样工作，不需要任何额外的映射，但java.util类型需要指定相应的时间类型。

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

这是通过@Temporal注解完成的，其value属性允许我们使用TemporalType枚举指定相应的JDBC类型。

@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.

注意，如果我们使用Hibernate作为实现，这并不支持将Calendar映射到TIME。

Similarly, we can use the Calendar class:

同样地，我们可以使用Calendar类。

@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.

这些类型都不支持时区或偏移。为了处理这些信息，我们传统上不得不存储UTC时间。

5. Mapping Java 8 Date Types

5.映射Java 8的日期类型

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.

Java 8引入了java.time包，JDBC 4.2 API增加了对额外SQL类型TIMESTAMP WITH TIME ZONE和TIME WITH TIME ZONE的支持。

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

我们现在可以将JDBC类型TIME，DATE，和TIMESTAMP映射到java.time类型 – LocalTime， LocalDate，和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:

此外，我们还通过OffsetTime和OffsetDateTime类支持将本地时区偏移到UTC。

@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.

相应的映射列类型应该是TIME WITH TIME ZONE和TIMESTAMP WITH TIME ZONE。不幸的是，并非所有数据库都支持这两种类型。

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.

我们可以看到，JPA支持这五个类作为基本类型，而且不需要额外的信息来区分日期和/或时间信息。

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

在保存了一个新的实体类的实例后，我们可以检查数据是否已经被正确插入。

date time

6. Conclusion

6.结论

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.

在Java 8和JPA 2.2之前，开发者通常需要在持久化之前将日期/时间类型转换为UTC。现在JPA 2.2通过支持对UTC的偏移和利用JDBC 4.2对时区的支持，开箱即支持这一功能。

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

这些样本的完整源代码可以在Github上找到over。