Hibernate JNDI 綁定機制深度解析：SessionFactory 自動註冊原理

核心流程概覽

Hibernate 的 JNDI 綁定發生在 Configuration.buildSessionFactory() 過程中，由 SessionFactoryObjectFactory 完成。理解此機制有助於在應用伺服器中正確管理 SessionFactory 生命週期。

關鍵代碼追蹤

1. 建立 Configuration 並讀取屬性

Configuration conf = new Configuration().addClass(Cat.class);
// 建構子內讀取 hibernate.properties，屬性存入 Properties 物件
// 關鍵屬性：hibernate.session_factory_name = hibernate/session_factory

2. buildSessionFactory() 呼叫鏈

SessionFactory sf = conf.buildSessionFactory();
// 內部檢查配置 → 呼叫 SessionFactoryImpl 建構子

3. SessionFactoryImpl 建構子關鍵行

name = properties.getProperty(Environment.SESSION_FACTORY_NAME);
SessionFactoryObjectFactory.addInstance(uuid, name, this, properties);

• name：從屬性讀取 JNDI 名稱 (預設 hibernate/session_factory)
• this：SessionFactory 實例自身
• 傳遞給 SessionFactoryObjectFactory.addInstance()

4. SessionFactoryObjectFactory.addInstance() 實作

Context ctx = NamingHelper.getInitialContext(properties);
NamingHelper.bind(ctx, name, instance);

• 透過 NamingHelper 取得 JNDI InitialContext
• 將 SessionFactory 實例綁定到指定名稱

關鍵結論

1. 動態綁定觸發點：conf.buildSessionFactory() 執行時自動完成 JNDI 綁定
2. 前置條件：必須先在程式碼中建立 SessionFactory 實例，且必須早於任何從 JNDI 查找的程式碼執行
3. 應用伺服器整合策略：
   • Servlet 環境：配置 load-on-startup 的初始化 Servlet 執行建立代碼
   • EJB/複雜 J2EE：依賴應用伺服器啟動服務 (如 JBoss SAR、WebLogic Startup Class) 確保優先建立
4. 無需手動管理 JNDI：Hibernate 內建綁定邏輯，開發者只需確保 SessionFactory 建立時機

實務配置範例

hibernate.properties 關鍵設定

hibernate.session_factory_name = java:/hibernate/SessionFactory
hibernate.jndi.url = jnp://localhost:1099
hibernate.jndi.class = org.jnp.interfaces.NamingContextFactory

Web.xml 初始化 Servlet (舊版專案適用)

<servlet>
 <servlet-name>HibernateInitializer</servlet-name>
 <servlet-class>com.example.HibernateInitServlet</servlet-class>
 <load-on-startup>1</load-on-startup>
</servlet>

HibernateInitServlet.java

public class HibernateInitServlet extends HttpServlet {
 public void init() {
     Configuration conf = new Configuration().configure();
     conf.buildSessionFactory(); // 觸發 JNDI 綁定
 }
}

常見問題與避坑指南

現代替代方案

JPA / Spring Framework / CDI 等現代框架提供更優雅的 SessionFactory/EntityManager 管理與注入機制，建議新專案優先考慮：

• Spring LocalSessionFactoryBean + <jee:jndi-lookup>
• Java EE @PersistenceUnit / @PersistenceContext
• CDI Producer 方法管理生命週期