Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

5.8. Hibernate 和 Jakarta Persistence 迁移更改

5.8.1. Hibernate ORM 3.0
复制链接

在 JBoss EAP 6.4 中使用 Hibernate ORM 3 的整合类已经从 JBoss EAP 7 中移除。如果您的应用程序仍然使用 Hibernate ORM 3 库，则强烈建议您迁移应用程序以使用 Hibernate ORM 5 作为 Hibernate ORM 5 作为 Hibernate ORM 3，无需大量工作。如果您无法迁移到 Hibernate ORM 5，您必须为 Hibernate ORM 3 JARs 定义自定义 JBoss 模块，并不包括应用程序中的 Hibernate ORM 5 类。

5.8.2. Hibernate ORM 4.0 - 4.3
复制链接

如果您的应用程序需要启用第二级别的缓存，请注意 Infinispan 8.x 与 Hibernate ORM 5.0 集成。支持将 Infinispan 用作 Hibernate 2nd 级缓存提供商，然后被移到 Hibernate ORM 5.3 中的 Infinispan 项目，因此，Ehiber n-infinispan 模块已从该版本丢弃。

使用 Hibernate ORM 4.x 编写的应用程序仍然可以使用 Hibernate ORM 4.x。您必须为 Hibernate ORM 4.x JARs 定义自定义 JBoss 模块，并从应用程序中排除 Hibernate ORM 5 类。但是，强烈建议您重写应用程序代码以使用 Hibernate ORM 5。有关迁移到 Hibernate ORM 5 的详情，请参考 Migrating to Hibernate ORM 5。

5.8.3. 迁移到 Hibernate ORM 5
复制链接

JBoss EAP 7.0 包含 Hibernate ORM 5.0。本节重点介绍从 Hibernate ORM 版本 4.3 迁移到版本 5 时所需的更改。有关在 Hibernate ORM 4 和 Hibernate ORM 5 之间实现的更改的更多信息，请参阅 Hibernate ORM 5.0 迁移指南。

删除和弃用的类

以下已弃用的类已从 Hibernate ORM 5 中删除：

对类和软件包的其他更改
类型处理
事务管理
其他 Hibernate ORM 5 更改

5.8.4. 从 Hibernate ORM 5.0 迁移到 Hibernate ORM 5.1
复制链接

JBoss EAP 7.1 包含 Hibernate ORM 5.1。本节重点介绍从 Hibernate ORM 版本 5.0 迁移到版本 5.1 所需的区别和所需更改。

Hibernate ORM 5.1 功能

Hibernate 的这个发行版本包括了很多性能改进和程序错误修复，它们包括在 JBoss EAP 7.1.0 发行注记中的 Hibernate ORM 5.1 功能 中。有关在 Hibernate ORM 5.0 和 Hibernate ORM 5.1 之间实施的更改的更多信息，请参阅 Hibernate ORM 5.1 迁移指南。

模式管理工具更改
JBoss EAP 7 中的模式管理工具更改

Hibernate ORM 5.1 中的模式管理工具更改主要关注以下区域：

  • 统一处理 hbm2ddl.auto 和 Hibernate 的 Jakarta Persistence schema-generation 支持。
  • 从 SPI 中删除 JDBC 顾虑，以促进 Hibernate OGM（一种为 NoSQL 数据存储提供 Jakarta Persistence 支持）的持久性引擎。

模式管理工具更改应该只针对直接使用任何类的应用程序进行迁移：

  • org.hibernate.tool.hbm2ddl.SchemaExport
  • org.hibernate.tool.hbm2ddl.SchemaUpdate
  • org.hibernate.tool.hbm2ddl.SchemaValidator
  • org.hibernate.tool.schema.spi.SchemaManagementTool 或其任何委托
JBoss EAP 7.1 中的模式管理工具更改

Hibernate ORM 5.1.10（包含在 JBoss EAP 7.1 中）引入了一种用于检索数据库表的新策略，用于提高 SchemaMigrator 和 SchemaValidator 性能。此策略执行单个 java.sql.DatabaseMetaData#getTables(String, String, String[]) 调用来确定每个 javax.persistence.Entity 都有映射的数据库表。这是默认的策略，它使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped 属性设置。此策略可能要求提供 hibernate.default_schema 和/或 hibernate.default_catalog。

要使用旧的策略，它会执行 java.sql.DatabaseMetaData#getTables(String, String, String, String[]) 调用每个 javax.persistence.Entity，使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individly 属性设置。

5.8.5. 从 Hibernate ORM 5.1 迁移到 Hibernate ORM 5.3
复制链接

JBoss EAP 7.4 包括 Hibernate ORM 5.3.本节重点介绍从 Hibernate ORM 5.1 迁移到 Hibernate ORM 5.3 时所需的一些更改。

Hibernate ORM 5.2 功能

Hibernate ORM 5.2 使用 Java 8 JDK 构建，需要在运行时使用 Java 8 JRE。以下是本发行版本中进行的一些更改列表：

  • hibernate-java8 模块已合并到 hibernate-core 中，Java 8 日期/时间数据类型现已原生支持。
  • hibernate-entitymanager 模块合并到 hibernate-core 中。HibernateEntityManager 和 HibernateEntityManagerFactory 已被弃用。
  • Session、StatelessSession 和 SessionFactory 类层次结构被重构为移除已弃用的类，并与 Jakarta Persistence Metamodel API 更好地保持一致。
  • org.hibernate.persister 和 org.hibernate.tuple 软件包中的 SPIs 已更改。任何使用这些 SPI 的自定义类别都需要检查和更新。
  • LimitHandler 更改引入了一个新的 hibernate.legacy_limit_handler 设置，默认设置为 false，它旨在允许您启用旧的 Hibernate 4.3 限制处理器行为。这会影响有限问题列表。
  • 引入了一个新的检索数据库表的策略，改进了 SchemaMigrator 和 SchemaValidator 性能。
  • 此发行版本更改了在使用 PostgreSQL81Dialect 及其子类时处理带有 @Lob 的 String、character[] 和 Character[] 属性的 CLOB 值的方式。
  • @TableGenerator 和 @SequenceGenerator 名称的范围已从 global 改为 local。

有关 Hibernate 5.2 中实施的更改的完整列表，请参阅 Hibernate ORM 5.2 迁移指南。

Hibernate ORM 5.3 功能

Hibernate ORM 5.3 添加了对 Jakarta Persistence 2.2 规范的支持。此发行版本包含有关此规格的更改，以及其他改进。以下是这些更改的列表：

  • 对位置查询参数处理的更改会导致以下更改：

    • 移除在 HQL/Jakarta Persistence 查询语言查询中对 JDBC 样式参数声明的支持。
    • Jakarta Persistence 位置位置参数的行为与命名参数更为相似。
    • 原生查询中的 JDBC 样式参数声明使用单向参数声明，而不是基于零的参数绑定，与 Jakarta Persistence 保持一致。您可以通过将 hibernate.query.sql.jdbc_style_params_base 属性设置为 true 来恢复基于零的绑定。
  • 为遵守 Jakarta Persistence 规格，由 @TableGener 存储的值存储的序列值是最后生成的值。在以前的版本中，Hibernate 存储下一个序列值。您可以使用 hibernate.id.generator.stored_last_used 属性来启用旧的 Hibernate 行为。使用 @TableGenerator 和迁移到 Hibernate 5.3 的现有应用程序必须将 hibernate.id.generator.stored_last_used 配置 属性设置为 false。
  • org.hibernate.query.QueryParameter 类中的 getType() 方法被重命名为 getHibernateType()。
  • Hibernate 的第二个缓存 SPI 被重新设计，以更好地满足各种缓存供应商的要求。可在 HHH-11356 中找到详情。
  • HHH-11356 的更改还需要更改消费者，这会影响 Hibernate Statistics 系统。
  • 有些方法临时添加到 org.hibernate.Query 类中，以便更轻松地将原生应用程序从 Hibernate ORM 5.1 迁移到 5.3，并维护 Hibernate 5.1 pagination 行为。这些方法已弃用，并在以后使用 Hibernate 版本进行可移植，应用程序应使用 Jakarta Persistence 方法。
  • 支持将 Infinispan 用作 Hibernate 2nd-level 缓存提供商，已移至 Infinispan 项目。因此，hibernate-infinispan 模块已被丢弃。
  • org.hibernate.tool.enhance.EnhancementTask Ant 任务的 API 已更改。addFileset（） 方法已被丢弃，而是使用 setBase（） 和 setDir（） 方法。详情可在 HHH-11795 中找到。
  • Hibernate 4.3 中引入了一个错误，导致嵌入的集合元素和复合 ID 中的多到一关联，即使在显式映射为 lazy 时也是如此。在 Hibernate 5.3.2 中，这个程序错误已被解决。因此，这些关联会根据其映射指定的。详情可在 HHH-12687 中找到。
  • 本发行版本中，Jakarta Persistence 和 Hibernate 事件监听器的原生实现。因此，JpaIntegrator 类已过时。扩展 org.hibernate.jpa.event.spi.JpaIntegrator 的类必须修改，才能将这些类更改为实施 org.hibernate.integrator.spi.spi.Integrator 接口。可在 HHH-11264 中找到详细信息。
  • org.hibernate.persister 软件包中的 SPI 已更改。任何使用这些 SPI 的自定义类别都需要检查和更新。

有关 Hibernate 5.3 中所实施的其他更改的完整列表，请参阅 Hibernate ORM 5.3 迁移指南。

在 Hibernate 5.2 和 5.3 中，使用 Hibernate 的原生 Bootstrap 构建的 SessionFactory 异常处理，按照 Jakarta Persistence 规格嵌套或转换 HibernateException。唯一例外于操作是特定于 Hibernate 时，如 Session.save（） 或 Session.saveOrUpdate（）。

在 Hibernate 5.3.3 中，添加了 hibernate.native_exception_handling_51_compliance 属性。此属性指示，使用 Hibernate 的原生 bootstrap 构建的 Session factory 异常处理是否应该和 Hibernate ORM 5.1 中的原生异常处理相同。当设置为 true 时，会根据 Jakarta Persistence 规范，不会嵌套或转换HibernateException。对于使用 Jakarta Persistence bootstrapping 构建的 SessionFactory，会忽略此设置。

5.8.5.2. 兼容性转换器
复制链接

JBoss EAP 7.4 包括一个兼容性转换程序，它解决了与 Hibernate ORM 5.1 兼容的 Hibernate ORM 5.3 API 方法。转换程序是一种临时措施，允许使用 Hibernate ORM 5.1 构建的应用程序在 JBoss EAP 7.4 中表现出与 Hibernate 5.3 相同的行为。这是一个临时解决方案，您应该将这些方法调用替换为推荐的 Jakarta Persistence 方法调用。

您可以使用以下方法之一启用转换器：

  • 您可以通过将 Hibernate51CompatibilityTransformer 系统属性设置为 true 为所有应用程序启用转换器。

  • 您可以使用 jboss-deployment-structure.xml 文件在应用程序级别启用转换程序。 

    <jboss-deployment-structure>
  <deployment>
    <transformers>
      <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/>
    </transformers>
  </deployment>
  <sub-deployment name="main.war">
    <transformers>
      <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/>
    </transformers>
  </sub-deployment>
</jboss-deployment-structure>
    Copy to Clipboard Toggle word wrap

下表列出了正在转换的 Hibernate 5.1 方法，并将其转换为 Hibernate 5.3 方法：

Expand
Hibernate 5.1 参考或方法转换为 Hibernate 5.3 参考或方法

org.hibernate.BasicQueryContract.getFlushMode()

org.hibernate.BasicQueryContract.getHibernateFlushMode()

org.hibernate.Session.getFlushMode()

org.hibernate.Session.getHibernateFlushMode()

enum org.hibernate.FlushMode.NEVER(0)

enum org.hibernate.FlushMode.MANUAL(0)

org.hibernate.Query.getMaxResults()

org.hibernate.Query.getHibernateMaxResults()

org.hibernate.Query.setMaxResults(int)

org.hibernate.Query.setHibernateMaxResults(int)

org.hibernate.Query.getFirstResult(int)

org.hibernate.Query.getHibernateFirstResult()

org.hibernate.Query.setFirstResult(int)

org.hibernate.Query.setHibernateFirstResult(int)

Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat返回顶部