Java 整合 WebSphere MQ 實戰指南：從環境搭建到收發消息

WebSphere MQ 核心概念

• Queue Manager (QM)：消息隊列管理器，如 MQSI_SAMPLE_QM
• Queue：存儲消息的容器，本例使用 Local Queue lq
• Channel：通信通道，本例使用 Server Connection Channel BridgeChannel
• 跨平台：MQ 客戶端與服務端可運行在不同作業系統

環境準備步驟

1. 安裝 WebSphere MQ 並啟動服務
2. 創建 Queue Manager：MQSI_SAMPLE_QM
3. 創建 Local Queue：lq
4. 創建 Server Connection Channel：BridgeChannel，監聽端口默認 1414

Java 客戶端完整代碼

package test.mq;

import com.ibm.mq.*;

public class FirstMqTest {
    public static void main(String[] args) {
        new FirstMqTest().test();
    }

    public void test() {
        String qManager = "MQSI_SAMPLE_QM";
        String qName = "lq";

        try {
            // 1. 配置連接參數
            MQEnvironment.hostname = "172.16.17.123";  // MQ 服務器 IP
            MQEnvironment.channel = "BridgeChannel";    // 通道名
            MQEnvironment.CCSID = 1381;                 // 字符集 (UTF-8)
            // MQEnvironment.port = 1414;               // 如非默認端口需顯式設置

            // 2. 連接 Queue Manager
            System.out.println("Connecting to queue manager: " + qManager);
            MQQueueManager qMgr = new MQQueueManager(qManager);

            // 3. 打開隊列（輸入+輸出模式）
            int openOptions = MQC.MQOO_INPUT_AS_Q_DEF | MQC.MQOO_OUTPUT;
            System.out.println("Accessing queue: " + qName);
            MQQueue queue = qMgr.accessQueue(qName, openOptions);

            // 4. 構造消息並發送
            MQMessage msg = new MQMessage();
            msg.writeUTF("Hello, World!");

            MQPutMessageOptions pmo = new MQPutMessageOptions();

            // 批量發送 5 條測試消息
            for (int j = 0; j < 5; j++) {
                String str = "test11111111111" + j;
                msg.writeUTF(str);
                queue.put(msg, pmo);
            }
            queue.put(msg, pmo);  // 再發送初始消息
            System.out.println("Sending messages done.");

            // 5. 接收消息
            MQMessage rcvMessage = new MQMessage();
            MQGetMessageOptions gmo = new MQGetMessageOptions();
            System.out.println("Getting message back...");
            queue.get(rcvMessage, gmo);

            String msgText = rcvMessage.readUTF();
            System.out.println("Received: " + msgText);

            // 6. 清理資源
            queue.close();
            qMgr.disconnect();
            System.out.println("Done!");
        } catch (MQException ex) {
            System.err.println("MQ Error: CC=" + ex.completionCode + ", RC=" + ex.reasonCode);
        } catch (java.io.IOException ex) {
            System.err.println("IO Error: " + ex);
        }
    }
}

關鍵 API 說明

常見問題排查

• 2035 (MQRC_NOT_AUTHORIZED)：Channel 權限未配置，需在 MQ 控制台授權 BridgeChannel 的 MCAUSER
• 2538 (MQRC_HOST_NOT_AVAILABLE)：IP/端口/防火牆/Listener 未啟動
• CCSID 不匹配：發送端 MQEnvironment.CCSID 必須與隊列管理器一致，中文環境常用 1381 (UTF-8) 或 5488 (GB18030)
• JAR 依賴：需 com.ibm.mq.jar、com.ibm.mqjms.jar、connector.jar 等，建議用 Maven 管理：com.ibm.mq:com.ibm.mq.allclient

進階主題

• JMS 規範封裝：使用 WMQInitialContextFactory 通過 JNDI 獲取 ConnectionFactory/Queue，代碼與 MQ 實現解耦
• 事務控制：qMgr.begin()/commit()/rollback() 實現本地事務
• 集群/高可用：配置 Queue Manager Cluster、Multi-instance QM
• 安全傳輸：啟用 TLS/SSL，配置 MQEnvironment.sslCipherSuite、密鑰庫

總結

WebSphere MQ 提供企業級可靠消息傳遞，Java 客戶端 API 成熟穩定。掌握「環境配置 → 連接 QM → 打開隊列 → 構造消息 → 收發 → 資源釋放」核心流程，並關注權限、編碼、事務、高可用等生產環境要點，即可穩健集成 MQ 消息中間件。