Java19+NetBeans16下EclipseLink与Derby适配问题排查

问题背景 #

项目从Java 8 + NetBeans 8升级到Java 19 + NetBeans 16后，先后出现两个JPA相关异常：

• 初始空指针异常：创建EntityManagerFactory时抛出，原依赖为javax.persistence_2.1.1和org.eclipse.persistence.jpa.modelgen_2.6.4
• 更换EclipseLink 4.0后：空指针解决，但出现No Persistence provider for EntityManager named jDiskMarkPU异常

原异常栈 #

Exception in thread "AWT-EventQueue-0" Local Exception Stack: 
Exception [EclipseLink-30005] (Eclipse Persistence Services - 2.6.4.v20160829-44060b6): org.eclipse.persistence.exceptions.PersistenceUnitLoadingException
Exception Description: An exception was thrown while searching for persistence archives with ClassLoader: jdk.internal.loader.ClassLoaders$AppClassLoader@c387f44
Internal Exception: java.lang.NullPointerException: Cannot invoke "org.eclipse.persistence.internal.sessions.AbstractSession.getName()" because "this.session" is null
    ...

异常触发代码 #

EntityManagerFactory emf = Persistence.createEntityManagerFactory("jDiskMarkPU");
em = emf.createEntityManager();

原persistence.xml配置 #

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
  <persistence-unit name="jDiskMarkPU" transaction-type="RESOURCE_LOCAL">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <exclude-unlisted-classes>false</exclude-unlisted-classes>
    <properties>
      <property name="eclipselink.logging.level" value="FINE"/>
      <property name="javax.persistence.jdbc.url" value="jdbc:derby:derbyDB;create=true"/>
      <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver"/>
      <property name="javax.persistence.schema-generation.database.action" value="create"/>
      <property name="eclipselink.ddl-generation" value="create-or-extend-tables"/>
    </properties>
  </persistence-unit>
</persistence>

新异常栈 #

Exception in thread "AWT-EventQueue-0" javax.persistence.PersistenceException: No Persistence provider for EntityManager named jDiskMarkPU
    ...

核心原因 #

EclipseLink 4.0基于Jakarta Persistence 3.0，而原项目使用的是Java EE的javax.persistence API。从Java EE 8到Jakarta EE 9，所有API包名从javax.*迁移到jakarta.*，导致旧配置和依赖与新版本完全不兼容。

分步解决方案 #

1. 彻底替换依赖库 #

• 删除所有javax.persistence相关的旧依赖
• 引入jakarta.persistence-api（3.0+版本）
• 使用完整的EclipseLink 4.0依赖包（必须包含org.eclipse.persistence.jpa核心模块，不要仅引入modelgen）
• 升级Derby驱动到10.16+版本，确保适配Java 19

2. 升级persistence.xml配置 #

同步更新命名空间、版本号和属性前缀：

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="3.0" xmlns="https://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd">
  <persistence-unit name="jDiskMarkPU" transaction-type="RESOURCE_LOCAL">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <exclude-unlisted-classes>false</exclude-unlisted-classes>
    <properties>
      <property name="eclipselink.logging.level" value="FINE"/>
      <!-- 替换javax.persistence前缀为jakarta.persistence -->
      <property name="jakarta.persistence.jdbc.url" value="jdbc:derby:derbyDB;create=true"/>
      <property name="jakarta.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver"/>
      <property name="jakarta.persistence.schema-generation.database.action" value="create"/>
      <property name="eclipselink.ddl-generation" value="create-or-extend-tables"/>
    </properties>
  </persistence-unit>
</persistence>

3. 替换代码中的API导入 #

将所有javax.persistence的导入替换为jakarta.persistence：

// 原导入
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

// 替换为
import jakarta.persistence.EntityManager;
import jakarta.persistence.EntityManagerFactory;
import jakarta.persistence.Persistence;

4. NetBeans项目配置检查 #

• 确认项目JDK已设置为Java 19（右键项目→Properties→Libraries→Java Platform）
• 执行Clean and Build，清理旧构建文件，确保新依赖被正确加载
• 验证persistence.xml存放路径：传统NetBeans项目放在src/META-INF，Maven项目放在src/main/resources/META-INF

验证步骤 #

1. 清理项目构建目录
2. 重新构建并运行项目
3. 检查Derby数据库是否正常初始化，EntityManagerFactory是否能成功创建

内容的提问来源于stack exchange，提问作者simgineer