パッケージ jakarta.jms
パッケージ jakarta.jms
Jakarta Messaging API は、Java プログラムがエンタープライズメッセージングシステムのメッセージを作成、送信、受信、読み取るための一般的な方法を提供します。
Jakarta Messaging Applications
Jakarta Messaging アプリケーションは、次の部分で構成されています。
- Jakarta Messaging プロバイダー - フル機能のメッセージング製品に必要な他の管理および制御機能に加えて、Jakarta Messaging API を実装するメッセージングシステム
- Jakarta Messaging クライアント - メッセージを送受信する Java 言語プログラム
- メッセージ - アプリケーションのクライアント間で情報を通信するために使用されるオブジェクト
- 管理対象オブジェクト - クライアントが Jakarta Messaging プロバイダーと移植可能に対話するために検索および使用するプロバイダー固有のオブジェクト
- 非 Jakarta メッセージングクライアント -Jakarta Messaging API の代わりにメッセージシステムのネイティブクライアント API を使用するクライアント。アプリケーションが Jakarta Messaging API の可用性よりも前の場合、Jakarta Messaging クライアントと非 Jakarta メッセージングクライアントの両方が含まれる可能性があります。
管理
Jakarta Messaging プロバイダーは、基盤となるメッセージングテクノロジーの実装が大きく異なります。Jakarta Messaging プロバイダーのシステムのインストール方法と管理方法にも大きな違いがあります。
Jakarta Messaging クライアントを移植可能にするには、プロバイダーのこれらの独自の側面から分離する必要があります。これは、プロバイダーの管理者によって作成およびカスタマイズされ、後でクライアントによって使用される Jakarta Messaging 管理対象オブジェクトを定義することによって行われます。クライアントは、移植可能な Jakarta Messaging インターフェースを介して使用します。管理者は、プロバイダー固有の機能を使用して作成します。
Jakarta Messaging 管理対象オブジェクトには次の 2 つの型があります。
ConnectionFactory- クライアントが Jakarta Messaging プロバイダーとの接続を作成するために使用するオブジェクトDestination- クライアントが送信するメッセージの宛先と受信するメッセージのソースを指定するために使用するオブジェクト
管理対象オブジェクトは、管理者によって JNDI（Java Naming and Directory Interface）名前空間に配置されます。Jakarta Messaging クライアントは通常、ドキュメントに、必要な Jakarta Messaging 管理対象オブジェクトと、これらのオブジェクトの JNDI 名をどのように提供するかを記載しています。
2 つのメッセージングスタイル
Jakarta Messaging は、次の 2 つのメッセージングスタイルをサポートしています。
- キューを使用したポイントツーポイント（PTP）メッセージング
- トピックを使用したパブリッシュアンドサブスクライブ（pub/ サブ）メッセージング
これらの 2 つのスタイルは、現在使用されているメッセージングへの 2 つの主要なアプローチを表しています。
Jakarta Messaging API
歴史的な理由から、Jakarta Messaging は、メッセージを送受信するための 4 つの代替インターフェースセットを提供します。
- Java Message Service 1.0 は、2 つのドメイン固有 API を定義しました。1 つはポイントツーポイントメッセージング（キュー）用で、もう 1 つは pub/sub（トピック）用です。これらは下位互換性の理由から Jakarta Messaging の一部のままですが、後の API によって完全に置き換えられると見なす必要があります。
- Java メッセージサービス 1.1 は、ポイントツーポイントメッセージングと pub/ サブメッセージングの両方に使用できる単一のインターフェースセットを提供する新しい統合 API を導入しました。これは、ここではクラシック API と呼ばれます。
- Jakarta Messaging 2.0 は、従来の API のすべての機能を提供するが、必要なインターフェースが少なく、使用が簡単な簡略化された API を導入しています。
各 API は、Jakarta Messaging プロバイダーに接続し、メッセージを送受信するための異なるインターフェースのセットを提供します。ただし、これらはすべて、メッセージとメッセージの宛先を表し、さまざまなユーティリティ機能を提供するための共通のインターフェースセットを共有しています。
すべてのインターフェースは jakarta.jms パッケージに含まれています。
Interfaces common to multiple API
複数の API に共通する主なインターフェースは次のとおりです。
Message、BytesMessage、MapMessage、ObjectMessage、StreamMessage、TextMessage- Jakarta Messaging プロバイダーとの間で送受信されるメッセージ。Queue- ポイントツーポイントメッセージングのメッセージ宛先の ID をカプセル化する管理対象オブジェクトTopic- pub/ サブメッセージングのメッセージ宛先の ID をカプセル化する管理対象オブジェクト。Destination-QueueとTopicの一般的なスーパー型
Classic API interfaces
従来の API によって提供される主なインターフェースは次のとおりです。ConnectionFactory- クライアントがConnectionを作成するために使用する管理対象オブジェクト。このインターフェースは、簡略化された API でも使用されます。Connection- Jakarta Messaging プロバイダーへのアクティブな接続Session- メッセージを送受信するためのシングルスレッドコンテキストMessageProducer- キューまたはトピックにメッセージを送信するために使用されるセッションによって作成されたオブジェクトMessageConsumer- キューまたはトピックに送信されたメッセージの受信に使用されるセッションによって作成されたオブジェクト
Simplified API interfaces
簡略化された API は、従来の API と同じメッセージング機能を提供しますが、必要なインターフェースが少なく、使用が簡単です。簡略化された API によって提供される主なインターフェースは次のとおりです。ConnectionFactory- クライアントがJMSContextを作成するために使用する管理対象オブジェクト。このインターフェースは、従来の API でも使用されます。JMSContext- Jakarta Messaging プロバイダーへのアクティブな接続と、メッセージを送受信するためのシングルスレッドコンテキストJMSProducer- キューまたはトピックにメッセージを送信するために使用されるJMSContextによって作成されたオブジェクトJMSConsumer- キューまたはトピックに送信されたメッセージを受信するために使用されるJMSContextによって作成されたオブジェクト
Legacy domain-specific API interfaces
ドメイン固有の API は、下位互換性の理由から Jakarta Messaging の一部のままですが、従来の単純化された API に完全に取って代わられると見なす必要があります。
ポイントツーポイントメッセージング用のドメイン固有 API によって提供される主なインターフェースは次のとおりです。
QueueConnectionFactory- クライアントがQueueConnectionを作成するために使用する管理対象オブジェクト。QueueConnection- Jakarta Messaging プロバイダーへのアクティブな接続QueueSession- メッセージを送受信するためのシングルスレッドコンテキストQueueSender- キューにメッセージを送信するために使用されるQueueSessionによって作成されたオブジェクトQueueReceiver- キューに送信されたメッセージの受信に使用されるQueueSessionによって作成されたオブジェクト
TopicConnectionFactory- クライアントがTopicConnectionを作成するために使用する管理対象オブジェクト。TopicConnection- Jakarta Messaging プロバイダーへのアクティブな接続TopicSession- メッセージを送受信するためのシングルスレッドコンテキストTopicPublisher- トピックにメッセージを送信するために使用されるTopicSessionによって作成されたオブジェクトTopicSubscriber- トピックに送信されたメッセージの受信に使用されるTopicSessionによって作成されたオブジェクト
メッセージを送受信するための用語
このドキュメントでは、「消費」という用語は、Jakarta Messaging クライアントによるメッセージの受信を意味するために使用されます。つまり、Jakarta Messaging プロバイダーがメッセージを受信し、それをクライアントに渡しました。Jakarta Messaging はメッセージの同期受信と非同期受信の両方をサポートしているため、消費という用語は、区別する必要がない場合に使用されます。
生成という用語は、メッセージを送信するための最も一般的な用語として使用されます。これは、宛先に配信するために Jakarta Messaging プロバイダーにメッセージを送信することを意味します。
Jakarta Messaging Application の開発
大まかに言えば、Jakarta Messaging アプリケーションは、メッセージを交換する 1 つ以上の Jakarta Messaging クライアントです。このアプリケーションには、JakartaMessaging 以外のクライアントも含まれる場合があります。ただし、これらのクライアントは、Jakarta Messaging API の代わりに Jakarta Messaging プロバイダーのネイティブ API を使用します。
Jakarta Messaging アプリケーションは、ユニットとして設計およびデプロイできます。多くの場合、Jakarta Messaging クライアントは既存のアプリケーションに段階的に追加されます。
アプリケーションによって使用されるメッセージ定義は、JMS で作成されている場合もあれば、アプリケーションの非 Jakarta メッセージング部分によって定義されている場合もあります。
Jakarta Messaging Client の開発
従来の API を使用する一般的な Jakarta Messaging クライアントは、次の Jakarta Messaging セットアップ手順を実行します。
- JNDI を使用して
ConnectionFactoryオブジェクトを検索します - JNDI を使用して、1 つ以上の
Destinationオブジェクトを検索します - ConnectionFactory を使用して、メッセージ配信が禁止された Jakarta Messaging
Connectionオブジェクトを作成します - 接続を使用して、1 つ以上の Jakarta Messaging
Sessionオブジェクトを作成します - セッションと宛先を使用して、必要な
MessageProducerオブジェクトとMessageConsumerオブジェクトを作成します - メッセージの配信を開始するように
Connectionに指示します
対照的に、簡略化された API を使用する一般的な Jakarta Messaging クライアントは、次のことを行います。
- JNDI を使用して
ConnectionFactoryオブジェクトを検索します - JNDI を使用して、1 つ以上の
Destinationオブジェクトを検索します ConnectionFactoryを使用してJMSContextオブジェクトを作成しますJMSContextを使用して、必要なJMSProducerおよびJMSConsumerオブジェクトを作成します。- メッセージの配信が自動的に開始されます
この時点で、クライアントはメッセージを生成および消費するために必要な基本的な Jakarta Messaging セットアップを持っています。
パッケージ仕様
Jakarta Messaging 3.1 仕様
関連資料
Jakarta Enterprise Edition Technical Documentation
- クラス説明
BytesMessageオブジェクトは、解釈されないバイトのストリームを含むメッセージを送信するために使用されます。CompletionListenerはアプリケーションによって実装され、メッセージが非同期に送信されるときに指定できます。Connectionオブジェクトは、Jakarta Messaging プロバイダーへのクライアントのアクティブな接続です。アプリケーションサーバーの場合、ConnectionオブジェクトはConnectionConsumerを作成するための特別な機能を提供します（オプション）。ConnectionFactoryオブジェクトは、管理者が定義した一連の接続構成パラメーターをカプセル化します。ConnectionMetaDataオブジェクトは、Connectionオブジェクトを説明する情報を提供します。Jakarta Messaging API でサポートされている配信モードはPERSISTENTおよびNON_PERSISTENTです。Destinationオブジェクトは、プロバイダー固有のアドレスをカプセル化します。Jakarta Messaging プロバイダーは、Connectionオブジェクトに重大な問題を検出すると、ConnectionオブジェクトのExceptionListenerが登録されているかどうかを通知します。この例外は、メソッドが不正または不適切なときに呼び出された場合、またはプロバイダーがリクエストされた操作に対して適切な状態にない場合にスローされます。このチェックされていない例外は、メソッドが不正または不適切なタイミングで呼び出された場合、またはプロバイダーがリクエストされた操作に対して適切な状態にない場合にスローされ、メソッドシグネチャーはIllegalStateRuntimeExceptionのスローを許可しません。クライアントが接続のクライアント ID をプロバイダーによって拒否された値に設定しようとすると、この例外がスローされる必要があります。このチェックされていない例外は、クライアントが接続のクライアント ID をプロバイダーによって拒否された値に設定しようとしたときにスローする必要があり、メソッドシグネチャーはInvalidClientIDExceptionのスローを許可しません。この例外は、宛先がプロバイダーに認識されないか、無効になった場合にスローする必要があります。このチェックされていない例外は、宛先がプロバイダーによって理解されないか、無効になった場合にスローする必要があり、メソッドシグネチャーがInvalidDestinationExceptionのスローを許可しません。この例外は、Jakarta Messaging クライアントが無効な構文のメッセージセレクターをプロバイダーに提供しようとしたときにスローされる必要があります。このチェックされていない例外は、Jakarta Messaging クライアントが無効な構文を使用してプロバイダーにメッセージセレクターを提供しようとし、メソッドシグネチャーがInvalidSelectorExceptionのスローを許可していない場合にスローする必要があります。このアノテーションをフィールドで使用して、jakarta.jms.JMSContextオブジェクトを挿入するときに使用するjakarta.jms.ConnectionFactoryの JNDI ルックアップ名を指定できます。アプリケーションはこのアノテーションを使用して、運用環境で必要な Jakarta MessagingConnectionFactoryリソースを指定できます。1 つ以上のJMSConnectionFactoryDefinitionアノテーションを指定します。Jakarta Messaging 2.0 に導入された簡略化された Jakarta Messaging API を使用するクライアントは、JMSConsumerオブジェクトを使用して、キューまたはトピックからメッセージを受信します。JMSContextは、Jakarta Messaging 2.0 用に導入された簡略化された Jakarta Messaging API のメインインターフェースです。アプリケーションはこのアノテーションを使用して、運用環境で必要な Jakarta MessagingDestinationリソースを指定できます。1 つ以上のJMSDestinationDefinitionアノテーションを指定します。これは、Jakarta Messaging API のすべてのチェック済み例外のルートクラスです。このアノテーションは、jakarta.jms.JMSContextオブジェクトを挿入するときに使用する userName とパスワードを指定するために使用できます。JMSProducerは、JMSContextに代わってメッセージを送信するために使用される単純なオブジェクトです。これは、Jakarta Messaging API のすべての未チェックの例外のルートクラスです。この例外は、プロバイダーがクライアントから送信されたユーザー名 / パスワードを拒否した場合にスローする必要があります。このチェックされていない例外は、プロバイダーがクライアントから送信されたユーザー名 / パスワードを拒否した場合、またはセキュリティ制限によりメソッドが完了できず、メソッドシグネチャーがJMSSecurityExceptionのスローを許可していない場合にスローする必要があります。このアノテーションは、jakarta.jms.JMSContextオブジェクトを挿入するときに使用されるセッションモードを指定するために使用できます。MapMessageオブジェクトは、名前と値のペアのセットを送信するために使用されます。Messageインターフェースは、すべての Jakarta Messaging メッセージのルートインターフェースです。クライアントはMessageConsumerオブジェクトを使用して、宛先からメッセージを受信します。この例外は、StreamMessageまたはBytesMessageの読み取り中にストリームの予期しない終わりに達した場合にスローする必要があります。この例外は、Jakarta Messaging クライアントがメッセージでサポートされていないデータ型を使用しようとしたり、メッセージ内のデータを間違った型として読み取ったりした場合にスローする必要があります。このチェックされていない例外は、Jakarta Messaging アプリケーションがメッセージでサポートされていないデータ型を使用しようとしたり、メッセージ内のデータを誤った型として読み取ったりしようとした場合にスローする必要があり、メソッドシグネチャーはMessageFormatExceptionのスローを許可しません。MessageListenerオブジェクトは、非同期で配信されるメッセージを受信するために使用されます。この例外は、Jakarta Messaging クライアントが書き込み専用メッセージを読み取ろうとしたときにスローされる必要があります。この例外は、Jakarta Messaging クライアントが読み取り専用メッセージに書き込もうとしたときにスローされる必要があります。このチェックされていない例外は、Jakarta Messaging クライアントが読み取り専用メッセージに書き込もうとしたときにスローされる必要があります。クライアントはMessageProducerオブジェクトを使用して宛先にメッセージを送信します。ObjectMessageオブジェクトは、Java プログラミング言語の直列化可能オブジェクト（「Java オブジェクト」）を含むメッセージを送信するために使用されます。Queueオブジェクトは、プロバイダー固有のキュー名をカプセル化します。クライアントはQueueBrowserオブジェクトを使用して、キューのメッセージを削除せずに調べます。QueueConnectionオブジェクトは、ポイントツーポイントの Jakarta Messaging プロバイダーへのアクティブな接続です。クライアントはQueueConnectionFactoryオブジェクトを使用して、ポイントツーポイントの Jakarta Messaging プロバイダーでQueueConnectionオブジェクトを作成します。クライアントは、QueueReceiverオブジェクトを使用して、キューに配信されたメッセージを受信します。QueueRequestorヘルパークラスは、サービスリクエストの作成を簡素化します。クライアントはQueueSenderオブジェクトを使用してメッセージをキューに送信します。QueueSessionオブジェクトは、QueueReceiver、QueueSender、QueueBrowser、TemporaryQueueオブジェクトを作成するためのメソッドを提供します。この例外は、プロバイダーがメソッドに必要なリソースを割り当てることができない場合にスローされます。この未チェックの例外は、プロバイダーがメソッドに必要なリソースを割り当てることができない場合にスローされます。ServerSessionオブジェクトは、サーバーがスレッドを Jakarta Messaging セッションに関連付けるために使用するアプリケーションサーバーオブジェクトです（オプション）。ServerSessionPoolオブジェクトは、ConnectionConsumerのメッセージを処理するためのServerSessionオブジェクトのプールを提供するためにアプリケーションサーバーによって実装されるオブジェクトです（オプション）。Sessionオブジェクトは、メッセージを生成および消費するためのシングルスレッドコンテキストです。StreamMessageオブジェクトは、Java プログラミング言語でプリミティブ型のストリームを送信するために使用されます。TemporaryQueueオブジェクトは、Connectionの期間中に作成される一意のQueueオブジェクトです。TemporaryTopicオブジェクトは、Connectionの期間中に作成される一意のTopicオブジェクトです。TextMessageオブジェクトは、java.lang.Stringを含むメッセージを送信するために使用されます。Topicオブジェクトは、プロバイダー固有のトピック名をカプセル化します。TopicConnectionオブジェクトは、パブリッシュ / サブスクライブ Jakarta Messaging プロバイダーへのアクティブな接続です。クライアントはTopicConnectionFactoryオブジェクトを使用して、パブリッシュ / サブスクライブ Jakarta Messaging プロバイダーでTopicConnectionオブジェクトを作成します。クライアントはTopicPublisherオブジェクトを使用してトピックに関するメッセージを公開します。TopicRequestorヘルパークラスは、サービスリクエストの作成を簡素化します。TopicSessionオブジェクトは、TopicPublisher、TopicSubscriber、TemporaryTopicオブジェクトを作成するためのメソッドを提供します。クライアントはTopicSubscriberオブジェクトを使用して、トピックに発行されたメッセージを受信します。この例外は、トランザクションが進行中であるために操作が無効な場合にスローされます。この未チェックの例外は、トランザクションが進行中であるために操作が無効な場合にスローされます。この例外は、Session.commitの呼び出しにより現在のトランザクションがロールバックされる場合にスローする必要があります。このチェックされていない例外は、JMSContext.commitの呼び出しの結果、現在のトランザクションがロールバックされる場合にスローする必要があります。XAConnectionインターフェースは、XASession（オプション）を提供することにより、Connectionの機能を継承します。XAConnectionFactoryインターフェースは、XAQueueConnectionFactoryおよびXATopicConnectionFactoryインターフェースの基本インターフェースです。XAJMSContextインターフェースは、Jakarta Messaging プロバイダーの Java Transaction API（JTA）に対するサポートへのアクセスを追加することにより、JMSContextの機能を継承します（オプション）。XAQueueConnectionは、QueueConnectionと同じ作成オプションを提供します（オプション）。XAQueueConnectionFactoryは、QueueConnectionFactoryと同じ作成オプションを提供します（オプション）。XAQueueSessionは、通常のQueueSessionを提供します。これは、QueueReceiver、QueueSender、QueueBrowserオブジェクトの作成に使用できます（オプション）。XASessionインターフェースは、Jakarta Messaging プロバイダーの Java Transaction API（JTA）に対するサポートへのアクセスを追加することにより、Sessionの機能を継承します（オプション）。XATopicConnectionは、TopicConnectionと同じ作成オプションを提供します（オプション）。XATopicConnectionFactoryは、TopicConnectionFactoryと同じ作成オプションを提供します（オプション）。XATopicSessionは、通常のTopicSessionを提供します。これは、TopicSubscriberおよびTopicPublisherオブジェクトの作成に使用できます（オプション）。