从 JPA 2.x 迁移到 3.0

柔情只为你懂 2023-09-25 13:51 30阅读 0赞

我最近收到了很多关于[JPA 3.0][]的问题，由于EclipseLink和Hibernate现在提供了对它的全面支持，现在是时候仔细看看规范的最新更新了。作为从Java EE到Jakarta EE转换的一部分，Java Persistence API（JPA）更名为Jakarta Persistence API（JPA）。该过程的第一步发生在 JPA 2.2 中，现在在 JPA 3.0 中完成。让我们仔细看看 JPA 3.0 中引入的更改以及所需的迁移步骤。

内容\[[隐藏][Link 1]\]

*  [1它不同，但仍然相同][1]
 *  [阿拉伯数字实现 JPA 3.0 的框架][JPA 3.0 1]
 *  [3迁移现有应用程序][3]
    
     *  [3.1更改与 JPA 相关的导入][3.1_ JPA]
     *  [3.2更新 XML 命名空间][3.2_ XML]
     *  [3.3迁移配置参数][3.3]
 *  [四结论][Link 2]

### 它不同，但仍然相同 ###

如果你仔细看看JPA 3.0，似乎什么都没有改变。这并非完全错误。JPA 3.0 没有带来任何新功能。它仅更改所有 API 类的包名称的前缀、某些配置属性的前缀以及所有基于 XML 的配置文件的架构命名空间。这些更改的目的是替换“java”一词以避免法律问题。

软件包名称和配置参数名称的前缀从javax.persistence.\*更改为*jakarta.persistence.\**，例如，*@Entity*注释所需的导入从*javax.persistence.Entity*更改为jakarta.persistence.Entity，javax.persistence.schema-generation.database.action属性的名称更改为*jakarta.persistence.schema-generation.database.action*.除此之外，XML 命名空间从*http://xmlns.jcp.org/xml/ns/persistence*和 *http://xmlns.jcp.org/xml/ns/persistence/orm*更改为*https://jakarta.ee/xml/ns/persistence*和  
*https://jakarta.ee/xml/ns/persistence/orm*。

这些更改完成了从 Java EE 到 Jakarta EE 的过渡过程。遗憾的是，它们还要求您迁移代码和配置文件。

### 实现 JPA 3.0 的框架 ###

JPA 规范的 2 个最流行的实现支持版本 3.0。如果要使用 EclipseLink，则至少需要使用 3.0 版。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 </td> 
 <td> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;org.eclipse.persistence&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;org.eclipse.persistence.jpa&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;3.0.1&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

Hibernate在5.5版本中开始支持JPA 3.0。所有支持新 JPA 3.0 API 的 Hibernate 工件的名称中都有后缀“-jakarta”。如果仍想使用旧的 API，可以坚持使用旧的工件名称。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 </td> 
 <td> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;org.hibernate&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;hibernate-core-jakarta&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;5.5.2&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

### 迁移现有应用程序 ###

将依赖项更新为上面列出的依赖项之一后，需要对导入语句和配置文件进行一些更改。但是，别担心，它并不像看起来那么糟糕。您可以使用 IDE 中的搜索和替换功能或在命令行上执行一些基本命令来完成大部分工作。

#### 更改与 JPA 相关的导入 ####

如前所述，与 JPA 2.2 相比，JPA 3.0 没有添加或更改任何功能。它只是将包从javax.persistence更改为*jakarta.persistence*。因此，您可以简单地将所有出现的“import javax.persistence”替换为“import jakarta.persistence”。

执行此操作后，实体类的导入应类似于以下代码段，并且所有映射定义都应保持不变。

#### 更新 XML 命名空间 ####

如果使用*orm.xml*或*持久性.xml*文件来定义映射或配置持久性单元，则还应更新命名空间和架构定义。

在[持久性.xml配置][.xml]中，需要将*http://xmlns.jcp.org/xml/ns/persistence*替换为*https://jakarta.ee/xml/ns/persistence*。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 </td> 
 <td> <code>&lt;?</code><code>xml</code> <code>version</code><code>=</code><code>"1.0"</code> <code>encoding</code><code>=</code><code>"UTF-8"</code> <code>standalone</code><code>=</code><code>"yes"</code><code>?&gt;</code> <code>&lt;</code><code>persistence</code> <code>xmlns</code><code>=</code><code>"<a href="https://jakarta.ee/xml/ns/persistence" title="Jakarta Persistence XML Schemas | The Eclipse Foundation" rel="nofollow">Jakarta Persistence XML Schemas | The Eclipse Foundation</a>"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>xmlns:xsi</code><code>=</code><code>"<a href="http://www.w3.org/2001/XMLSchema-instance" title="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>version</code><code>=</code><code>"3.0"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>xsi:schemaLocation</code><code>=</code><code>"<a href="https://jakarta.ee/xml/ns/persistence" title="Jakarta Persistence XML Schemas | The Eclipse Foundation" rel="nofollow">Jakarta Persistence XML Schemas | The Eclipse Foundation</a> <a href="https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd" title="https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd" rel="nofollow">https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd</a>"</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>persistence-unit</code> <code>name</code><code>=</code><code>"my-persistence-unit"</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>...</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;/</code><code>persistence-unit</code><code>&gt;</code> <code>&lt;/</code><code>persistence</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

在包含映射定义的[orm.xml][]文件中，您需要*将 http://xmlns.jcp.org/xml/ns/persistence/orm*替换为*https://jakarta.ee/xml/ns/persistence/orm*。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 </td> 
 <td> <code>&lt;?</code><code>xml</code> <code>version</code><code>=</code><code>"1.0"</code> <code>encoding</code><code>=</code><code>"UTF-8"</code> <code>standalone</code><code>=</code><code>"yes"</code><code>?&gt;</code> <code>&lt;</code><code>entity-mappings</code> <code>version</code><code>=</code><code>"3.0"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>xmlns</code><code>=</code><code>"<a href="https://jakarta.ee/xml/ns/persistence/orm" title="https://jakarta.ee/xml/ns/persistence/orm" rel="nofollow">https://jakarta.ee/xml/ns/persistence/orm</a>"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>xmlns:xsi</code><code>=</code><code>"<a href="http://www.w3.org/2001/XMLSchema-instance" title="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>"</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>entity</code> <code>class</code><code>=</code><code>"com.thorben.janssen.model.ChessPlayer"</code> <code>name</code><code>=</code><code>"ChessPlayer"</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>...</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;/</code><code>entity</code><code>&gt;</code> <code>&lt;/</code><code>entity-mappings</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

#### 迁移配置参数 ####

要将应用程序迁移到 JPA 3.0，您需要做的最后一件事是更新配置参数的名称。这些通常在您的持久性.xml文件中定义和使用，我在[JPA 持久性初学者指南][.xml]中详细介绍了所有这些.xml。

其中一些属性的名称包括前缀“javax.persistence”，例如“javax.persistence.jdbc.driver”。对于所有这些参数，您需要将“javax.persistence”替换为“jakarta.persistence”。执行此操作后，您的配置类似于以下代码片段。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 </td> 
 <td> <code>&lt;?</code><code>xml</code> <code>version</code><code>=</code><code>"1.0"</code> <code>encoding</code><code>=</code><code>"UTF-8"</code> <code>standalone</code><code>=</code><code>"yes"</code><code>?&gt;</code> <code>&lt;</code><code>persistence</code> <code>xmlns</code><code>=</code><code>"<a href="https://jakarta.ee/xml/ns/persistence" title="Jakarta Persistence XML Schemas | The Eclipse Foundation" rel="nofollow">Jakarta Persistence XML Schemas | The Eclipse Foundation</a>"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>xmlns:xsi</code><code>=</code><code>"<a href="http://www.w3.org/2001/XMLSchema-instance" title="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>version</code><code>=</code><code>"3.0"</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>xsi:schemaLocation</code><code>=</code><code>"<a href="https://jakarta.ee/xml/ns/persistence" title="Jakarta Persistence XML Schemas | The Eclipse Foundation" rel="nofollow">Jakarta Persistence XML Schemas | The Eclipse Foundation</a> <a href="https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd" title="https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd" rel="nofollow">https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd</a>"</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>persistence-unit</code> <code>name</code><code>=</code><code>"my-persistence-unit"</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>description</code><code>&gt;Hibernate example configuration - thorben-janssen.com&lt;/</code><code>description</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>exclude-unlisted-classes</code><code>&gt;false&lt;/</code><code>exclude-unlisted-classes</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>properties</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"hibernate.jdbc.time_zone"</code> <code>value</code><code>=</code><code>"UTC"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"jakarta.persistence.jdbc.driver"</code> <code>value</code><code>=</code><code>"org.postgresql.Driver"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"jakarta.persistence.jdbc.url"</code> <code>value</code><code>=</code><code>"jdbc:postgresql://localhost:5432/test"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"jakarta.persistence.jdbc.user"</code> <code>value</code><code>=</code><code>"postgres"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"jakarta.persistence.jdbc.password"</code> <code>value</code><code>=</code><code>"postgres"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"jakarta.persistence.schema-generation.database.action"</code> <code>value</code><code>=</code><code>"drop-and-create"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>property</code> <code>name</code><code>=</code><code>"jakarta.persistence.sql-load-script-source"</code> <code>value</code><code>=</code><code>"data.sql"</code><code>/&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;/</code><code>properties</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;/</code><code>persistence-unit</code><code>&gt;</code> <code>&lt;/</code><code>persistence</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

### 结论 ###

JPA 3.0 更改了所有类的包、配置文件的 XML 命名空间以及一些配置参数的名称，以完成从 Java 持久性 API 到 Jakarta 持久性 API 的转换。特别是包名称的更改可能看起来像一个巨大的变化，导致现有项目中的大量工作。但它并不像看起来那么糟糕。您可以使用 IDE 的搜索和替换功能或基本 shell 脚本轻松更改导入语句。

[JPA 3.0]: https://jakarta.ee/specifications/persistence/3.0/
[Link 1]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#
[1]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#It8217s_different_but_it8217s_still_the_same
[JPA 3.0 1]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#Frameworks_Implementing_JPA_30
[3]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#Migrating_an_Existing_Application
[3.1_ JPA]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#Changing_JPA-Related_Imports
[3.2_ XML]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#Updating_XML_Namespaces
[3.3]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#Migrating_Configuration_Parameters
[Link 2]: https://thorben-janssen.com/migrating-jpa-2-x-to-3-0/#Conclusion
[.xml]: https://thorben-janssen.com/jpa-persistence-xml/
[orm.xml]: https://thorben-janssen.com/mapping-definitions-jpa-hibernate-annotations-xml/