検索

AMQ JMS クライアントの使用

download PDF
Red Hat AMQ 2021.Q3

AMQ Clients 2.10 向け

概要

本ガイドでは、クライアントのインストールや設定、実例の実行、他の AMQ コンポーネントでのクライアントの使用方法について説明します。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。これは大規模な取り組みであるため、これらの変更は今後の複数のリリースで段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージをご覧ください。

第1章 概要

AMQ JMS は、AMQP メッセージを送受信するメッセージングアプリケーションで使用する Java Message Service (JMS) 2.0 クライアントです。

AMQ JMS は、複数の言語やプラットフォームをサポートするメッセージングライブラリースイートである AMQ Clients の一部です。クライアントの概要は、「AMQ Clients Overview」を参照してください。本リリースに関する詳細は、『AMQ Clients 2.10 Release Notes』を参照してください。

AMQ JMS は、Apache Qpid からの JMS 実装に基づいています。JMS API の詳細は、「JMS API reference 」および「JMS tutorial」を参照してください。

1.1. 主な特長

  • JMS 1.1 および 2.0 との互換
  • SSL/TLS でのセキュアな通信
  • 柔軟な SASL 認証
  • 自動再接続およびフェイルオーバー
  • OSGi コンテナーと使用する準備ができました。
  • Pure-Java 実装
  • OpenTracing 標準に基づく分散トレーシング

    重要

    AMQ Clients での分散トレーシングはテクノロジープレビュー機能です。テクノロジープレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat では、これらについて実稼働環境での使用を推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストやフィードバックの提供を可能にするために提供されます。Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、https://access.redhat.com/ja/support/offerings/techpreview を参照してください。

注記

AMQ JMS は現在分散トランザクション (XA) をサポートしていません。アプリケーションに分散トランザクションが必要な場合は、AMQ Core Protocol JMS クライアントを使用することが推奨されます。

1.2. サポート対象の標準およびプロトコル

AMQ JMS は、以下の業界標準およびネットワークプロトコルをサポートします。

1.3. サポートされる構成

AMQ JMS でサポートされている設定については、Red Hat カスタマーポータルの「Red Hat AMQ 7 でサポートされる構成」を参照してください。

1.4. 用語および概念

本セクションでは、コア API エンティティーを紹介し、それらが一緒に操作する方法を説明します。

表1.1 API の用語
エンティティー説明

ConnectionFactory

接続を作成するエントリーポイント。

Connection

ネットワーク上の 2 つのピア間の通信用のチャネル。これにはセッションが含まれます。

Session

メッセージを生成および消費するためのコンテキスト。メッセージプロデューサーとコンシューマーが含まれます。

MessageProducer

メッセージを宛先に送信するためのチャネル。ターゲットの宛先があります。

MessageConsumer

宛先からメッセージを受信するためのチャネル。ソースの宛先があります。

Destination

メッセージの名前付きの場所 (キューまたはトピックのいずれか)。

Queue

メッセージの保存されたシーケンス。

Topic

マルチキャスト配布用のメッセージの保存されたシーケンス。

Message

アプリケーション固有の情報部分。

AMQ JMS は メッセージを送受信します。メッセージは、メッセージプロデューサーコンシューマーを使用して、接続されたピア間で転送されます。プロデューサーおよびコンシューマーは セッション 上で確立されます。セッションはコネクション上で確立されます。コネクションは接続ファクトリーによって作成されます。

送信ピアは、メッセージを送信するためにプロデューサーを作成します。プロデューサーには、リモートピアでターゲットキューまたはトピックを識別する 宛先 があります。受信ピアは、メッセージを受信するためにコンシューマーを作成します。プロデューサーと同様に、コンシューマーにはリモートピアでソースキューまたはトピックを識別する宛先があります。

宛先は、キューまたはトピックのいずれかです。JMS では、キューとトピックはメッセージを保持する名前付きブローカーエンティティーのクライアント側表現です。

キューは、ポイントツーポイントセマンティクスを実装します。各メッセージは 1 つのコンシューマーによってのみ認識され、メッセージは読み取り後にキューから削除されます。トピックはパブリッシュ/サブスクライブセマンティクスを実装します。各メッセージは複数のコンシューマーによって認識され、メッセージは読み取り後も他のコンシューマーが利用できます。

詳細は「JMS tutorial」を参照してください。

1.5. 本書の表記慣例

sudo コマンド

本書では、root 権限を必要とするコマンドには sudo が使用されています。何らかの変更がシステム全体に影響する可能性があるため、sudo を使用する場合は注意が必要です。sudo の詳細は、「sudo コマンドの使用」を参照してください。

ファイルパス

本書では、すべてのファイルパスが Linux、UNIX、および同様のオペレーティングシステムで有効です (例: /home/andrea)。Microsoft Windows では、同等の Windows パスを使用する必要があります (例: C:\Users\andrea)。

変数テキスト

本書には、実際の環境に固有の値に置き換える必要がある変数を含むコードブロックが含まれています。変数テキストは中括弧で囲まれ、斜体の等幅フォントとしてスタイル設定されます。たとえば、以下の例では、<project-dir> を実際の環境の値に置き換えます。

$ cd <project-dir>

第2章 インストール

本章では、環境に AMQ JMS をインストールする手順を説明します。

2.1. 前提条件

  • AMQ リリースファイルおよびリポジトリーにアクセスするには、サブスクリプションが必要です。
  • AMQ JMS でプログラムを構築するには、Apache Maven をインストールする必要があります。
  • AMQ JMS を使用するには、Java をインストールする必要があります。

2.2. 「Using the Red Hat Maven repository」

Red Hat Maven リポジトリーからクライアントライブラリーをダウンロードするように Maven 環境を設定します。

手順

  1. Red Hat リポジトリーを Maven 設定または POM ファイルに追加します。設定ファイルの例については、「オンラインリポジトリーの使用」 を参照してください。

    <repository>
      <id>red-hat-ga</id>
      <url>https://maven.repository.redhat.com/ga</url>
    </repository>
  2. ライブラリー依存関係を POM ファイルに追加します。

    <dependency>
      <groupId>org.apache.qpid</groupId>
      <artifactId>qpid-jms-client</artifactId>
      <version>1.0.0.redhat-00001</version>
    </dependency>

これで、クライアントが Maven プロジェクトで利用できるようになりました。

2.3. 「Installing a local Maven repository」

オンラインリポジトリーの代わりに、ファイルベースの Maven リポジトリーとして AMQ JMS をローカルファイルシステムにインストールできます。

手順

  1. サブスクリプションを使用して AMQ Clients 2.10.0 JMS Maven repository .zip ファイルをダウンロードします。
  2. ファイルの内容を、選択したディレクトリーに展開します。

    Linux または UNIX の場合は、unzip コマンドを使用してファイルの内容を展開します。

    $ unzip amq-clients-2.10.0-jms-maven-repository.zip

    Windows の場合は、.zip ファイルを右クリックし、Extract All を選択します。

  3. 展開したインストールディレクトリー内の maven-repository ディレクトリーにあるリポジトリーを使用するように Maven を設定します。詳細は、「ローカルリポジトリーの使用」 を参照してください。

2.4. 「Installing the examples」

手順

  1. git clone コマンドを使用して、ソースリポジトリーを qpid-jms という名前のローカルディレクトリーにクローンします。

    $ git clone https://github.com/apache/qpid-jms.git qpid-jms
  2. qpid-jms ディレクトリーに移動し、git checkout コマンドを使用して 1.0.0 ブランチに切り替えます。

    $ cd qpid-jms
    $ git checkout 1.0.0

作成されるローカルディレクトリーは、本書全体で <source-dir> と呼ばれます。

第3章 スタートガイド

本章では、環境を設定して簡単なメッセージングプログラムを実行する手順を説明します。

3.1. 前提条件

3.2. Hello World の実行

Hello World の例では、ブローカーへの接続を作成し、グリーティングが含まれるメッセージを queue キューに送信し、それを受け取ります。成功すると、受け取ったメッセージをコンソールに出力します。

手順

  1. <source-dir>/qpid-jms-examples ディレクトリーで以下のコマンドを実行し、Maven を使用してサンプルを構築します。

    $ mvn clean package dependency:copy-dependencies -DincludeScope=runtime -DskipTests

    dependency:copy-dependencies を追加すると、依存関係が target/dependency ディレクトリーにコピーされます。

  2. java コマンドを使用してサンプルを実行します。

    Linux または UNIX の場合:

    $ java -cp "target/classes:target/dependency/*" org.apache.qpid.jms.example.HelloWorld

    Windows の場合:

    > java -cp "target\classes;target\dependency\*" org.apache.qpid.jms.example.HelloWorld

たとえば、Linux で実行すると、以下のような出力になります。

$ java -cp "target/classes/:target/dependency/*" org.apache.qpid.jms.example.HelloWorld
Hello world!

この例のソースコードは <source-dir>/qpid-jms-examples/src/main/java ディレクトリーにあります。JNDI およびロギング設定は <source-dir>/qpid-jms-examples/src/main/resources ディレクトリーにあります。

第4章 設定

本章では、AMQ JMS 実装を JMS アプリケーションにバインドし、設定オプションを設定するプロセスについて説明します。

JMS は Java Naming Directory Interface (JNDI) を使用して、API 実装およびその他のリソースを登録し、検索します。これにより、特定の実装によって制限されることなく、JMS API にコードを作成できます。

設定オプションは、接続 URI でクエリーパラメーターとして公開されます。

4.1. JNDI 初期コンテキストの設定

JMS アプリケーションは、InitialContextFactory から取得した JNDI InitialContext オブジェクトを使用して、接続ファクトリーなどの JMS オブジェクトを検索します。AMQ JMS は、org.apache.qpid.jms.jndi.JmsInitialContextFactory クラスで InitialContextFactory の実装を提供します。

InitialContext オブジェクトがインスタンス化されると、InitialContextFactory の実装が検出されます。

javax.naming.Context context = new javax.naming.InitialContext();

実装を見つけるには、お使いの環境で JNDI を設定する必要があります。これを行う方法は、jndi.properties ファイルの使用、システムプロパティーの使用、または初期コンテキスト API の使用の 3 つの方法があります。

jndi.properties ファイルの使用

jndi.properties という名前のファイルを作成し、Java クラスパスに配置します。java.naming.factory.initial キーでプロパティーを追加します。

例: jndi.properties ファイルを使用した JNDI 初期コンテキストファクトリーの設定

java.naming.factory.initial = org.apache.qpid.jms.jndi.JmsInitialContextFactory

Maven ベースのプロジェクトでは、jndi.properties ファイルは <project-dir>/src/main/resources ディレクトリーに配置されます。

システムプロパティーの使用

java.naming.factory.initial システムプロパティーの設定

例: システムプロパティーを使用した JNDI 初期コンテキストファクトリーの設定

$ java -Djava.naming.factory.initial=org.apache.qpid.jms.jndi.JmsInitialContextFactory ...

初期コンテキスト API の使用

JNDI 初期コンテキスト API を使用してプロパティーをプログラム的に設定します。

例: プログラムでの JNDI プロパティーの設定

Hashtable<Object, Object> env = new Hashtable<>();

env.put("java.naming.factory.initial", "org.apache.qpid.jms.jndi.JmsInitialContextFactory");

InitialContext context = new InitialContext(env);

同じ API を使用して、接続ファクトリー、キュー、およびトピックの JNDI プロパティーを設定できることに注意してください。

4.2. 接続ファクトリーの設定

JMS 接続ファクトリーは、接続を作成するためのエントリーポイントです。これは、アプリケーション固有の設定をエンコードする接続 URI を使用します。

ファクトリー名と接続 URI を設定するには、以下の形式でプロパティーを作成します。この設定を jndi.properties ファイルに保存するか、対応するシステムプロパティーを設定できます。

接続ファクトリーの JNDI プロパティー形式

connectionFactory.<lookup-name> = <connection-uri>

たとえば、app1 という名前のファクトリーを以下のように設定します。

例: jndi.properties ファイルでの接続ファクトリーの設定

connectionFactory.app1 = amqp://example.net:5672?jms.clientID=backend

その後、JNDI コンテキストを使用して、app1 という名前を使い、設定済みの接続ファクトリーを検索できます。

ConnectionFactory factory = (ConnectionFactory) context.lookup("app1");

4.3. 接続 URI

コネクションは接続 URI を使用して設定されます。接続 URI は、クエリーパラメーターとして設定されるリモートホスト、ポート、および設定オプションのセットを指定します。利用可能なオプションについての詳細は、5章SSL 設定オプション を参照してください。

接続 URI 形式

<scheme>://<host>:<port>[?<option>=<value>[&<option>=<value>...]]

暗号化されていない接続のスキームは amqp で、SSL/TLS 接続の場合は amqps です。

たとえば、以下はポート 5672 でホスト example.net に接続する接続 URI で、クライアント ID を backend に設定します。

例: 接続 URI

amqp://example.net:5672?jms.clientID=backend

フェイルオーバー URI

フェイルオーバーが設定されると、現在のサーバーへの接続が失われた場合、クライアントは別のサーバーに自動的に再接続できます。フェイルオーバー URI には接頭辞 failover: があり、括弧内には接続 URI のコンマ区切りリストが含まれます。追加のオプションは最後に指定されます。

フェイルオーバーの URI 形式

failover:(<connection-uri>[,<connection-uri>...])[?<option>=<value>[&<option>=<value>...]]

たとえば、以下は、2 つのホスト (host1 または host2) のいずれかに接続できるフェイルオーバー URI です。

例: フェイルオーバー URI

failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=backend

接続 URI の例と同様に、クライアントはフェイルオーバー設定で URI を使用して多数の異なる設定で設定できます。これらの設定は、5章SSL 設定オプション で詳しく説明しています。「フェイルオーバーオプション」 セクションも参照してください。

SSL/TLS サーバー名の表示

amqps スキームを使用して SSL/TLS 接続を指定する場合、URI からのホストセグメントは JVM の TLS Server Name Indication (SNI) 拡張によって使用でき、TLS ハンドシェイク時に必要なサーバーのホスト名を通信できます。SNI 拡張は、完全修飾ドメイン名 (例: "myhost.mydomain") が指定されている場合に自動的に含まれますが、修飾されていない名前 (「myhost」など) やベア IP アドレスが使用される場合は定義されません。

4.4. キューおよびトピック名の設定

JMS は、JNDI を使用してデプロイメント固有のキューとトピックリソースを検索するオプションを提供します。

JNDI でキューおよびトピック名を設定するには、以下の形式でプロパティーを作成します。この設定を jndi.properties ファイルに置くか、対応するシステムプロパティーを設定します。

キューおよびトピックの JNDI プロパティー形式

queue.<lookup-name> = <queue-name>
topic.<lookup-name> = <topic-name>

たとえば、以下のプロパティーは、2 つのデプロイメント固有のリソースに jobs および notifications という名前を定義します。

例: jndi.properties ファイルでのキューおよびトピック名の設定

queue.jobs = app1/work-items
topic.notifications = app1/updates

その後、JNDI 名でリソースを検索できます。

Queue queue = (Queue) context.lookup("jobs");
Topic topic = (Topic) context.lookup("notifications");

4.5. JNDI プロパティーの変数拡張

JNDI プロパティー値には、${<variable-name>} 形式の変数を含めることができます。ライブラリーは、以下の場所の順序を検索して、変数値を解決します。

  • Java システムプロパティー
  • OS 環境変数
  • JNDI プロパティーファイルまたは環境ハッシュテーブル

たとえば、Linux ${HOME} では、現在のユーザーのホームディレクトリーである HOME 環境変数に解決されます。

構文 ${<variable-name>:-<default-value>} を使用してデフォルト値を指定できます。<variable-name> の値が見つからない場合は、代わりにデフォルト値が使用されます。

第5章 SSL 設定オプション

本章では、AMQ JMS で利用可能な設定オプションについて説明します。

JMS 設定オプションは、接続 URI でクエリーパラメーターとして設定されます。詳細は、「接続 URI」 を参照してください。

5.1. JMS オプション

これらのオプションは、ConnectionSessionMessageConsumerMessageProducer などの JMS オブジェクトの動作を制御します。

jms.username
クライアントが接続を認証するために使用するユーザー名。
jms.password
クライアントが接続を認証するために使用するパスワード。
jms.clientID
クライアントが接続に適用するクライアント ID。
jms.forceAsyncSend
有効にすると、MessageProducer からのすべてのメッセージが非同期に送信されます。それ以外の場合、非永続メッセージやトランザクション内のメッセージなど、特定の種類のみが非同期で送信されます。これはデフォルトで無効にされます。
jms.forceSyncSend
有効にすると、MessageProducer からのすべてのメッセージが同期的に送信されます。これはデフォルトで無効にされます。
jms.forceAsyncAcks
有効にすると、すべてのメッセージ承認は非同期で送信されます。これはデフォルトで無効にされます。
jms.localMessageExpiry
有効にすると、MessageConsumer によって受信される期限切れのメッセージはすべてフィルタリングされ、配信されません。これはデフォルトで有効になっています。
jms.localMessagePriority
有効にすると、事前にフェッチされたメッセージはメッセージの優先度の値に基づいてローカルに並べ替えられます。これはデフォルトで無効にされます。
jms.validatePropertyNames
有効にすると、メッセージプロパティー名が有効な Java 識別子である必要があります。これはデフォルトで有効になっています。
jms.receiveLocalOnly
これを有効にすると、timeout 引数を指定した receive の呼び出しは、コンシューマーのローカルメッセージバッファーのみを確認します。タイムアウトが期限切れになると、リモートピアをチェックして、メッセージがないことを確認します。これはデフォルトで無効にされます。
jms.receiveNoWaitLocalOnly
有効にすると、receiveNoWait に対する呼び出しは、コンシューマーのローカルメッセージバッファーのみを確認します。それ以外の場合は、リモートピアをチェックし、利用可能なメッセージがないことを確認することができます。これはデフォルトで無効にされます。
jms.queuePrefix
Session から作成される Queue の名前に追加される任意のプレフィックス値。
jms.topicPrefix
Session から作成される Topic の名前に追加される任意のプレフィックス値。
jms.closeTimeout
返される前にクライアントが通常のリソースクリップを待つ時間 (ミリ秒単位)。デフォルトは 60000 (60 秒) です。
jms.connectTimeout
エラーを返す前にクライアントが接続確立を待つ時間 (ミリ秒単位)。デフォルトは 15000 (15 秒) です。
jms.sendTimeout
エラーを返す前に、クライアントが 同期メッセージを送信 するのを待機する期間 (ミリ秒単位)。デフォルトでは、クライアントは送信が完了するまで無期限に待機します。
jms.requestTimeout
クライアントがエラーを返す前に、リモートピアでプロデューサまたはコンシューマー (送信を除く) を開くなど、さまざまな同期インタラクションが完了するまで待機する時間 (ミリ秒単位)。デフォルトでは、クライアントはリクエストが完了するまで無期限に待機します。
jms.clientIDPrefix
ConnectionFactory で新しい Connection を作成する際に、クライアント ID 値を生成するために使用されるオプションの接頭辞値。デフォルトは ID: です。
jms.connectionIDPrefix
ConnectionFactory で新しい Connection を作成する際に、クライアント ID 値を生成するために使用されるオプションの接頭辞値。この接続 ID は、Connection オブジェクトから一部の情報をログに記録する際に使用されるため、設定可能な接頭辞を使用するとログのブレッドをより容易にすることができます。デフォルトは ID: です。
jms.populateJMSXUserID
有効な場合は、接続から認証済みユーザー名を使用して、送信された各メッセージの JMSXUserID プロパティーを設定します。これはデフォルトで無効にされます。
jms.awaitClientID
有効にすると、URI で設定されたクライアント ID のない接続は、クライアント ID がプログラムを設定するまで待機するか、または AMQP コネクション「open」を送信する前に何も設定できない確認を行います。これはデフォルトで有効になっています。
jms.useDaemonThread
有効にすると、コネクションはデーモン以外のスレッドではなく、エグゼキューターにデーモンスレッドを使用します。これはデフォルトで無効にされます。
jms.tracing
トレースプロバイダーの名前。サポートされる値は opentracing および noop です。デフォルトは noop です。
prefetch ポリシーオプション

prefetch ポリシーは、各 MessageConsumer がリモートピアから取得し、ローカルの「prefetch」バッファーに保持されるメッセージ数を決定します。

jms.prefetchPolicy.queuePrefetch
デフォルトは 1000 です。
jms.prefetchPolicy.topicPrefetch
デフォルトは 1000 です。
jms.prefetchPolicy.queueBrowserPrefetch
デフォルトは 1000 です。
jms.prefetchPolicy.durableTopicPrefetch
デフォルトは 1000 です。
jms.prefetchPolicy.all
これは、すべての事前にフェッチされた値を 1 度に設定するために使用できます。

prefetch の値は、キューまたは共有サブスクリプションの複数のコンシューマーへのメッセージの分散に影響します。値が大きいと、各コンシューマーに一度に送信されるバッチが大きくなる可能性があります。より均等にラウンドロビンの分散を実現するには、小さい値を使用します。

再配信ポリシーオプション

再配信ポリシーは、クライアント上で再配信されたメッセージの処理方法を制御します。

jms.redeliveryPolicy.maxRedeliveries
受信メッセージが再配信された回数に基づいて拒否されるタイミングを制御します。値が 0 の場合は、メッセージの再配信が許可されないことを示します。値が 5 の場合、メッセージを 5 回など再送することができます。デフォルトは -1 で、無制限を意味します。
jms.redeliveryPolicy.outcome
設定された maxRedeliveries 値を超過すると、メッセージに適用される結果を制御します。サポートされる値は ACCEPTEDREJECTEDRELEASEDMODIFIED_FAILED、および MODIFIED_FAILED_UNDELIVERABLE です。デフォルト値は MODIFIED_FAILED_UNDELIVERABLE です。
メッセージ ID ポリシーオプション

メッセージ ID ポリシーは、クライアントから送信されたメッセージに割り当てられたメッセージ ID のデータタイプを制御します。

jms.messageIDPolicy.messageIDType
デフォルトでは、生成された String 値は送信メッセージのメッセージ ID に使用されます。その他の利用可能なタイプは、UUIDUUID_STRING、および PREFIXED_UUID_STRING です。
Presettle ポリシーオプション

Presettle ポリシーは、AMQP の事前設定されたメッセージングセマンティクスを使用するように設定されているプロデューサーまたはコンシューマーインスタンスが設定されたタイミングを制御します。

jms.presettlePolicy.presettleAll
有効な場合は、作成されたプロデューサーおよび非トランザクションコンシューマーはすべて、事前設定モードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleProducers
有効な場合は、すべてのプロデューサーが事前設定されたモードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleTopicProducers
有効にすると、Topic または TemporaryTopic 宛先に送信されたすべてのプロデューサーは、事前に設定されたモードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleQueueProducers
有効にすると、Queue または TemporaryQueue 宛先に送信されたすべてのプロデューサーは、事前に設定されたモードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleTransactedProducers
有効な場合、トランザクション Session で作成されたプロデューサーは事前設定モードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleConsumers
有効にすると、すべてのコンシューマーは事前に設定されたモードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleTopicConsumers
有効にすると、Topic または TemporaryTopic 宛先から受信されたコンシューマーはすべて、事前セットモードで動作します。これはデフォルトで無効にされます。
jms.presettlePolicy.presettleQueueConsumers
有効にすると、Queue または TemporaryQueue 宛先から受信されたコンシューマーはすべて、事前セットモードで動作します。これはデフォルトで無効にされます。
デシリアライズポリシーオプション

デシリアライズポリシーは、シリアル化された Java Object コンテンツで構成される受信 ObjectMessage からボディーを取得しつつ、どの Java タイプがオブジェクトストリームからデシリアライズされるかを制御する手段を提供します。デフォルトでは、本文のデシリアライズの試行時にすべてのタイプが信頼されます。デフォルトのデシリアライズポリシーは、ホワイトリストと Java クラスまたはパッケージ名のブラックリストを指定できるようにする URI オプションを提供します。

jms.deserializationPolicy.whiteList
blackList によって上書きされない限り、ObjectMessage の内容をデシリアライズする際に許可されるクラス名のコンマ区切りリスト。このリストの名前は、パターンの値ではありません。java.util.Map または java.util のように、正確なクラスまたはパッケージ名を設定する必要があります。パッケージの一致には、サブパッケージが含まれます。デフォルトではすべてを許可します。
jms.deserializationPolicy.blackList
ObjectMessage の内容をデシリアライズする際に拒否されるクラス名とパッケージ名のコンマ区切りリスト。このリストの名前は、パターンの値ではありません。java.util.Map または java.util のように、正確なクラスまたはパッケージ名を設定する必要があります。パッケージの一致には、サブパッケージが含まれます。デフォルトでは、none が回避されます。

5.2. TCP オプション

プレーン TCP を使用してリモートサーバーに接続する場合、以下のオプションは基礎となるソケットの動作を指定します。これらのオプションは、他の設定オプションと共に接続 URI に追加されます。

例: トランスポートオプションを持つ接続 URI

amqp://localhost:5672?jms.clientID=foo&transport.connectTimeout=30000

TCP トランスポートオプションの完全なセットを以下に示します。

transport.sendBufferSize
送信バッファーサイズ (バイト単位)。デフォルトは 65536 (64 KiB) です。
transport.receiveBufferSize
受信バッファーサイズ (バイト単位)。デフォルトは 65536 (64 KiB) です。
transport.trafficClass
デフォルトは 0 です。
transport.connectTimeout
デフォルトは 60 秒です。
transport.soTimeout
デフォルトは -1 です。
transport.soLinger
デフォルトは -1 です。
transport.tcpKeepAlive
デフォルトは false です。
transport.tcpNoDelay
有効な場合、TCP 送信の遅延やバッファーを行いません。これはデフォルトで有効になっています。
transport.useEpoll
利用できる場合は、NIO レイヤーではなくネイティブの epoll IO レイヤーを使用します。これにより、パフォーマンスが向上します。これはデフォルトで有効になっています。

5.3. SSL/TLS オプション

SSL/TLS トランスポートは、amqps URI スキームを使用して有効にします。SSL/TLS トランスポートは TCP ベースのトランスポートの機能を拡張するため、すべての TCP トランスポートオプションは SSL/TLS トランスポート URI で有効です。

例: 簡単な SSL/TLS 接続 URI

amqps://myhost.mydomain:5671

以下は、SSL/TLS トランスポートオプションの完全なセットです。

transport.keyStoreLocation
SSL/TLS キーストアへのパス。設定しない場合、javax.net.ssl.keyStore システムプロパティーの値が使用されます。
transport.keyStorePassword
SSL/TLS キーストアのパスワード。設定しない場合、javax.net.ssl.keyStorePassword システムプロパティーの値が使用されます。
transport.trustStoreLocation
SSL/TLS トラストストアへのパス。設定しない場合、javax.net.ssl.trustStore システムプロパティーの値が使用されます。
transport.trustStorePassword
SSL/TLS トラストストアのパスワード。設定しない場合、javax.net.ssl.trustStorePassword システムプロパティーの値が使用されます。
transport.keyStoreType
設定しない場合、javax.net.ssl.keyStoreType システムプロパティーの値が使用されます。システムプロパティーが設定されていない場合は、デフォルトは JKS です。
transport.trustStoreType
設定しない場合、javax.net.ssl.trustStoreType システムプロパティーの値が使用されます。システムプロパティーが設定されていない場合は、デフォルトは JKS です。
transport.storeType
keyStoreTypetrustStoreType の両方を同じ値に設定します。未設定の場合は、keyStoreType および trustStoreType が上記の値にデフォルト設定されます。
transport.contextProtocol
SSLContext の取得時に使用されるプロトコル引数。デフォルトは TLS です。OpenSSL を使用している場合は TLSv1.2 です。
transport.enabledCipherSuites
有効にする暗号スイートのコンマ区切りリスト。未設定の場合は、context-default 暗号が使用されます。無効にした暗号は、この一覧から削除されます。
transport.disabledCipherSuites
無効にする暗号スイートのカンマ区切りリスト。ここに挙げられている暗号は、有効な暗号化から削除されます。
transport.enabledProtocols
有効にするプロトコルのコンマ区切りリスト。設定しないと、context-default プロトコルが使用されます。無効にされたプロトコルはすべてこの一覧から削除されます。
transport.disabledProtocols
無効にするプロトコルのコンマ区切りリスト。ここに挙げられているプロトコルは、有効なプロトコルリストから削除されます。デフォルトは SSLv2Hello,SSLv3 です。
transport.trustAll
有効な場合、設定されたトラストストアに関係なく、提供されたサーバー証明書を暗黙的に信頼します。これはデフォルトで無効にされます。
transport.verifyHost
有効な場合は、接続ホスト名が、提供されたサーバー証明書と一致することを確認します。これはデフォルトで有効になっています。
transport.keyAlias
クライアント証明書をサーバーに送信する必要がある場合には、キーストアからキーペアを選択する際に使用するエイリアス。
transport.useOpenSSL

有効にすると、利用可能な場合は SSL/TLS 接続にネイティブ OpenSSL ライブラリーを使用します。これはデフォルトで無効にされます。

詳細は、「OpenSSL サポートの有効化」 を参照してください。

5.4. AMQP オプション

以下のオプションは、AMQP ワイヤプロトコルに関連する動作の要素に適用されます。

amqp.idleTimeout
ピアが AMQP フレームを送信しない場合の接続に失敗する時間 (ミリ秒単位)。デフォルトの期間は 60000 (1 分) です。
amqp.vhost
接続する仮想ホスト。これは、SASL および AMQP ホスト名フィールドを設定するために使用されます。デフォルトは、接続 URI からのメインホスト名です。
amqp.saslLayer
有効にされている場合、SASL は接続を確立するときに使用されます。これはデフォルトで有効になっています。
amqp.saslMechanisms
サーバーによって提供される場合に、クライアントが選択でき、設定された認証情報で使用可能である場合に、クライアントが選択できる SASL メカニズムのカンマ区切りリスト。サポートされるメカニズムは EXTERNAL、SCRAM-SHA-256、SCRAM-SHA-1、CRAM-MD5、PLAIN、ANONYMOUS、および GSSAPI for Kerberos です。デフォルトでは、ここで明示的に有効にするために明示的に組み込む必要のある GSSAPI 以外のすべてのメカニズムの選択を許可します。
amqp.maxFrameSize
クライアントによって許可される最大 AMQP フレームサイズ (バイト単位)。この値は、リモートピアに公開されています。デフォルトは 1048576 (1 MiB) です。
amqp.drainTimeout
コンシューマーのドレイン要求が作成されると、クライアントがリモートピアからの応答を待つ時間 (ミリ秒単位)。割り当てられたタイムアウトの期間に応答が表示されない場合は、リンクが失敗したとみなされ、関連付けられたコンシューマーが閉じられます。デフォルトの期間は 60000 (1 分) です。
amqp.allowNonSecureRedirects
有効にすると、既存の接続が安全で、別の接続が利用できない場合に AMQP の代替ホストへのリダイレクトを許可します。たとえば、これを有効にすると、SSL/TLS 接続の raw TCP 接続へのリダイレクトが許可されます。これはデフォルトで無効にされます。

5.5. フェイルオーバーオプション

フェイルオーバー URI は接頭辞 failover: で始まり、括弧内に接続 URI のコンマ区切りリストが含まれます。追加のオプションは最後に指定されます。jms. で始まるオプションは、括弧外にある全体的なフェイルオーバー URI に適用され、その有効期間の Connection オブジェクトに影響します。

例: フェイルオーバーオプションを含むフェイルオーバー URI

failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.maxReconnectAttempts=20

括弧内の個別のブローカー詳細は、以前に定義した transport. または amqp. オプションを使用できます。各ホストが接続されていると、これらが適用されます。

例: 各接続トランスポートと AMQP オプションを持つフェイルオーバー URI

failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?jms.clientID=foo

フェイルオーバーのすべての設定オプションは以下のとおりです。

failover.initialReconnectDelay
クライアントが最初にリモートピアへの再接続を試みるまで待機する時間 (ミリ秒単位)。デフォルトは 0 で、最初の試行がすぐに実行されます。
failover.reconnectDelay
再接続試行の間隔 (ミリ秒単位)。backoff オプションが有効になっていない場合、この値は定数のままになります。デフォルトは 10 です。
failover.maxReconnectDelay
クライアントが再接続を試行するまで待機する時間。この値は、遅延が大きくなりすぎないようにバックオフ機能が有効な場合にのみ使用されます。デフォルトは 30 秒です。
failover.useReconnectBackOff
有効にすると、設定された乗数に基づいて再接続試行の間隔が長くなります。これはデフォルトで有効になっています。
failover.reconnectBackOffMultiplier
再接続遅延値を拡張するために使用される乗数。デフォルトは 2.0 です。
failover.maxReconnectAttempts
接続をクライアントに失敗したと報告する前に許可される再接続試行の数。デフォルトは -1 で、無制限を意味します。
failover.startupMaxReconnectAttempts
事前にリモートピアに接続されていないクライアントの場合、このオプションは、接続を失敗と報告する前に接続する試行回数を制御します。設定しなければ、maxReconnectAttempts の値が使用されます。
failover.warnAfterReconnectAttempts
警告がログに記録されるまでの再接続試行の失敗回数。デフォルトは 10 です。
failover.randomize
有効な場合、いずれかの接続を試行する前にフェイルオーバー URI のセットが無作為にシャッフルされます。これにより、クライアント接続を複数のリモートピアに均等に分散させることができます。これはデフォルトで無効にされます。
failover.amqpOpenServerListAction
サーバーからの接続 "open" フレームがクライアントへのフェイルオーバーホストのリストを提供すると、フェイルオーバートランスポートがどのように動作するかを制御します。有効な値は、REPLACEADD、または IGNORE です。REPLACE を設定すると、現在のサーバーにあるサーバー以外のフェイルオーバー URI は、サーバーによって提供されるものに置き換えられます。ADD を設定すると、サーバーによって提供される URI が重複排除を使用して、既存のフェイルオーバー URI セットに追加されます。IGNORE を設定すると、サーバーからの更新は無視され、使用中のフェイルオーバー URI のセットに変更は行われません。デフォルトは REPLACE です。

フェイルオーバー URI は、AMQP およびトランスポートオプションをすべてネスト化されたブローカー URI に指定する手段として、入れ子オプションの定義もサポートします。これは、非フェイルオーバーブローカー URI が前述されているのと同じ transport. および amqp. の URI オプションを使用して実行されますが、failover.nested. のプレフィックスが付けられます。たとえば、接続されたすべてのブローカーに amqp.vhost オプションに同じ値を適用するには、以下のような URI が含まれる場合があります。

例: 共有トランスポートと AMQP オプションを持つフェイルオーバー URI

failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.nested.amqp.vhost=myhost

5.6. 検出オプション

クライアントにはオプションの検出モジュールがあります。これは、接続するブローカー URI が初期 URI で指定されず、検出エージェントと対話して検出されるカスタムフェールオーバーを提供します。現在、ディスカバリーエージェントの実装には、ファイルから URI をロードするファイル監視と、クライアントをリッスンするブローカーアドレスをブロードキャストするよう設定された ActiveMQ 5.x ブローカーと動作するマルチキャストリスナーとされています。

検出を使用する際のフェイルオーバー関連のオプションの一般的なセットは前述のものと同じで、主な接頭辞は failover. から discovery. に変更され、検出されたすべてのブローカー URI に共通する URI オプションを指定するために nested 接頭辞が使用されます。たとえば、エージェントの URI の詳細がないと、一般的な検出 URI は以下のようになります。

例: 検出 URI

discovery:(<agent-uri>)?discovery.maxReconnectAttempts=20&discovery.discovered.jms.clientID=foo

ファイルウォッチャー検出エージェントを使用するには、以下のようなエージェント URI を作成します。

例: ファイルウォッチャーエージェントを使用した検出 URI

discovery:(file:///path/to/monitored-file?updateInterval=60000)

ファイルウォッチャーの検出エージェントの URI オプションを以下に示します。

updateInterval
ファイル変更を確認する間隔 (ミリ秒単位)。デフォルトは 30000 (30 秒) です。

ActiveMQ 5.x ブローカーでマルチキャストディスカバリーエージェントを使用するには、以下のようなエージェント URI を作成します。

例: マルチキャストリスナーエージェントを使用した検出 URI

discovery:(multicast://default?group=default)

上記のマルチキャストエージェント URI のホストに default を使用することは、エージェントがデフォルトの 239.255.2.3:6155 に置き換える特別な値であることに注意してください。これを変更して、マルチキャスト設定で使用している実際の IP アドレスとポートを指定できます。

マルチキャスト検出エージェントの URI オプションを以下に示します。

group
更新をリッスンするために使用されるマルチキャストグループ。デフォルトは default です。

第6章 例

本章では、サンプルプログラムで AMQ JMS を使用する方法について説明します。

詳細は、「AMQ JMS のサンプルスイート」および「Qpid JMS の例」を参照してください。

6.1. JNDI コンテキストの設定

通常、JMS を使用するアプリケーションは JNDI を使用してアプリケーションが使用する ConnectionFactory および Destination オブジェクトを取得します。これにより、設定がプログラムから分離され、特定のクライアント実装から分離されます。

これらの例を使用する場合は、以前に詳細に説明したように JNDI コンテキストを設定するために、jndi.properties という名前のファイルをクラスパスに配置する必要があります。

jndi.properties ファイルの内容は、以下に示す内容と一致している必要があります。これにより、クライアントの InitialContextFactory 実装を使用し、ローカルサーバーに接続するための ConnectionFactory を設定し、queue という名前の宛先キューを定義します。

# Configure the InitialContextFactory class to use
java.naming.factory.initial = org.apache.qpid.jms.jndi.JmsInitialContextFactory

# Configure the ConnectionFactory
connectionfactory.myFactoryLookup = amqp://localhost:5672

# Configure the destination
queue.myDestinationLookup = queue

6.2. メッセージの送信

この例では、まず JNDI Context を作成します。これを使用して、ConnectionFactory および Destination を検索するために使用されます。ファクトリーを使用して Connection を作成してから、Session を作成します。次に、MessageProducerDestination に作成され、メッセージを使用して送信されます。その後、Connection が閉じられ、プログラムは終了します。

この Sender 例の実行可能なバリアントは、以前に3章スタートガイドで説明した例の Hello World とともに、<source-dir>/qpid-jms-examples ディレクトリーにあります。

例: メッセージの送信

package org.jboss.amq.example;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.DeliveryMode;
import javax.jms.Destination;
import javax.jms.ExceptionListener;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageProducer;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;

public class Sender {
  public static void main(String[] args) throws Exception {
    try {
      Context context = new InitialContext(); 1

      ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup");
      Destination destination = (Destination) context.lookup("myDestinationLookup"); 2

      Connection connection = factory.createConnection("<username>", "<password>");
      connection.setExceptionListener(new MyExceptionListener());
      connection.start(); 3

      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); 4

      MessageProducer messageProducer = session.createProducer(destination); 5

      TextMessage message = session.createTextMessage("Message Text!"); 6
      messageProducer.send(message, DeliveryMode.NON_PERSISTENT,
                           Message.DEFAULT_PRIORITY, Message.DEFAULT_TIME_TO_LIVE); 7

      connection.close(); 8
    } catch (Exception exp) {
      System.out.println("Caught exception, exiting.");
      exp.printStackTrace(System.out);
      System.exit(1);
    }
  }

  private static class MyExceptionListener implements ExceptionListener {
    @Override
    public void onException(JMSException exception) {
      System.out.println("Connection ExceptionListener fired, exiting.");
      exception.printStackTrace(System.out);
      System.exit(1);
    }
  }
}

1
JNDI Context を作成して、ConnectionFactory および Destination オブジェクトを検索します。設定は、前述した jndi.properties ファイルから選択されます。
2
ConnectionFactory および Destination オブジェクトは、ルックアップ名を使用して JNDI コンテキストから取得されます。
3
ファクトリーは Connection の作成に使用され、続いて ExceptionListener が登録され、開始します。接続の作成時に指定される認証情報は、通常は適切な外部設定ソースから取得され、アプリケーション自体とは別のままとなり、個別に更新することができます。
4
トランザクション以外の自動承認 SessionConnection に作成されます。
5
MessageProducer は、メッセージを Destination に送信するために作成されます。
6
指定の内容で TextMessage が作成されます。
7
TextMessage が送信されます。非永続的な送信は、デフォルトの優先度で、有効期限はありません。
8
Connection は終了します。Session および MessageProducer は暗黙的に閉じられます。

これは単なる例であることに注意してください。実際のアプリケーションは、通常、有効期間の長い MessageProducer を使用し、時間の経過を使用して多数のメッセージを送信します。通常、メッセージごとに ConnectionSession、および MessageProducer を開くことは効率的ではありません。

6.3. メッセージの受信

この例では、JNDI コンテキストを作成し、そのコンテキストを使用して ConnectionFactory および Destination を検索し、ファクトリーを使用して Connection を起動してから Session を作成します。次に、Destination に対して MessageConsumer が作成され、それを使用してメッセージを受信し、その内容をコンソールに出力します。その後、接続が閉じられ、プログラムを終了します。送信例 と同じ JNDI 設定が使用されます。

この Receiver 例の実行可能なバリアントは、以前 3章スタートガイド で説明した Hello World 例とともに、クライアントディストリビューションの例ディレクトリー内に含まれています。

例: メッセージの受信

package org.jboss.amq.example;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.Destination;
import javax.jms.ExceptionListener;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageConsumer;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;

public class Receiver {
  public static void main(String[] args) throws Exception {
    try {
      Context context = new InitialContext(); 1

      ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup");
      Destination destination = (Destination) context.lookup("myDestinationLookup"); 2

      Connection connection = factory.createConnection("<username>", "<password>");
      connection.setExceptionListener(new MyExceptionListener());
      connection.start(); 3

      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); 4

      MessageConsumer messageConsumer = session.createConsumer(destination); 5

      Message message = messageConsumer.receive(5000); 6

      if (message == null) { 7
        System.out.println("A message was not received within given time.");
      } else {
        System.out.println("Received message: " + ((TextMessage) message).getText());
      }

      connection.close(); 8
    } catch (Exception exp) {
      System.out.println("Caught exception, exiting.");
      exp.printStackTrace(System.out);
      System.exit(1);
    }
 }

  private static class MyExceptionListener implements ExceptionListener {
    @Override
    public void onException(JMSException exception) {
      System.out.println("Connection ExceptionListener fired, exiting.");
      exception.printStackTrace(System.out);
      System.exit(1);
    }
  }
}

1
JNDI Context を作成して、ConnectionFactory および Destination オブジェクトを検索します。設定は、前述した jndi.properties ファイルから選択されます。
2
ConnectionFactory および Destination オブジェクトは、ルックアップ名を使用して JNDI Context から取得されます。
3
ファクトリーは Connection の作成に使用され、続いて ExceptionListener が登録され、開始します。接続の作成時に指定される認証情報は、通常は適切な外部設定ソースから取得され、アプリケーション自体とは別のままとなり、個別に更新することができます。
4
トランザクション以外の自動承認 SessionConnection に作成されます。
5
MessageConsumer は、Destination からメッセージを受信するために作成されます。
6
メッセージを受信する呼び出しは、5 秒のタイムアウトで行われます。
7
結果は確認され、メッセージを受信した場合、その内容は出力され、メッセージが受信されなかったことが通知されます。Sender が送信されている内容であるため、結果は TextMessage に明示的にキャストされます。
8
Connection は終了します。Session および MessageConsumer は暗黙的に閉じられます。

これは単なる例であることに注意してください。実際のアプリケーションは、通常有効期限の長い MessageConsumer を使用し、時間の経過とともに多数のメッセージを受信します。通常、各メッセージに対して ConnectionSession、および MessageConsumer を開くことは効率的ではありません。

第7章 セキュリティー

AMQ JMS には、アプリケーションのニーズに合わせて活用できるセキュリティー関連の設定オプションが複数あります。

アプリケーション内に Connection を作成する際に、ユーザー名とパスワードなどの基本的なユーザーの認証情報を ConnectionFactory に直接渡す必要があります。ただし、no-argument ファクトリーメソッドを使用している場合は、接続 URI でユーザーの認証情報を指定することもできます。詳細は、「JMS オプション」 セクションを参照してください。

もう 1 つの一般的なセキュリティー対策として、SSL/TLS が使用されます。クライアントは、amqps URI スキームが接続 URI に指定され、動作を設定するさまざまなオプションとともに、SSL/TLS トランスポートを介してサーバーに接続します。詳細は、「SSL/TLS オプション」 セクションを参照してください。

以前の項目と詳しく説明すると、クライアントが、対応するすべてのものから選択するのではなく、サーバーで提供できる特定の SASL メカニズムのみを使用できるようにクライアントを制限することが望ましい場合があります。詳細は、「AMQP オプション」 セクションを参照してください。

受信した ObjectMessagegetObject() を呼び出すアプリケーションは、デシリアライズ中に作成された型を制限することができます。AMQP タイプシステムを使用して構成されたメッセージ本文は ObjectInputStream メカニズムを使用しないため、この予防措置は必要ありません。詳細は、「デシリアライズポリシーオプション」 セクションを参照してください。

7.1. OpenSSL サポートの有効化

SSL/TLS 接続は、パフォーマンスを改善するためにネイティブの OpenSSL 実装を使用するように設定できます。OpenSSL を使用するには、transport.useOpenSSL オプションが有効にされ、OpenSSL サポートライブラリーがクラスパスで利用可能でなければなりません。

Red Hat Enterprise Linux でインストールされた OpenSSL ライブラリーを使用するには、openssl および apr RPM パッケージをインストールし、以下の依存関係を POM ファイルに追加します。

例: ネイティブ OpenSSL サポートの追加

<dependency>
  <groupId>io.netty</groupId>
  <artifactId>netty-tcnative</artifactId>
  <version>2.0.39.Final-redhat-00001</version>
  <classifier>linux-x86_64-fedora</classifier>
</dependency>

OpenSSL ライブラリーの実装のリストは、Netty プロジェクトから入手できます。

7.2. Kerberos を使用した認証

クライアントは、適切に設定されたサーバーで使用される場合に Kerberos を使用して認証するように設定できます。Kerberos を有効にするには、以下の手順に従います。

  1. amqp.saslMechanisms URI オプションを使用して、SASL 認証に GSSAPI メカニズムを使用するようにクライアントを設定します。

    amqp://myhost:5672?amqp.saslMechanisms=GSSAPI
    failover:(amqp://myhost:5672?amqp.saslMechanisms=GSSAPI)
  2. java.security.auth.login.config システムプロパティーを、Kerberos LoginModule の適切な設定が含まれる JAAS ログイン設定ファイルのパスに設定します。

    -Djava.security.auth.login.config=<login-config-file>

    ログイン設定ファイルは以下の例のようになります。

    amqp-jms-client {
        com.sun.security.auth.module.Krb5LoginModule required
        useTicketCache=true;
    };

使用される正確な設定は、接続のためにクレデンシャルを確立する方法と、使用中の特定の LoginModule によって異なります。Oracle Krb5LoginModule の詳細は、「Oracle Krb5LoginModule class reference」を参照してください。IBM Java 8 Krb5LoginModule の詳細は、IBM Krb5LoginModule class reference を参照してください。

プリンシパルの指定や既存のチケットキャッシュまたはキータブを使用するかどうかなど、Kerberos プロセスに使用する認証情報を確立するように LoginModule を設定できます。ただし、LoginModule 設定が、必要なすべての認証情報を確立する手段を提供しない場合は、これを要求して、クライアント Connection オブジェクトからユーザー名とパスワードの値が渡されます。これは、ConnectionFactory を使用するか、URI オプションから以前に設定した Connection を作成するときに、これらの値が提供される場合です。

Kerberos は認証の目的でのみサポートされることに注意してください。暗号化には SSL/TLS 接続を使用します。

以下の接続 URI オプションを使用して Kerberos 認証プロセスに影響を与えることができます。

sasl.options.configScope
認証に使用するログイン設定エントリーの名前。デフォルトは amqp-jms-client です。
sasl.options.protocol
GSSAPI SASL プロセス中に使用されるプロトコル値。デフォルトは amqp です。
sasl.options.serverName
GSSAPI SASL プロセス中に使用される serverName 値。デフォルトは、接続 URI からのサーバーのホスト名です。

これまでで説明する amqp. および transport. オプションと同様に、これらのオプションはホストごとに、またはフェイルオーバー URI のすべてのホストネストされたオプションに指定する必要があります。

第8章 メッセージ配信

8.1. 承認されていない配信の処理

メッセージングシステムは、メッセージ確認を使用して、メッセージの送信ゴールが頻繁に行われるかどうかを追跡します。

メッセージが送信されると、メッセージが送信されてから、確認応答するまでの期間が発生します (メッセージは「in flight (進行中)」です)。その間ネットワーク接続が失われた場合、メッセージ配信のステータスは不明となり、配信が完了するまで、アプリケーションコードで特別な処理が必要になる場合があります。

以下のセクションでは、接続に失敗した場合にメッセージ配信の条件を示します。

未承認の配信とトランザクション以外のプロデューサー

メッセージが進行中の場合、送信タイムアウトが設定されておらず、経過していないとすると、再接続後に再度送信されます。

ユーザーのアクションは不要です。

トランザクションがコミットされていないトランザクションとのトランザクションプロデューサー

メッセージが進行中の場合は、再接続後に再度送信されます。新しいトランザクションで送信が最初に送信された場合は、再接続後に通常通りに送信が続行されます。トランザクションに 1 つ前の送信がある場合は、トランザクションが失敗したと見なされ、後続のコミット操作によって TransactionRolledBackException がスローされます。

配信を図るには、失敗したトランザクションに属するメッセージを再送信する必要があります。

保留中のコミットとトランザクションプロデューサー

コミットが フライト である場合、トランザクションは失敗とみなされ、後続のコミット操作によって TransactionRolledBackException がスローされます。

配信を図るには、失敗したトランザクションに属するメッセージを再送信する必要があります。

未承認配信のあるトランザクションでないコンシューマー

メッセージが受信してもまだ確認されていないと、メッセージを承認すると、エラーは生成されませんが、クライアントによるアクションはありません。

受信したメッセージが確認されていないため、プロデューサーは再送することがあります。重複を回避するために、ユーザーはメッセージ ID で重複メッセージをフィルタリングする必要があります。

コミットされていないトランザクションを使用したトランザクションコンシューマー

アクティブなトランザクションがまだコミットされていない場合は、失敗とみなされ、保留中の承認はドロップされます。後続のコミット操作によって TransactionRolledBackException がスローされます。

プロデューサーは、トランザクションに属するメッセージを再送信する可能性があります。重複を回避するために、ユーザーはメッセージ ID で重複メッセージをフィルタリングする必要があります。

保留中のコミットのあるトランザクションコンシューマー

コミットがフライトの場合、トランザクションは失敗とみなされます。後続のコミット操作によって TransactionRolledBackException がスローされます。

プロデューサーは、トランザクションに属するメッセージを再送信する可能性があります。重複を回避するために、ユーザーはメッセージ ID で重複メッセージをフィルタリングする必要があります。

8.2. 拡張セッション承認モード

クライアントは、JMS 仕様で定義されたもの以外の追加のセッション確認モードをサポートします。

個別確認応答

このモードでは、セッションが CLIENT_ACKNOWLEDGE モードの場合に使用される Message.acknowledge() メソッドを使用して、メッセージを個別に承認する必要があります。CLIENT_ACKNOWLEDGE モードとは異なり、ターゲットメッセージのみが確認されます。それ以外の配信されたメッセージはすべて承認されていないままになります。このモードを有効にするために使用される整数値は 101 です。

connection.createSession(false, 101);
確認なし

このモードでは、クライアントへのディスパッチ前にサーバーでメッセージを受け入れ、承認はクライアントによって実行されません。クライアントは、このモードをアクティブにするために 2 つの整数値をサポートします (100 および 257)。

connection.createSession(false, 100);

第9章 ロギング

9.1. ロギングの設定

クライアントは SLF4J API を使用し、ユーザーがニーズに基づいて特定のロギング実装を選択できるようにします。たとえば、ユーザーは slf4j-log4j バインディングを提供して Log4J 実装を選択できます。SLF4J の詳細は、その Web サイト から入手できます。

クライアントは org.apache.qpid.jms 階層内に存在する Logger の名前を使用します。これを使用して、ニーズに合わせてロギング実装を設定することができます。

9.2. プロトコルロギングの有効化

デバッグ時には、Qpid Proton AMQP 1.0 ライブラリーから追加のプロトコルトレースロギングを有効にすると便利です。これを行う方法は 2 つあります。

  • 環境変数 (Java システムプロパティーではない) PN_TRACE_FRM1 に設定します。変数が 1 に設定されている場合は、Proton がフレームロギングをコンソールに出力します。
  • amqp.traceFrames=true オプションを 接続 URI に追加しorg.apache.qpid.jms.provider.amqp.FRAMES ロガーをログレベル TRACE に設定します。これにより、プロトコルトレーサーが Proton に追加され、ログの出力が含まれます。

入力および出力バイトの低レベルトレースを出力するようにクライアントを設定することもできます。これを有効にするには、オプション transport.traceBytes=true接続 URI に追加し、org.apache.qpid.jms.transports.netty.NettyTcpTransport ロガーをログレベル DEBUG に設定します。

第10章 分散トレーシング

クライアントは、OpenTracing 標準の Jaeger 実装に基づいて分散トレーシングを提供します。

10.1. 分散トレースの有効化

アプリケーションでトレースを有効にするには、以下の手順に従います。

手順

  1. Jaeger クライアントの依存関係を POM ファイルに追加します。

    <dependency>
      <groupId>io.jaegertracing</groupId>
      <artifactId>jaeger-client</artifactId>
      <version>${jaeger-version}</version>
    </dependency>

    ${jaeger-version} 1.0.0 以降である必要があります。

  2. 接続 URI に jms.tracing オプションを追加します。この値は opentracing に設定します。

    例: トレースが有効になっている接続 URI

    amqps://example.net?jms.tracing=opentracing

  3. グローバルトレーサーを登録します。

    例: グローバルトレーサーの登録

    import io.jaegertracing.Configuration;
    import io.opentracing.Tracer;
    import io.opentracing.util.GlobalTracer;
    
    public class Example {
        public static void main(String[] args) {
            Tracer tracer = Configuration.fromEnv("<service-name>").getTracer();
            GlobalTracer.registerIfAbsent(tracer);
    
            // ...
        }
    }

  4. トレーシングのための環境を設定します。

    例: トレーシング設定

    $ export JAEGER_SAMPLER_TYPE=const
    $ export JAEGER_SAMPLER_PARAM=1
    $ java -jar example.jar net.example.Example

    ここで示された設定はデモ目的で使用されます。Jaeger の設定に関する詳細は、「Configuration via Environment and Jaeger Sampling」を参照してください。

アプリケーションをキャプチャーするトレースを表示するには、Jaeger Getting Started を使用して Jaeger インフラストラクチャーおよびコンソールを実行します。

第11章 相互運用性

本章では、AMQ JMS を他の AMQ コンポーネントと組み合わせて使用する方法を説明します。AMQ コンポーネントの互換性の概要は、「製品の概要」を参照してください。

11.1. 他の AMQP クライアントとの相互運用

AMQP メッセージAMQP タイプシステムを使用して構成されます。この一般的な形式を使用するのは、異なる言語の AMQP クライアントが、相互運用できることが理由です。このセクションでは、クライアントと他の AMQP クライアントの使用を支援するために、使用されるさまざまな JMS メッセージタイプに関連して、クライアントによって送受信された AMQP ペイロードに関する動作を文書化します。

11.1.1. メッセージの送信

このセクションでは、さまざまな JMS メッセージタイプの使用時にクライアントが送信した各種ペイロードを文書化するため、他のクライアントを使用してそれらを受信するのを支援する方法を説明します。

11.1.1.1. メッセージタイプ
JMS メッセージタイプ提出された AMQP メッセージの説明

TextMessage

TextMessage は、本文テキストの utf8 でエンコードされた文字列 を含む amqp-value ボディーセクションを使用して送信されます。本文テキストが設定されていない場合は null になります。"x-opt-jms-msg-type" の 記号キーを持つメッセージアノテーションは、5 の バイト 値に設定されます。

BytesMessage

BytesMessage は、BytesMessage ボディーからの raw バイトを含む data ボディーセクションを使用して送信され、properties セクションの content-type フィールドは 記号の 値 “application/octet-stream” に設定します。"x-opt-jms-msg-type" の 記号キーを持つメッセージアノテーションは、3 の バイト 値に設定されます。

MapMessage

MapMessage ボディーは、単一の マップ 値が含まれる amqp-value ボディーセクションを使用して送信されます。MapMessage ボディーの byte[] 値はマップのバイナリーエントリーとしてエンコードされます。"x-opt-jms-msg-type" の記号 キーを持つメッセージアノテーションは、2 の バイト 値に設定されます。

StreamMessage

StreamMessage は、StreamMessage ボディーのエントリーが含まれる amqp-sequence ボディーセクションを使用して送信されます。StreamMessage ボディーの byte[] エントリーは、シーケンス バイナリー エントリーとしてエンコードされます。"x-opt-jms-msg-type" の記号 キーを持つメッセージアノテーションは、4 の バイト 値に設定されます。

ObjectMessage

ObjectMessage は、ObjectOutputStream を使用して ObjectMessage ボディーをシリアライズするバイトを含む data ボディーセクションを使用して送信されます。また、properties セクションの content-type フィールドは、記号"application/x-java-serialized-object" に設定されます。"x-opt-jms-msg-type" の記号 キーを持つメッセージアノテーションは、1 の バイト 値に設定されます。

メッセージ

プレーンな JMS メッセージにはボディーがなく、null を含む amqp-value ボディーセクションとして送信されます。"x-opt-jms-msg-type" の記号 キーを持つメッセージアノテーションは、0 の バイト 値に設定されます。

11.1.1.2. メッセージのプロパティー

JMS メッセージでは、さまざまな Java タイプのアプリケーションプロパティーの設定がサポートされます。ここでは、送信されたメッセージの application-properties セクションで、これらのプロパティー型から AMQP 型の値へのマッピングを説明します。JMS と AMQP はいずれもプロパティー名に文字列キーを使用します。

JMS プロパティータイプAMQP アプリケーションプロパティーのタイプ

boolean

boolean

byte

byte

short

short

int

int

long

long

float

float

double

double

String

文字列 または null

11.1.2. メッセージの受信

このセクションでは、クライアントが受信した各種ペイロードをさまざまな JMS メッセージタイプにマッピングし、他のクライアントを使用してメッセージを受信して JMS クライアントによる受信用にメッセージを送信するために使用されます。

11.1.2.1. メッセージタイプ

受信した AMQP メッセージに "x-opt-jms-msg-type" message-annotation が存在する場合は、その値を使用して、表で説明されているマッピングに従ってその使用された JMS メッセージタイプを判断します。これは、JMS クライアントによって送信されるメッセージについて説明されるマッピングのリバースプロセスを反映しています。

AMQP “x-opt-jms-msg-type” message-annotation 値 (タイプ)JMS メッセージタイプ

0 (バイト)

メッセージ

1 (バイト)

ObjectMessage

2 (バイト)

MapMessage

3 (バイト)

BytesMessage

4 (バイト)

StreamMessage

5 (バイト)

TextMessage

"x-opt-jms-msg-type" message-annotation が存在しない場合、以下の表でメッセージが JMS メッセージタイプにマップされます。StreamMessage および MapMessage タイプは、アノテーション付きメッセージにのみ割り当てられていることに注意してください。

"x-opt-jms-msg-type" アノテーションなしの Received AMQP メッセージの説明JMS メッセージタイプ
  • 文字列 または null を含む amqp-value ボディーセクション。
  • プロパティー セクションの content-type フィールドが "text/plain""application/xml"、または "application/json" などの共通のテキストメディアタイプを表す シンボル 値に設定される data ボディーセクション。

TextMessage

  • バイナリー を含む amqp-value ボディーセクション。
  • プロパティー セクションの content-type フィールドが設定されていないか、記号"application/octet-stream”、または別のメッセージタイプと関連付けられない値に設定されている data ボディーセクション。

BytesMessage

  • プロパティー セクションの content-type フィールドが 記号"application/x- java-serialized-object" に設定された data ボディセクション。
  • 上記の説明のない値を含む amqp-value ボディーセクション。
  • amqp-sequence ボディーセクション。これは ObjectMessage 内で List として表されます。

ObjectMessage

11.1.2.2. メッセージのプロパティー

このセクションでは、受信した AMQP メッセージの application-properties セクションから JMS メッセージで使用される Java 型へのマッピングについて説明します。

AMQP アプリケーションプロパティーのタイプJMS プロパティータイプ

boolean

boolean

byte

byte

short

short

int

int

long

long

float

float

double

double

string

String

null

String

11.2. AMQ Broker への接続

AMQ Broker は AMQP 1.0 クライアントと相互運用するために設計されています。以下をチェックして、ブローカーが AMQP メッセージング用に設定されていることを確認します。

  • ネットワークファイアウォールのポート 5672 が開いている。
  • AMQ Broker AMQP アクセプターが有効になっています。「デフォルトのアクセプター設定」を参照してください。
  • 必要なアドレスはブローカーで設定されます。「Addresses, Queues, and Topics」を参照してください。
  • ブローカーはクライアントからアクセスを許可するよう設定され、クライアントは必要なクレデンシャルを送信するように設定されます。Broker Security を参照してください。

11.3. AMQ Interconnect への接続

AMQ Interconnect は AMQP 1.0 クライアントと動作します。以下をチェックして、コンポーネントが正しく設定されていることを確認します。

  • ネットワークファイアウォールのポート 5672 が開いている。
  • ルーターはクライアントからアクセスを許可するよう設定され、クライアントは必要なクレデンシャルを送信するように設定されます。「ネットワーク接続のセキュリティー保護」を参照してください。

付録A サブスクリプションの使用

AMQ は、ソフトウェアサブスクリプションから提供されます。サブスクリプションを管理するには、Red Hat カスタマーポータルでアカウントにアクセスします。

A.1. アカウントへのアクセス

手順

  1. access.redhat.com に移動します。
  2. アカウントがない場合は、作成します。
  3. アカウントにログインします。

A.2. サブスクリプションのアクティベート

手順

  1. access.redhat.com に移動します。
  2. サブスクリプション に移動します。
  3. Activate a subscription に移動し、16 桁のアクティベーション番号を入力します。

A.3. リリースファイルのダウンロード

.zip、.tar.gz、およびその他のリリースファイルにアクセスするには、カスタマーポータルを使用してダウンロードする関連ファイルを検索します。RPM パッケージまたは Red Hat Maven リポジトリーを使用している場合、この手順は必要ありません。

手順

  1. ブラウザーを開き、access.redhat.com/downloads で Red Hat カスタマーポータルの Product Downloads ページにログインします。
  2. INTEGRATION AND AUTOMATION カテゴリーで Red Hat AMQ エントリーを見つけます。
  3. 必要な AMQ 製品を選択します。Software Downloads ページが開きます。
  4. コンポーネントの Download リンクをクリックします。

A.4. パッケージを受信するためのシステムの登録

この製品の RPM パッケージを Red Hat Enterprise Linux にインストールするには、お使いのシステムを登録する必要があります。ダウンロードしたリリースファイルを使用している場合は、この手順は必要ありません。

手順

  1. access.redhat.com に移動します。
  2. Registration Assistant に移動します。
  3. ご使用の OS バージョンを選択し、次のページに進みます。
  4. システムの端末に一覧表示されたコマンドを使用して、登録を完了します。

システムを登録する方法は、以下のリソースを参照してください。

付録B Red Hat Maven リポジトリーの使用

本セクションでは、ソフトウェアで Red Hat が提供する Maven リポジトリーを使用する方法を説明します。

B.1. オンラインリポジトリーの使用

Red Hat は、Maven ベースのプロジェクトで使用する中央 Maven リポジトリーを維持します。詳細は、リポジトリーの welcome ページ を参照してください。

Red Hat リポジトリーを使用するように Maven を設定する方法は 2 つあります。

Maven 設定へのリポジトリーの追加

この設定の手法は、POM ファイルがリポジトリー設定を上書きせず、含まれるプロファイルが有効になっている限り、ユーザーが所有するすべての Maven プロジェクトに適用されます。

手順

  1. Maven settings.xml ファイルを見つけます。通常、これはユーザーのホームディレクトリー内の .m2 ディレクトリー内にあります。ファイルが存在しない場合は、テキストエディターを使用して作成します。

    Linux または UNIX の場合:

    /home/<username>/.m2/settings.xml

    Windows の場合:

    C:\Users\<username>\.m2\settings.xml
  2. 以下の例のように、Red Hat リポジトリーを含む新しいプロファイルを settings.xml ファイルの profiles 要素に追加します。

    例: Red Hat リポジトリーが含まれる Maven settings.xml ファイル

    <settings>
      <profiles>
        <profile>
          <id>red-hat</id>
          <repositories>
            <repository>
              <id>red-hat-ga</id>
              <url>https://maven.repository.redhat.com/ga</url>
            </repository>
          </repositories>
          <pluginRepositories>
            <pluginRepository>
              <id>red-hat-ga</id>
              <url>https://maven.repository.redhat.com/ga</url>
              <releases>
                <enabled>true</enabled>
              </releases>
              <snapshots>
                <enabled>false</enabled>
              </snapshots>
            </pluginRepository>
          </pluginRepositories>
        </profile>
      </profiles>
      <activeProfiles>
        <activeProfile>red-hat</activeProfile>
      </activeProfiles>
    </settings>

Maven 設定に関する詳細は、Maven 設定リファレンス を参照してください。

POM ファイルへのリポジトリーの追加

プロジェクトに直接リポジトリーを設定するには、以下の例のように、POM ファイルの repositories 要素に新しいエントリーを追加します。

例: Red Hat リポジトリーが含まれる Maven pom.xml ファイル

<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>example-app</artifactId>
  <version>1.0.0</version>

  <repositories>
    <repository>
      <id>red-hat-ga</id>
      <url>https://maven.repository.redhat.com/ga</url>
    </repository>
  </repositories>
</project>

POM ファイル設定の詳細は、「Maven POM リファレンス」を参照してください。

B.2. ローカルリポジトリーの使用

Red Hat は、そのコンポーネントの一部に対してファイルベースの Maven リポジトリーを提供します。これらは、ローカルファイルシステムに抽出できるダウンロード可能なアーカイブとして提供されます。

ローカルに抽出したリポジトリーを使用するように Maven を設定するには、Maven 設定または POM ファイルに以下の XML を適用します。

<repository>
  <id>red-hat-local</id>
  <url>${repository-url}</url>
</repository>

${repository-url} 展開したリポジトリーのローカルファイルシステムパスを含むファイルの URL でなければなりません。

表B.1 ローカル Maven リポジトリーの URL の例
オペレーティングシステムファイルシステムパスURL

Linux または UNIX

/home/alice/maven-repository

file:/home/alice/maven-repository

Windows

C:\repos\red-hat

file:C:\repos\red-hat

付録C サンプルでの AMQ Broker の使用

AMQ JMS のサンプルでは、queue という名前のキューが含まれる実行中のメッセージブローカーが必要です。以下の手順に従って、ブローカーをインストールして起動し、キューを定義します。

C.1. ブローカーのインストール

AMQ Broker の使用』の説明に従い ブロッカーをインストール して、ブローカーインスタンスを作成 します。匿名アクセスを有効にします。

以下の手順では、<broker-instance-dir> としてブローカーインスタンスの場所を参照します。

C.2. ブローカーの起動

手順

  1. artemis run コマンドを使用してブローカーを起動します。

    $ <broker-instance-dir>/bin/artemis run
  2. コンソールの出力で、起動時にログに記録される重要なエラーの有無を確認します。ブローカーは、準備が整う際に Server is now live をログに記録します。

    $ example-broker/bin/artemis run
               __  __  ____    ____            _
         /\   |  \/  |/ __ \  |  _ \          | |
        /  \  | \  / | |  | | | |_) |_ __ ___ | | _____ _ __
       / /\ \ | |\/| | |  | | |  _ <| '__/ _ \| |/ / _ \ '__|
      / ____ \| |  | | |__| | | |_) | | | (_) |   <  __/ |
     /_/    \_\_|  |_|\___\_\ |____/|_|  \___/|_|\_\___|_|
    
     Red Hat AMQ <version>
    
    2020-06-03 12:12:11,807 INFO  [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server
    ...
    2020-06-03 12:12:12,336 INFO  [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
    ...

C.3. キューの作成

新しいターミナルで、artemis queue コマンドを使用して queue という名前のキューを作成します。

$ <broker-instance-dir>/bin/artemis queue create --name queue --address queue --auto-create-address --anycast

yes または no の質問への回答を求めるプロンプトが表示されます。そのすべてに no (N) と回答します。

キューが作成されると、ブローカーはサンプルプログラムと使用できるようになります。

C.4. ブローカーの停止

サンプルの実行が終了したら、artemis stop コマンドを使用してブローカーを停止します。

$ <broker-instance-dir>/bin/artemis stop

改訂日時: 2021-08-29 15:56:45 +1000

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.