Azure 服務匯流排 JMS 2.0 開發人員指南
本指南包含了可協助您使用 JAVA 訊息服務 (JMS) 2.0 API 與 Azure 服務匯流排通訊的詳細資訊。
如果身為 Java 開發人員的您不熟悉 Azure 服務匯流排，請考慮閱讀下列文章。
| 開始使用 | 概念 |
|---|---|
JAVA 訊息服務 (JMS) 程式設計模型
Java 訊息服務 API 程式設計模型如下列幾節所示：
注意
Azure 服務匯流排進階層支援 JMS 1.1 和 JMS 2.0。
Azure 服務匯流排 - 標準層支援 JMS 1.1 的有限功能。 如需更多詳細資料，請參閱此文件。
JMS - 建置組塊
下列建置組塊可用來與 JMS 應用程式通訊。
連線中心
連線中心物件能讓用戶端用來與 JMS 提供者連線。 連線中心會封裝系統管理員所定義的一組連線組態參數。
每個連線中心都是 ConnectionFactory、QueueConnectionFactory 或 TopicConnectionFactory 介面的執行個體。
為了簡化與 Azure 服務匯流排的連線，這些介面會分別透過 ServiceBusJmsConnectionFactory、ServiceBusJmsQueueConnectionFactory 或 ServiceBusJmsTopicConnectionFactory 進行實作。
重要
利用 JMS 2.0 API 的 Java 應用程式可以連線到 Azure 服務匯流排，方法為使用連接字串，或使用 TokenCredential，用於利用 Microsoft Entra 支援的驗證。 使用 Microsoft Entra 支援的驗證時，請務必視需要將角色和權限指派給身分識別。
在 Azure 上建立系統指派的受控識別，並使用此身分識別來建立 TokenCredential。
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
連線中心接著可以使用下列參數來具現化。
- 權杖認證 - 代表能夠提供 OAuth 權杖的認證。
- 主機 - Azure 服務匯流排進階層命名空間的主機名稱。
- ServiceBusJmsConnectionFactorySettings 屬性包，其中包含
- connectionIdleTimeoutMS - 以毫秒為單位的閒置連線逾時。
- traceFrames - 用以收集 AMQP 追蹤框架來進行偵錯的布林值旗標。
- 其他組態參數
您可以建立如下所示的中心。 權杖認證和主機是必要參數，但其他屬性是選用的。
String host = "<YourNamespaceName>.servicebus.windows.net";
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(tokenCredential, host, null);
JMS 目的地
目的地是用戶端用來指定產生的訊息要前往何處的目標，以及其取用訊息來源的物件。
目的地會對應至 Azure 服務匯流排中的實體 - 佇列 (在點對點傳送的使用情境下) 以及主題 (在發佈/訂閱的使用情境下)。
連線
連線會以 JMS 提供者封裝虛擬連線。 使用 Azure 服務匯流排，這代表了應用程式透過 AMQP 與 Azure 服務匯流排之間的具狀態連線。
連線是從連線中心建立的，如下列範例所示：
Connection connection = factory.createConnection();
工作階段
工作階段是用於產生及取用訊息的單一執行緒內容。 它可以用來建立訊息、訊息產生者和取用者，但也能提供異動內容，藉此將送出和接收到的訊息分組至不可部分完成的工作單位。
您可以從連線物件建立工作階段，如下列範例所示：
Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);
注意
JMS API 不支援從已啟用訊息工作階段的服務匯流排佇列或主題接收訊息。
工作階段模式
您可以使用下列任何模式來建立工作階段。
| 工作階段模式 | 行為 |
|---|---|
| Session.AUTO_ACKNOWLEDGE | 當不論是工作階段成功地傳回了對於接收的呼叫，或是工作階段所呼叫，負責處理訊息的訊息接聽程式成功地傳回時，工作階段便會自動確認客戶端收到了一個訊息。 |
| Session.CLIENT_ACKNOWLEDGE | 用戶端會藉由呼叫訊息的確認方法，來確認已取用的訊息。 |
| Session.DUPS_OK_ACKNOWLEDGE | 此確認模式會指示工作階段延遲確認訊息的傳遞。 |
| Session.SESSION_TRANSACTED | 這個值可以當做引數並傳遞至方法 createSession(int sessionMode) 連接物件上，以指定工作階段應該使用本機交易。 |
未指定工作階段模式時，預設會挑選 Session.AUTO_ACKNOWLEDGE。
JMSContext
注意
JMSCoNtext 定義為 JMS 2.0 規格的一部分。
JMSCoNtext 結合了連線和工作階段物件所提供的功能。 您可以從連線中心物件建立它。
JMSContext context = connectionFactory.createContext();
JMSCoNtext 模式
就像工作階段物件一樣，JMSCoNtext 可以使用與工作階段模式中所述相同的確認模式來建立。
JMSContext context = connectionFactory.createContext(JMSContext.AUTO_ACKNOWLEDGE);
未指定模式時，預設會挑選 JMSContext.AUTO_ACKNOWLEDGE。
JMS 訊息產生者
訊息產生者是使用 JMSCoNtext 或工作階段所建立的物件，用於將訊息傳送至目的地。
其可以建立為獨立物件，如下列範例所示：
JMSProducer producer = context.createProducer();
或者，在需要傳送訊息時於執行階段建立。
context.createProducer().send(destination, message);
JMS 訊息取用者
訊息取用者是由 JMSCoNtext 或工作階段所建立的物件，用於接收傳送至目的地的訊息。 其建立方式如下列範例所示：
JMSConsumer consumer = context.createConsumer(dest);
透過 receive() 方法同步接收
訊息取用者提供透過 receive() 方法，提供了一種同步接收來自目的地訊息的方式。
如果未指定任何引數/逾時，或將逾時指定為 '0'，否則直到訊息送達之前，取用者將會會無限期封鎖，或連線將會中斷 (視何者稍早較早發生而定)。
Message m = consumer.receive();
Message m = consumer.receive(0);
當提供非零的正引數時，取用者會持續封鎖，直到該計時器到期為止。
Message m = consumer.receive(1000); // time out after one second.
使用 JMS 訊息接聽程式進行非同步接收
訊息接聽程式是一種用於在目的地上非同步處理訊息的物件。 其會實作 MessageListener 介面，其中包含了特定商務邏輯必須在其中存續的 onMessage 方法。
訊息接聽程式物件必須使用 setMessageListener 方法來具現化並註冊到特定的訊息取用者上。
Listener myListener = new Listener();
consumer.setMessageListener(myListener);
從主題取用
JMS 訊息取用者會針對目的地建立，此目的地可以是佇列或主題。
佇列上的取用者只是位於用戶端應用程式與 Azure 服務匯流排之間工作階段 (和連線) 內容的用戶端物件。
但是主題上的取用者則分為 2 個部分 -
- 位於工作階段 (或 JMSCoNtext) 中的用戶端物件，以及
- 位於 Azure 服務匯流排上的訂閱實體。
訂用帳戶記載於這裡，而且可以是下列其中一個：
- 共用永久性訂閱
- 共用非永久性訂閱
- 非共用永久性訂閱
- 非共用非永久性訂閱
JMS 佇列瀏覽器
JMS API 提供了 QueueBrowser 物件，可讓應用程式流覽佇列中的訊息，並顯示每個訊息的標頭值。
您可以使用 JMSContext 來建立佇列瀏覽器，如下列範例所示：
QueueBrowser browser = context.createBrowser(queue);
注意
JMS API 不提供用以瀏覽主題的 API。
這是因為主題本身不會儲存訊息。 一旦訊息傳送至主題後，就會被轉送至適當的訂閱。
JMS 訊息選取器
接收端應用程式可以使用訊息選取器來篩選收到的訊息。 透過訊息選取器，接收端應用程式會將篩選訊息的工作卸載至 JMS 提供者 (在此案例中即為 Azure 服務匯流排)，而不是自行承擔該責任。
建立下列任一取用者時，即可以使用選取器 -
- 共用永久性訂閱
- 非共用永久性訂閱
- 共用非永久性訂閱
- 非共用非永久性訂閱
- 佇列瀏覽器
AMQP 配置和服務匯流排作業對應
以下是 AMQP 配置轉譯為服務匯流排作業的方式：
ACCEPTED = 1; -> Complete()
REJECTED = 2; -> DeadLetter()
RELEASED = 3; (just unlock the message in service bus, will then get redelivered)
MODIFIED_FAILED = 4; -> Abandon() which increases delivery count
MODIFIED_FAILED_UNDELIVERABLE = 5; -> Defer()
摘要
此開發人員指南示範使用 JAVA 訊息服務 (JMS) 的 JAVA 用戶端應用程式能如何與 Azure 服務匯流排進行連線。
下一步
如需 Azure 服務匯流排的詳細資訊和 Java 訊息服務 (JMS) 實體的詳細資料，請參閱下列文章：