JBoss 4.2.x 配置 MySQL 數據源完整教程（附 Oracle 通用遷移說明）

前言

JBoss AS 4.2.x 系列雖屬舊版本，但仍有存量系統在運行。本文以 MySQL 為例，詳細說明 -ds.xml 數據源配置全過程，並標註 Oracle 遷移差異點，助你快速完成資料庫接入。

一、 準備工作

1. 確認 JBoss 版本：jboss-4.2.2.GA（本文基準版本）
2. 下載 MySQL JDBC 驅動：mysql-connector-java-5.1.xx.jar（或 8.0.x 版本，需對應 com.mysql.cj.jdbc.Driver）
3. 將驅動包放入 $JBOSS_HOME/server/default/lib/ 目錄（全域共享）或專案 WEB-INF/lib/（隔離部署）

二、 建立數據源配置文件

在 $JBOSS_HOME/server/default/deploy/ 目錄新建 mysql-ds.xml（命名慣例：*-ds.xml 會被自動識別部署）。

可從 $JBOSS_HOME/docs/examples/jca/mysql-ds.xml 複製模板修改。

完整配置範例（MySQL 5.1+ 驅動）：

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>MySQLDS</jndi-name>
    <connection-url>jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=utf8&useSSL=false</connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>db_user</user-name>
    <password>db_password</password>
    <min-pool-size>5</min-pool-size>
    <max-pool-size>20</max-pool-size>
    <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exception-sorter-class-name>
    <metadata>
      <type-mapping>mySQL</type-mapping>
    </metadata>
  </local-tx-datasource>
</datasources>

關鍵屬性說明：

三、 Oracle 遷移差異對照表

若需接入 Oracle，只需修改以下項目，其餘結構完全一致：

四、 驗證部署

1. 啟動 JBoss：$JBOSS_HOME/bin/run.sh -c default
2. 觀察控制台/日誌 server.log，出現 Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=MySQLDS' to JNDI name 'java:/MySQLDS' 表示成功
3. JMX Console 驗證：https://localhost:8080/jmx-console/ → 搜尋 MySQLDS → 檢視 ConnectionPool 狀態

五、 程式碼中查找使用

Context ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:/MySQLDS");
Connection conn = ds.getConnection();
// 業務邏輯...
conn.close(); // 必須關閉，歸還連接池

六、 常見問題排查

• ClassNotFoundException 驅動類： 驅動包未放入 server/default/lib/ 或版本不匹配
• Communications link failure： 檢查 MySQL bind-address、防火牆 3306 端口、skip-networking 參數
• 連接池耗盡： 代碼未正確關閉連接、max-pool-size 過小、長事務阻塞
• 中文亂碼： 確認 useUnicode=true&characterEncoding=utf8、資料庫/表/欄位字符集為 utf8mb4

結語

JBoss 4.2 的 -ds.xml 配置機制清晰且強大，掌握核心屬性與驅動對應關係，即可快速完成異構資料庫接入。新專案建議遷移至 WildFly / JBoss EAP 7+，享受 Jakarta EE 8/9 標準與更佳效能。