關於 Message Queue 4.0

Message Queue 4.0 是僅支援 Application Server 9 PE 的發行版本。此為包含一些新功能、次要增強功能和錯誤修正的次要發行版本。本節包含下列資訊。

• 4.0 版的新增功能

• 硬體與軟體需求

4.0 版的新增功能

Message Queue 4.0 包含下列新增功能：

• C API 與 C 用戶端執行階段的介面變更

• Java API 與 Java 用戶端執行階段的介面變更

• 顯示關於永久存放區的資訊

• 永久存放區格式變更

• 代理程式管理

• JDBC 永久性支援

• SSL 支援

• JMX 支援

• 用戶端執行階段記錄

• 連線事件通知

這些資訊都會在下列小節中詳述。

4.0 版推出的其中一個變更極為次要，但可能會造成重大問題，亦即停用指定密碼的指令行選項。因此，您必須如已停用的密碼選項中所述，把所有密碼儲存在一個檔案中。

C API 與 C 用戶端執行階段的介面變更

Message Queue 4.0 版增加兩個特性，停用的訊息佇列中所有的訊息都會設定這兩個特性。

• JMS_SUN_DMQ_PRODUCING_BROKER 表示產生訊息的代理程式。

• JMS_SUN_DMQ_DEAD_BROKER 表示將訊息標記為停用的代理程式。

Java API 與 Java 用戶端執行階段的介面變更

Message Queue 4.0 版增加兩個特性，停用的訊息佇列中所有的訊息都會設定這兩個特性。

• JMS_SUN_DMQ_PRODUCING_BROKER 表示產生訊息的代理程式。

• JMS_SUN_DMQ_DEAD_BROKER 表示將訊息標記為停用的代理程式。

顯示關於永久存放區的資訊

imqdbmgr 指令已增加 query 子指令。使用此子指令可顯示關於永久存放區的資訊，包含存放區版本、資料庫使用者，以及是否已建立資料庫表格。

以下是該指令所顯示之資訊的範例。

imqdbmgr query

[04/Oct/2005:15:30:20 PDT] Using plugged-in persistent store:
        version=400
        brokerid=Mozart1756
        database connection url=jdbc:oracle:thin:@Xhome:1521:mqdb
        database user=scott
Running in standalone mode.
Database tables have already been created.

永久存放區格式變更

Message Queue 3.7 UR1 版推出了永久存放區格式的兩項變更，可改善效能。其中一項變更針對檔案存放區，另一項則針對 JDBC 存放區。

• 存留在檔案存放區中的作業事件資料格式

  Message Queue 檔案式永久存放區所儲存的作業事件狀態資訊已經變更其格式，可降低磁碟 I/O 並改善 JMS 作業事件的效能。

• Oracle JDBC 存放區

  在之前版本的 Message Queue 中，Oracle 的存放區模式使用 LONG RAW 資料類型來儲存訊息資料。在 Oracle 8 中，Oracle 引入了 BLOB 資料類型，並停用了 LONG RAW 類型。Message Queue 3.7 UR1 已改用 BLOB 資料類型，可改善效能與支援能力。

由於這些變更會影響存放區相容性，因此在 Message Queue 3.7 UR1 版中，檔案存放區和 JDBC 存放區的存放區版本皆已由 350 變更為 370。

Message Queue 4.0 版變更了 JDBC 存放區，以取得最佳效能並支援後續的增強功能。因此，JDBC 存放區版本已提昇為 400。請注意，在 4.0 版中，檔案式永久存放區版本沒有任何變更，因此還是 370。

Message Queue 4.0 支援將永久存放區自動轉換為檔案式和 JDBC 永久存放區的最新版本。初次啟動 imqbrokerd 時，如果公用程式偵測到舊版存放區，則會將該存放區遷移至新的格式，同時保留舊版存放區。

• 檔案式存放區版本 200 和 350 會遷移至 370 版本格式。

• JDBC 存放區版本 350 和 370 會遷移至 400 版本格式。(如果您需要升級 200 存放區，則需要先升級到 3.5 或 3. 6 版。)

若要回復此升級動作，請解除安裝 Message Queue 4.0，然後重新安裝之前執行的版本。由於舊版的存放區副本保留不變，因此代理程式可利用舊版的存放區副本執行。

代理程式管理

指令公用程式 (imqcmd) 已增加子指令和數個選項，可讓管理員靜止代理程式、在指定間隔時間後關閉代理程式、銷毀連線，或設定 Java 系統特性 (例如連線相關特性)

• 靜止代理程式會使其進入無訊息狀態，允許在關閉或重新啟動代理程式之前清空訊息。您無法向靜止中的代理程式建立新連線。若要靜止代理程式，請如下輸入指令。

  imqcmd quiesce bkr -b Wolfgang:1756

• 若要在指定間隔後關閉代理程式，請如下輸入指令。(時間間隔會指定代理程式關閉前的等候秒數)。

  imqcmd shutdown bkr -b Hastings:1066 -time 90

  若指定時間間隔，代理程式就會記錄一則訊息，指示何時將會關閉。例如，

  Shutting down the broker in 29 seconds (29996 milliseconds) (在 29 秒後關閉代理程式，29996 毫秒)

  當代理程式等候關閉時，其運作方式會有以下影響。

  • 會繼續接受管理 JMS 連線。

  • 不會接受任何新的 JMS 連線。

  • 現有的 JMS 連線會繼續運作。

  • 代理程式無法接管高可用性叢集中的任何其他代理程式。

  • imqcmd 公用程式不會封鎖，它會向代理程式傳送關閉請求並立即返回。

• 若要銷毀連線，請如下輸入指令。

  imqcmd destroy cxn -n 2691475382197166336

  使用指令 imqcmd list cxn 或 imqcmd query cxn 以取得連線 ID。

• 若要透過 imqcmd 設定系統特性，請使用新的 –D 選項。這在設定或置換 JMS 連線工廠特性或連線相關的 Java 系統特性時，會很有用。例如：

  imqcmd list svc -secure -DimqSSLIsHostTrusted=true
  imqcmd list svc -secure -Djavax.net.ssl.trustStore=/tmp/mytruststore 
              -Djavax.net.ssl.trustStorePassword=mytrustword

如需有關 imqcmd 指令之語法的完整資訊，請參閱「Sun Java System Message Queue 4.1 Administration Guide」中的第 13 章「Command Line Reference」。

JDBC 永久性支援

現在支援將 Apache Derby 10.1.1 版視為 JDBC 相容永久存放區的提供者。

SSL 支援

自 4.0 版起，用戶端連線工廠特性 imqSSLIsHostTrusted 的預設值為 false。若應用程式相依於之前的預設值 true，您需要重新配置並將特性明確設定為 true。

當代理程式配置為使用自我簽署的憑證時，您可以選擇信任主機。此時，除了指定連線應使用基於 SSL 的連線服務 (使用 imqConnectionType 特性)，還應該將 imqSSLIsHostTrusted 特性設定為 true。

例如，若要在代理程式使用自我簽署的憑證時安全地執行用戶端應用程式，請使用如下的指令。

java -DimqConnectionType=TLS 
      -DimqSSLIsHostTrusted=true <ClientAppName>

若要在代理程式使用自我簽署的憑證時安全地執行管理工具 imqcmd，請使用如下的指令。

imqcmd list svc -secure -DimqSSLIsHostTrusted=true

JMX 支援

已增加符合 Java Management Extensions (JMX) 規格，且可用於配置與監視 Message Queue 代理程式的新 API。您可以使用此 API，從 Message Queue 用戶端應用程式內以程式化方式配置並監視代理程式功能。在 Message Queue 的早期版本中，這些功能只能從指令行或管理主控台存取。

API 包含一組 JMX 受管理 Bean (MBean)，以用於管理下列與 Message Queue 相關的資源：

• 訊息代理程式

• 連線服務

• 連線

• 目標

• 訊息產生器

• 訊息用戶

• 作業事件

• 代理程式叢集

• 記錄

• Java 虛擬機器 (JVM)

這些 MBean 提供一些屬性和作業，以同步輪詢與處理基礎資源的狀態，並提供通知，以允許用戶端應用程式以非同步方式偵聽並回應狀態變更。用戶端應用程式可使用 JMX API，執行如下的配置與監視作業：

• 設定代理程式的連接埠號

• 設定代理程式的最大訊息容量

• 暫停連線服務

• 設定連線服務的最大執行緒數目

• 取得目前服務中的連線數目

• 銷毀連線

• 建立目標

• 銷毀目標

• 啟用或停用自動建立目標

• 清除所有來自目標的訊息

• 取得自啟動代理程式以來，目標所接收的訊息累積數目

• 取得佇列的目前狀態 (執行中或已暫停)

• 取得主題目前的訊息產生器數目

• 清除所有來自長期用戶的訊息

• 取得目前 JVM 堆疊大小

如需有關 JMX API 的簡介以及完整參考資訊，請參閱「Sun Java System Message Queue 4.1 Developer’s Guide for JMX Clients」。

代理程式支援：JMX 相關特性

增加了數個新的代理程式特性以支援 JMX API (請參閱表 1–3)。您無法使用 Message Queue 指令公用程式 (imqcmd) 從指令行設定這些特性；而是要使用代理程式公用程式 (imqbrokerd) 的 -D 選項設定，或是在代理程式的實例配置檔案 (config.properties) 中手動編輯。此外，其中的部分特性 (imq.jmx.rmiregistry.start、 imq.jmx.rmiregistry.use、 imq.jmx.rmiregistry.port) 可以透過表 1–4 中所述之新的代理程式公用程式選項進行設定。該表列出每個選項、指定其類型，並說明其用途。

   /jndi/rmi://brokerHost:rmiPort
      /brokerHost/brokerPort/connectorName

   /stub/rmiStub

imq.jmx.connector.list 特性會定義一組在代理程式啟動時建立的已命名 JMX 連接器；imq.jmx.connector.activelist 會指定其中要啟動的連接器。每個已命名的連接器接著會有各自的特性集：

根據預設，會建立兩個 JMX 連接器，名為 jmxrmi 和 ssljmxrmi；第一個連接器會配置為不使用 SSL 加密 (imq.jmx.connector.jmxrmi.useSSL = false)，第二個連接器則使用 (imq.jmx.connector.ssljmxrmi.useSSL = true)。根據預設，代理程式啟動時只會啟動 jmxrmi 連接器；請參閱JMX 用戶端的 SSL 支援，以取得有關如何啟動 ssljmxrmi 連接器進行安全通訊的資訊。

為方便使用，還在指令行代理程式公用程式 (imqbrokerd) 中增加了新的選項 (表 1–4)，以控制 RMI 登錄的使用、啟動和連接埠。這些選項的用法和效果與其等效代理程式特性 (如表 1–3 中所述) 相同。該表列出每個選項、指定其等效代理程式特性，並說明其用法。

一個新的子指令 (表 1–5) 增加至指令行指令公用程式 (imqcmd)，以列出在代理程式啟動時建立和啟動的 JMX 連接器之 JMX 服務 URL。JMX 用戶端若要不使用 Message Queue 簡易類別 AdminConnectionFactory 即取得其 JMX 連接器，就需要此資訊。此資訊也可用於透過 Java 監視與管理主控台 (jconsole) 等一般 JMX 瀏覽器，來管理與監視 Message Queue。

JMX 用戶端的 SSL 支援

如上所述，預設會將 Message Queue 訊息代理程式配置為使用預先配置之 JMX 連接器 jmxrmi，進行不安全的通訊。應用程式若要使用安全傳輸層 (SSL) 進行安全通訊，則必須啟動另一個安全的 JMX 連接器 ssljmxrmi。此項作業需要下列步驟：

1. 如「Message Queue Administration Guide」中所述，使用與 ssljms、ssladmin 或 cluster 連線服務相同的方式取得並安裝簽署的憑證。

2. 視需要在信任清單存放區中安裝根憑證授權單位的憑證。

3. 將 ssljmxrmi 連接器增加至要在代理程式啟動時啟動的 JMX 連接器清單：

   imq.jmx.connector.activelist=jmxrmi,ssljmxrmi

4. 使用 Message Queue 代理程式公用程式 (imqbrokerd) 啟動代理程式，然後傳遞密碼檔案中的金鑰庫密碼，或在提示時從指令行輸入。

5. 根據預設，ssljmxrmi 連接器 (或任何其他基於 SSL 的連接器) 會配置為驗證所有提供給它的代理程式 SSL 憑證。若要避免此驗證 (例如，在軟體測試期間使用自我簽署的憑證時)，請將代理程式特性 imq.jmx.connector.ssljmxrmi.brokerHostTrusted 設定為 true。

配置用戶端的管理員連線工廠 (AdminConnectionFactory) 時，內含的 URL 必須指定 ssljmxrmi 為喜好的連接器：

AdminConnectionFactory  acf = new AdminConnectionFactory();
acf.setProperty(AdminConnectionConfiguration.imqAddress, "mq://myhost:7676/ssljmxrmi");

請視需要使用系統特性 javax.net.ssl.trustStore 和 javax.net.ssl.trustStorePassword，將 JMX 用戶端指向信任清單存放區。

用戶端執行階段記錄

本節說明 Message Queue 4.0 如何針對連線和階段作業相關事件，支援用戶端執行階段的記錄功能。

JDK 1.4 (及以上版本) 包含 java.util.logging 程式庫。此程式庫會實作可用於應用程式特定記錄的標準記錄程式介面。

Message Queue 用戶端執行階段使用 Java 記錄 API 實作其記錄功能。您可以使用所有 J2SE 1.4 記錄功能來配置記錄作業。例如，應用程式可使用下列 Java 記錄功能，配置 Message Queue 用戶端執行階段輸出其記錄資訊的方式：

• 記錄處理程式

• 記錄篩選器

• 記錄格式化程式

• 記錄層級

如需有關 Java 記錄 API 的更多資訊，請參閱「Java Logging Overview」，網址為 http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

記錄名稱空間、層級和作業

Message Queue 提供者會定義一組與記錄層級和記錄作業相關的記錄名稱空間，可在適當設定記錄配置時，讓 Message Queue 用戶端記錄連線與階段作業事件。

Message Queue 用戶端執行階段的根記錄名稱空間定義為 javax.jms。Message Queue 用戶端執行階段的所有記錄程式皆使用此名稱做為父系名稱空間。

Message Queue 用戶端執行階段使用的記錄層級與 java.util.logging.Level 類別中所定義的記錄層級相同。此類別會定義七個標準記錄層級，以及可用於啟動與關閉記錄的兩個其他設定。

OFF

關閉記錄。

SEVERE

最高優先權、最高值。由應用程式定義。

WARNING

由應用程式定義。

INFO

由應用程式定義。

CONFIG

由應用程式定義。

FINE

由應用程式定義。

FINER

由應用程式定義。

FINEST

最低優先權、最低值。由應用程式定義。

ALL

啟用所有訊息的記錄。

一般來說，Message Queue 用戶端執行階段中發生的異常與錯誤，皆由記錄程式使用 javax.jms 名稱空間所記錄。

• 從 JVM 丟出且由用戶端執行階段截獲的異常 (例如 IOException)，是由記錄程式使用記錄名稱空間 javax.jms 記錄在 WARNING 層級。

• 從用戶端執行階段丟出的 JMS 異常 (例如 IllegalStateException)，是由記錄程式使用記錄名稱空間 javax.jms 記錄在 FINER 層級。

• 從 JVM 丟出且由用戶端執行階段截獲的錯誤 (例如 OutOfMemoryError)，是由記錄程式使用記錄名稱空間 javax.jms 記錄在 SEVERE 層級。

下表列出可記錄的事件，以及必須設定的記錄層級以記錄 JMS 連線與階段作業事件。

下表說明連線的記錄層級與事件。

下列階段作業資訊會記錄在記錄中。

• 傳送給用戶的每筆訊息記錄包含 ConnectionID、SessionID 和 ConsumerID。

• 由產生器傳送的每筆訊息記錄包含 ConnectionID、SessionID、ProducerID 和目標名稱。

下表說明階段作業的記錄層級與事件。

根據預設，會從應用程式執行所在的 JRE 繼承輸出記錄層級。請檢查 JRE_DIRECTORY/lib/logging.properties 檔案以判斷該層級為何。

您可以程式化方式或藉由使用配置檔案來配置記錄功能，且可控制記錄發生的範圍。以下小節說明這些可能的作業。

使用 JRE 記錄配置檔案

下列範例說明如何在 JRE_DIRECTORY/lib/logging.properties 檔案中設定記錄名稱空間與層級，該檔案將用以設定 Java 執行階段環境的記錄層級。使用此 JRE 的所有應用程式會有相同的記錄配置。以下的配置範例會將 javax.jms.connection 名稱空間的記錄層級設定為 INFO，並指定將輸出寫入 java.util.logging.ConsoleHandler。

#logging.properties file.
# "handlers" specifies a comma separated list of log Handler 
# classes. These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.

	handlers= java.util.logging.ConsoleHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers. For any given facility this global level
# can be overriden by a facility-specific level.
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.

    .level= INFO

# Limit the messages that are printed on the console to INFO and above.

    java.util.logging.ConsoleHandler.level = INFO
    java.util.logging.ConsoleHandler.formatter = 
                                    java.util.logging.SimpleFormatter

# The logger with javax.jms.connection name space will write
# Level.INFO messages to its output handler(s). In this configuration 
# the ouput handler is set to java.util.logging.ConsoleHandler.

    javax.jms.connection.level = INFO

使用特定應用程式的記錄配置檔案

您也可以從用於執行應用程式的 Java 指令行來定義記錄配置檔案。應用程式會使用指定的記錄檔中所定義之配置。在下列範例中，configFile 使用 JRE_DIRECTORY/lib/logging.properties 檔案中所定義的相同格式。

java -Djava.util.logging.config.file=configFile MQApplication

以程式化方式設定記錄配置

下列程式碼使用 java.util.logging API，將 javax.jms.connection 名稱空間記錄層級變更為 FINE，以記錄連線事件。您可以在應用程式中包含這類程式碼，從而以程式化方式設定記錄配置。

import java.util.logging.*;
//construct a file handler and output to the mq.log file 
//in the system's temp directory.

    Handler fh = new FileHandler("%t/mq.log");
    fh.setLevel (Level.FINE);

//Get Logger for "javax.jms.connection" domain.

    Logger logger = Logger.getLogger("javax.jms.connection");
    logger.addHandler (fh);

//javax.jms.connection logger would log activities   
//with level FINE and above.

    logger.setLevel (Level.FINE);

連線事件通知

連線事件通知可讓 Message Queue 用戶端偵聽關閉事件與重新連線事件，並根據通知類型與連線狀態採取適當的動作。例如，當發生容錯移轉且用戶端重新連線至其他代理程式時，應用程式最好清除作業事件狀態，並進行新的作業事件。

如果 Message Queue 提供者偵測到嚴重的連線問題，它會呼叫連線物件的已註冊之異常偵聽程式。它會呼叫偵聽程式的 onException 方法，並傳遞描述問題的 JMSException 引數給該方法。Message Queue 提供者亦可提供事件通知 API，讓用戶端執行階段將連線狀態的變更通知應用程式。通知 API 由下列元素所定義：

• 定義事件偵聽程式及通知事件物件的 com.sun.messaging.jms.notification 套裝模組。

• 定義 javax.jms.Connection 介面延伸的 com.sun.messaging.jms.Connection 介面。

以下小節說明可觸發通知的事件，並說明建立事件偵聽程式的方式。

連線事件

下表列出並說明事件偵聽程式會傳回的事件。

請注意，發生連線事件時，不會呼叫 JMS 異常偵聽程式。只有在用戶端執行階段用盡重新連線的嘗試次數時，才會呼叫異常偵聽程式。用戶端執行階段一律會先呼叫事件偵聽程式，再呼叫異常偵聽程式。

建立事件偵聽程式

下列程式碼範例描述設定連線事件偵聽程式的方式。每次發生連線事件時，用戶端執行階段便會呼叫事件偵聽程式的 onEvent 方法。

//create an MQ connection factory.

com.sun.messaging.ConnectionFactory factory =
        new com.sun.messaging.ConnectionFactory();

//create an MQ connection.

com.sun.messaging.jms.Connection connection = 
       (com.sun.messaging.jms.Connection )factory.createConnection();

//construct an MQ event listener.  The listener implements 
//com.sun.messaging.jms.notification.EventListener interface.

com.sun.messaging.jms.notification.EventListener eListener = 
       new ApplicationEventListener();

//set event listener to the MQ connection.

connection.setEventListener ( eListener );

事件偵聽程式範例

在此範例中，應用程式選擇事件偵聽程式將連線事件記錄到應用程式的記錄系統：

public class ApplicationEventListener implements
				com.sun.messaging.jms.notification.EventListener {

public void onEvent ( com.sun.messaging.jms.notification.Event connEvent ) {
      	log (connEvent);
}
private void log ( com.sun.messaging.jms.notification.Event connEvent ) {
	      String eventCode = connEvent.getEventCode(); 
      	String eventMessage = connEvent.getEventMessage();
    	  //write event information to the output stream.
     	}
}

硬體與軟體需求

如需有關 4.0 版軟硬體需求的資訊，請參閱 Sun Java System Application Server Platform Edition 9 的版本說明。