パッケージ 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 BytesMessageオブジェクトは、解釈されないバイトのストリームを含むメッセージを送信するために使用されます。CompletionListener CompletionListenerはアプリケーションによって実装され、メッセージが非同期に送信されるときに指定できます。Connection Connectionオブジェクトは、Jakarta Messaging プロバイダーへのクライアントのアクティブな接続です。ConnectionConsumer アプリケーションサーバーの場合、ConnectionオブジェクトはConnectionConsumerを作成するための特別な機能を提供します（オプション）。ConnectionFactory ConnectionFactoryオブジェクトは、管理者が定義した一連の接続構成パラメーターをカプセル化します。ConnectionMetaData ConnectionMetaDataオブジェクトは、Connectionオブジェクトを説明する情報を提供します。DeliveryMode Jakarta Messaging API でサポートされている配信モードはPERSISTENTおよびNON_PERSISTENTです。Destination Destinationオブジェクトは、プロバイダー固有のアドレスをカプセル化します。ExceptionListener Jakarta Messaging プロバイダーは、Connectionオブジェクトに重大な問題を検出すると、ConnectionオブジェクトのExceptionListenerが登録されているかどうかを通知します。JMSConsumer Jakarta Messaging 2.0 に導入された簡略化された Jakarta Messaging API を使用するクライアントは、JMSConsumerオブジェクトを使用して、キューまたはトピックからメッセージを受信します。JMSContext JMSContextは、Jakarta Messaging 2.0 用に導入された簡略化された Jakarta Messaging API のメインインターフェースです。JMSProducer JMSProducerは、JMSContextに代わってメッセージを送信するために使用される単純なオブジェクトです。MapMessage MapMessageオブジェクトは、名前と値のペアのセットを送信するために使用されます。Message Messageインターフェースは、すべての Jakarta Messaging メッセージのルートインターフェースです。MessageConsumer クライアントはMessageConsumerオブジェクトを使用して、宛先からメッセージを受信します。MessageListener MessageListenerオブジェクトは、非同期で配信されるメッセージを受信するために使用されます。MessageProducer クライアントはMessageProducerオブジェクトを使用して宛先にメッセージを送信します。ObjectMessage ObjectMessageオブジェクトは、Java プログラミング言語の直列化可能オブジェクト（「Java オブジェクト」）を含むメッセージを送信するために使用されます。Queue Queueオブジェクトは、プロバイダー固有のキュー名をカプセル化します。QueueBrowser クライアントはQueueBrowserオブジェクトを使用して、キューのメッセージを削除せずに調べます。QueueConnection QueueConnectionオブジェクトは、ポイントツーポイントの Jakarta Messaging プロバイダーへのアクティブな接続です。QueueConnectionFactory クライアントはQueueConnectionFactoryオブジェクトを使用して、ポイントツーポイントの Jakarta Messaging プロバイダーでQueueConnectionオブジェクトを作成します。QueueReceiver クライアントは、QueueReceiverオブジェクトを使用して、キューに配信されたメッセージを受信します。QueueSender クライアントはQueueSenderオブジェクトを使用してメッセージをキューに送信します。QueueSession QueueSessionオブジェクトは、QueueReceiver、QueueSender、QueueBrowser、TemporaryQueueオブジェクトを作成するためのメソッドを提供します。ServerSession ServerSessionオブジェクトは、サーバーがスレッドを Jakarta Messaging セッションに関連付けるために使用するアプリケーションサーバーオブジェクトです（オプション）。ServerSessionPool ServerSessionPoolオブジェクトは、ConnectionConsumerのメッセージを処理するためのServerSessionオブジェクトのプールを提供するためにアプリケーションサーバーによって実装されるオブジェクトです（オプション）。Session Sessionオブジェクトは、メッセージを生成および消費するためのシングルスレッドコンテキストです。StreamMessage StreamMessageオブジェクトは、Java プログラミング言語でプリミティブ型のストリームを送信するために使用されます。TemporaryQueue TemporaryQueueオブジェクトは、Connectionの期間中に作成される一意のQueueオブジェクトです。TemporaryTopic TemporaryTopicオブジェクトは、Connectionの期間中に作成される一意のTopicオブジェクトです。TextMessage TextMessageオブジェクトは、java.lang.Stringを含むメッセージを送信するために使用されます。Topic Topicオブジェクトは、プロバイダー固有のトピック名をカプセル化します。TopicConnection TopicConnectionオブジェクトは、パブリッシュ / サブスクライブ Jakarta Messaging プロバイダーへのアクティブな接続です。TopicConnectionFactory クライアントはTopicConnectionFactoryオブジェクトを使用して、パブリッシュ / サブスクライブ Jakarta Messaging プロバイダーでTopicConnectionオブジェクトを作成します。TopicPublisher クライアントはTopicPublisherオブジェクトを使用してトピックに関するメッセージを公開します。TopicSession TopicSessionオブジェクトは、TopicPublisher、TopicSubscriber、TemporaryTopicオブジェクトを作成するためのメソッドを提供します。TopicSubscriber クライアントはTopicSubscriberオブジェクトを使用して、トピックに発行されたメッセージを受信します。XAConnection XAConnectionインターフェースは、XASession（オプション）を提供することにより、Connectionの機能を継承します。XAConnectionFactory XAConnectionFactoryインターフェースは、XAQueueConnectionFactoryおよびXATopicConnectionFactoryインターフェースの基本インターフェースです。XAJMSContext XAJMSContextインターフェースは、Jakarta Messaging プロバイダーの Java Transaction API（JTA）に対するサポートへのアクセスを追加することにより、JMSContextの機能を継承します（オプション）。XAQueueConnection XAQueueConnectionは、QueueConnectionと同じ作成オプションを提供します（オプション）。XAQueueConnectionFactory XAQueueConnectionFactoryは、QueueConnectionFactoryと同じ作成オプションを提供します（オプション）。XAQueueSession XAQueueSessionは、通常のQueueSessionを提供します。これは、QueueReceiver、QueueSender、QueueBrowserオブジェクトの作成に使用できます（オプション）。XASession XASessionインターフェースは、Jakarta Messaging プロバイダーの Java Transaction API（JTA）に対するサポートへのアクセスを追加することにより、Sessionの機能を継承します（オプション）。XATopicConnection XATopicConnectionは、TopicConnectionと同じ作成オプションを提供します（オプション）。XATopicConnectionFactory XATopicConnectionFactoryは、TopicConnectionFactoryと同じ作成オプションを提供します（オプション）。XATopicSession XATopicSessionは通常のTopicSessionを提供します。クラスのサマリー クラス 説明 QueueRequestor QueueRequestorヘルパークラスは、サービスリクエストの作成を簡素化します。TopicRequestor TopicRequestorヘルパークラスは、サービスリクエストの作成を簡素化します。例外のサマリー 例外 説明 IllegalStateException この例外は、メソッドが不正または不適切なときに呼び出された場合、またはプロバイダーがリクエストされた操作に対して適切な状態にない場合にスローされます。IllegalStateRuntimeException このチェックされていない例外は、メソッドが不正または不適切なタイミングで呼び出された場合、またはプロバイダーがリクエストされた操作に対して適切な状態にない場合にスローされ、メソッドシグネチャーはIllegalStateRuntimeExceptionのスローを許可しません。InvalidClientIDException クライアントが接続のクライアント ID をプロバイダーによって拒否された値に設定しようとすると、この例外がスローされる必要があります。InvalidClientIDRuntimeException このチェックされていない例外は、クライアントが接続のクライアント ID をプロバイダーによって拒否された値に設定しようとしたときにスローする必要があり、メソッドシグネチャーはInvalidClientIDExceptionのスローを許可しません。InvalidDestinationException この例外は、宛先がプロバイダーに認識されないか、無効になった場合にスローする必要があります。InvalidDestinationRuntimeException このチェックされていない例外は、宛先がプロバイダーによって理解されないか、無効になった場合にスローする必要があり、メソッドシグネチャーがInvalidDestinationExceptionのスローを許可しません。InvalidSelectorException この例外は、Jakarta Messaging クライアントが無効な構文のメッセージセレクターをプロバイダーに提供しようとしたときにスローされる必要があります。InvalidSelectorRuntimeException このチェックされていない例外は、Jakarta Messaging クライアントが無効な構文を使用してプロバイダーにメッセージセレクターを提供しようとし、メソッドシグネチャーがInvalidSelectorExceptionのスローを許可していない場合にスローする必要があります。JMSException これは、Jakarta Messaging API のすべてのチェック済み例外のルートクラスです。JMSRuntimeException これは、Jakarta Messaging API のすべての未チェックの例外のルートクラスです。JMSSecurityException この例外は、プロバイダーがクライアントから送信されたユーザー名 / パスワードを拒否した場合にスローする必要があります。JMSSecurityRuntimeException このチェックされていない例外は、プロバイダーがクライアントから送信されたユーザー名 / パスワードを拒否した場合、またはセキュリティ制限によりメソッドが完了できず、メソッドシグネチャーがJMSSecurityExceptionのスローを許可していない場合にスローする必要があります。MessageEOFException この例外は、StreamMessageまたはBytesMessageの読み取り中にストリームの予期しない終わりに達した場合にスローする必要があります。MessageFormatException この例外は、Jakarta Messaging クライアントがメッセージでサポートされていないデータ型を使用しようとしたり、メッセージ内のデータを間違った型として読み取ったりした場合にスローする必要があります。MessageFormatRuntimeException このチェックされていない例外は、Jakarta Messaging アプリケーションがメッセージでサポートされていないデータ型を使用しようとしたり、メッセージ内のデータを誤った型として読み取ったりしようとした場合にスローする必要があり、メソッドシグネチャーはMessageFormatExceptionのスローを許可しません。MessageNotReadableException この例外は、Jakarta Messaging クライアントが書き込み専用メッセージを読み取ろうとしたときにスローされる必要があります。MessageNotWriteableException この例外は、Jakarta Messaging クライアントが読み取り専用メッセージに書き込もうとしたときにスローされる必要があります。MessageNotWriteableRuntimeException このチェックされていない例外は、Jakarta Messaging クライアントが読み取り専用メッセージに書き込もうとしたときにスローされる必要があります。ResourceAllocationException この例外は、プロバイダーがメソッドに必要なリソースを割り当てることができない場合にスローされます。ResourceAllocationRuntimeException この未チェックの例外は、プロバイダーがメソッドに必要なリソースを割り当てることができない場合にスローされます。TransactionInProgressException この例外は、トランザクションが進行中であるために操作が無効な場合にスローされます。TransactionInProgressRuntimeException この未チェックの例外は、トランザクションが進行中であるために操作が無効な場合にスローされます。TransactionRolledBackException この例外は、Session.commitの呼び出しにより現在のトランザクションがロールバックされる場合にスローする必要があります。TransactionRolledBackRuntimeException このチェックされていない例外は、JMSContext.commitの呼び出しの結果、現在のトランザクションがロールバックされる場合にスローする必要があります。アノテーション型のサマリー アノテーション型 説明 JMSConnectionFactory このアノテーションをフィールドで使用して、jakarta.jms.JMSContextオブジェクトを挿入するときに使用するjakarta.jms.ConnectionFactoryの JNDI ルックアップ名を指定できます。JMSConnectionFactoryDefinition アプリケーションはこのアノテーションを使用して、運用環境で必要な Jakarta MessagingConnectionFactoryリソースを指定できます。JMSConnectionFactoryDefinitions 1 つ以上のJMSConnectionFactoryDefinitionアノテーションを指定します。JMSDestinationDefinition アプリケーションはこのアノテーションを使用して、運用環境で必要な Jakarta MessagingDestinationリソースを指定できます。JMSDestinationDefinitions 1 つ以上のJMSDestinationDefinitionアノテーションを指定します。JMSPasswordCredential このアノテーションは、jakarta.jms.JMSContextオブジェクトを挿入するときに使用する userName とパスワードを指定するために使用できます。JMSSessionMode このアノテーションは、jakarta.jms.JMSContextオブジェクトを挿入するときに使用されるセッションモードを指定するために使用できます。