OpenJPA 入門實戰：從環境搭建到第一個持久化應用完整流程

本文為 OpenJPA 實戰系列第 2 部分，帶領讀者從零開始，在 Java SE 環境下完成 OpenJPA 開發環境搭建、實體建立、增強、映射生成、持久化操作全流程。

環境準備

• JDK 5.0+ (註解支援)
• MySQL 5.0+ (建議字符集 GB2312 支援中文)
• OpenJPA 0.97+ (解壓至 C:/OpenJPA，設 %OPENJPA_HOME%)

標準開發步驟

1. 編寫 META-INF/persistence.xml 配置
2. 設計實體類 (JPA 註解)
3. 編譯實體類
4. 增強 實體類 (PCEnhancer)
5. 生成資料庫 DDL (MappingTool) 或直接同步建表
6. 註冊實體至 persistence.xml
7. 編寫 DAO 代碼操作實體

核心配置：persistence.xml

<persistence-unit name="mysql" transaction-type="RESOURCE_LOCAL">
  <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
  <class>org.vivianj.openjpa.entity.Animal</class>
  <properties>
    <property name="openjpa.ConnectionURL" value="jdbc:mysql://localhost/openjpa"/>
    <property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
    <property name="openjpa.ConnectionUserName" value="openjpa"/>
    <property name="openjpa.ConnectionPassword" value="openjpa"/>
  </properties>
</persistence-unit>

RESOURCE_LOCAL 表示本地事務 (非 JTA)，適用 Java SE 環境。

實體類：Animal

@Entity
public class Animal {
    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY) // MySQL 自增
    private int id;

    @Basic
    private String name;
    // getter/setter...
}

關鍵步驟：實體增強

OpenJPA 必須 對編譯後的 Class 執行位元組碼增強 (PCEnhancer)，植入 PersistenceCapable 介面，實現：

• 狀態管理 (脏檢查、版本控制)
• 延遲載入
• 效能優化

命令列增強範例：

java -cp %CLASSPATH% org.apache.openjpa.enhance.PCEnhancer Animal.class

增強後類結構新增 pcStateManager、pcFlags 等欄位與大量 pc* 方法。

MappingTool：同步資料庫結構

• 直接建表：java org.apache.openjpa.jdbc.meta.MappingTool Animal.class
• 生成 DDL 腳本：java org.apache.openjpa.jdbc.meta.MappingTool -sql animal.sql Animal.class

執行後 MySQL 自動建立 animal 表 (含 ID 自增主鍵、NAME 欄位)。

核心 API 操作模式

// 1. 獲取 EntityManagerFactory (緩存重用)
EntityManagerFactory factory = Persistence.createEntityManagerFactory("mysql");

// 2. 獲取 EntityManager
EntityManager em = factory.createEntityManager();

// 3. 寫操作需顯式事務
em.getTransaction().begin();
em.persist(animal);  // 新增
em.merge(animal);    // 更新
em.remove(animal);   // 刪除
// 或 JPQL 批量: em.createQuery("DELETE FROM Animal WHERE id=1").executeUpdate();
em.getTransaction().commit();

// 4. 讀操作
Animal a = em.find(Animal.class, 1); // 主鍵查找
Query q = em.createQuery("SELECT a FROM Animal a WHERE a.name LIKE :name");
q.setParameter("name", "%dog%");
List list = q.getResultList(); // JPQL 查詢

// 5. 關閉資源
em.close();
factory.close();

完整 DAO 實現

文中提供 AnimalDAOImpl 完整代碼，封裝 persistAnimal、updateAnimal、removeAnimal、getAnimalByPrimaryKey、findAnimalsByName 五大核心方法，展示標準操作模式與資源管理。

常見坑點提醒

• 未增強實體：運行時拋出 PersistenceException，提示非 PersistenceCapable。
• JDBC 驅動未加入 Classpath：MappingTool 或運行時報 StoreException。
• persistence.xml 未註冊實體類：EntityManager 找不到實體定義。
• 事務未提交：寫操作無效果，資料未入庫。

總結

OpenJPA 入門核心在於：註解式配置 + 位元組碼增強 + 標準 JPA API。掌握 persistence.xml、@Entity/@Id/@GeneratedValue、PCEnhancer、MappingTool、EntityManager 生命週期與事務邊界，即可快速構建健壯持久層。下一步將探討實體繼承、關聯映射等進階特性。