Hibernate 註解配置載入機制深度解析 (AnnotationConfiguration)

前言

Hibernate 啟動核心在於 Configuration 物件建立與組態檔載入。使用註解時需改用 AnnotationConfiguration (Hibernate 3.5+ 已合併至 Configuration)，本文剖析 configure() 多載方法的載入邏輯與資源尋找路徑。

Configuration 物件建立

// 純 XML 映射
Configuration cfg = new Configuration();

// 註解映射 (Hibernate 3.x)
Configuration cfg = new AnnotationConfiguration();
// Hibernate 4/5+ 直接用 Configuration 即可支援註解
Configuration cfg = new Configuration();

configure() 方法族群

1. configure() - 無參數

預設載入 classpath 根目錄下的 hibernate.cfg.xml。內部實際呼叫 configure("/hibernate.cfg.xml")。

2. configure(String resource) - 最常用

指定 classpath 相對路徑資源名 (如 "com/example/hibernate.cfg.xml")。內部委派 doConfigure(InputStream, String)。

資源尋找邏輯 (ConfigHelper.getResourceAsStream)：

1. 移除開頭 / (若有)
2. 嘗試 Thread.currentThread().getContextClassLoader().getResourceAsStream() (通常為 AppClassLoader)
3. 失敗則嘗試 Environment.class.getResourceAsStream() (Hibernate 核心類別 ClassLoader)
4. 失敗則嘗試 Environment.class.getClassLoader().getResourceAsStream()
5. 皆失敗拋出 HibernateException: resource not found

啟示： 組態檔可放在專案 src/main/resources (ClassLoader 根路徑)，或與啟動類別同包路徑。

3. configure(URL url)

接受 java.net.URL 物件，內部呼叫 url.openStream() 取得輸入流，再委派 doConfigure。

4. configure(File configFile)

接受 java.io.File，內部以 FileInputStream 讀取，適用檔案系統絕對路徑。

5. doConfigure(InputStream stream, String resourceName) - 核心解析

使用 Dom4j 解析 XML：

SAXReader reader = XMLHelper.createSAXReader(resourceName, errors, entityResolver);
Document doc = reader.read(new InputSource(stream));
configure(doc); // 進入 Document 解析流程

6. configure(Document document)

直接接受已解析的 Dom4j Document 物件，解析所有 <property>、<mapping> (class 或 resource) 等節點。

映射檔案載入

<mapping class="com.eric.po.User"/> 載入註解實體；<mapping resource="User.hbm.xml"/> 載入 XML 映射檔。兩者可混用。

建立 SessionFactory

SessionFactory sf = cfg.buildSessionFactory();
// 或搭配 ServiceRegistry (Hibernate 4+)
StandardServiceRegistryBuilder builder = new StandardServiceRegistryBuilder().applySettings(cfg.getProperties());
SessionFactory sf = cfg.buildSessionFactory(builder.build());

總結

掌握 configure() 多載與資源尋找順序，能靈活部署組態檔 (JAR 內、外部檔案、URL、動態生成 Document)，也是排查「hibernate.cfg.xml not found」異常的關鍵。