AMQ Spring Boot Starter の使用
AMQ Clients 2.10 向け
概要
多様性を受け入れるオープンソースの強化
Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。これは大規模な取り組みであるため、これらの変更は今後の複数のリリースで段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージをご覧ください。
第1章 概要
AMQ Spring Boot Starter は、AMQ メッセージングを使用する Spring ベースのアプリケーションを作成するためのアダプターです。スタンドアロン Spring アプリケーションを構築できる Spring Boot スターターモジュールを提供します。スターターは、AMQ JMS クライアントを使用して AMQP 1.0 プロトコルを使用して通信します。
AMQ Spring Boot Starter は、複数の言語およびプラットフォームをサポートするメッセージングライブラリーのスイートである AMQ Clients の一部です。クライアントの概要は、「AMQ Clients の概要」を参照してください。本リリースに関する詳細は、『AMQ Clients 2.10 リリースノート』を参照してください。
AMQ Spring Boot Starter は AMQP 1.0 JMS Spring Boot プロジェクトをベースとしています。
1.1. 主な特長
- メッセージングが組み込まれたスタンドアロンの Spring アプリケーションをすばやく構築
- JMS リソースの自動設定
- JMS 接続およびセッションの設定可能なプール
1.2. サポート対象の標準およびプロトコル
- Spring Boot API のバージョン 2.2
- Java Message Service API のバージョン 2.0
- Advanced Message Queueing Protocol (AMQP) バージョン 1.0
1.3. サポートされる構成
AMQ Spring Boot Starter でサポートされている設定については、Red Hat カスタマーポータルの「Red Hat AMQ 7 でサポートされる構成」を参照してください。
1.4. 本書の表記慣例
sudo コマンド
本書では、root 権限を必要とするコマンドには sudo
が使用されています。何らかの変更がシステム全体に影響する可能性があるため、sudo
を使用する場合は注意が必要です。sudo
の詳細は、「sudo コマンドの使用」を参照してください。
ファイルパス
本書では、すべてのファイルパスが Linux、UNIX、および同様のオペレーティングシステムで有効です (例: /home/andrea
)。Microsoft Windows では、同等の Windows パスを使用する必要があります (例: C:\Users\andrea
)。
変数テキスト
本書には、実際の環境に固有の値に置き換える必要がある変数を含むコードブロックが含まれています。変数テキストは中括弧で囲まれ、斜体の等幅フォントとしてスタイル設定されます。たとえば、以下の例では、<project-dir>
を実際の環境の値に置き換えます。
$ cd <project-dir>
第2章 インストール
本章では、環境に AMQ Spring Boot Starter をインストールする手順を説明します。
2.1. 前提条件
- AMQ リリースファイルおよびリポジトリーにアクセスするには、サブスクリプション が必要です。
- AMQ Spring Boot Starter でプログラムをビルドするには、Apache Maven をインストールする必要があります。
- AMQ Spring Boot Starter を使用するには、Java をインストールする必要があります。
2.2. 「Using the Red Hat Maven repository」
Red Hat Maven リポジトリーからクライアントライブラリーをダウンロードするように Maven 環境を設定します。
手順
Red Hat リポジトリーを Maven 設定または POM ファイルに追加します。設定ファイルの例については、「オンラインリポジトリーの使用」 を参照してください。
<repository> <id>red-hat-ga</id> <url>https://maven.repository.redhat.com/ga</url> </repository>
ライブラリー依存関係を POM ファイルに追加します。
<dependency> <groupId>org.amqphub.spring</groupId> <artifactId>amqp-10-jms-spring-boot-starter</artifactId> <version>2.5.0.redhat-00001</version> </dependency>
これで、クライアントが Maven プロジェクトで利用できるようになりました。
2.3. 「Installing a local Maven repository」
オンラインリポジトリーの代わりに、AMQ Spring Boot Starter をファイルベースの Maven リポジトリーとしてローカルファイルシステムにインストールできます。
手順
- サブスクリプションを使用 して AMQ Clients 2.10.0 Spring Boot Starter Maven リポジトリー の .zip ファイルをダウンロードします。
ファイルの内容を選択したディレクトリーに展開します。
Linux または UNIX の場合は、
unzip
コマンドを使用してファイルの内容を展開します。$ unzip amq-clients-2.10.0-spring-boot-starter-maven-repository.zip
Windows で、.zip ファイルを右クリックし、Extract All を選択します。
-
展開したインストールディレクトリー内の
maven-repository
ディレクトリーのリポジトリーを使用するように Maven を設定します。詳細は、「「ローカルリポジトリーの使用」」を参照してください。
第3章 スタートガイド
本章では、環境を設定して簡単なメッセージングプログラムを実行する手順を説明します。
3.1. 前提条件
- サンプルをビルドするには、Red Hat リポジトリー または ローカルリポジトリー を使用するように Maven を設定する必要があります。
-
localhost
で接続をリッスンするメッセージブローカーが必要です。匿名アクセスを有効にする必要があります。詳細は、「ブローカーの開始」を参照してください。 -
example
という名前のキューが必要です。詳細は、「キューの作成」を参照してください。
3.2. Hello World の実行
Hello World の例では、ブローカーへの接続を作成し、グリーティングが含まれるメッセージを example
キューに送信し、それを受け取ります。成功すると、受け取ったメッセージをコンソールに出力します。
例: "Hello World!" の送受信 (HelloWorld.java
)
package net.example; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.CommandLineRunner; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.jms.annotation.EnableJms; import org.springframework.jms.annotation.JmsListener; import org.springframework.jms.core.JmsTemplate; @EnableJms @SpringBootApplication public class HelloWorld implements CommandLineRunner { @Autowired private JmsTemplate jmsTemplate; public static void main(String[] args) { SpringApplication.run(HelloWorld.class, args); } @Override public void run(String... strings) throws Exception { sendMessage("Hello World!"); } public void sendMessage(String text) { System.out.println(String.format("Sending '%s'", text)); this.jmsTemplate.convertAndSend("example", text); } @JmsListener(destination = "example") public void receiveMessage(String text) { System.out.println(String.format("Received '%s'", text)); } }
サンプルの実行
サンプルプログラムをコンパイルして実行するには、次の手順を使用します。
手順
-
新しいプロジェクトディレクトリーを作成します。これは、以降の手順で
<project-dir>
と呼ばれます。 サンプル一覧を以下の場所にコピーします。
<project-dir>/src/main/java/net/example/HelloWorld.java
テキストエディターを使用して、新しい
<project-dir>/pom.xml
ファイルを作成します。以下の XML を追加します。<project> <modelVersion>4.0.0</modelVersion> <groupId>net.example</groupId> <artifactId>example</artifactId> <version>1.0.0-SNAPSHOT</version> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.0</version> </parent> <dependencies> <dependency> <groupId>org.amqphub.spring</groupId> <artifactId>amqp-10-jms-spring-boot-starter</artifactId> <version>2.5.0.redhat-00001</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
プロジェクトディレクトリーに移動し、
mvn
コマンドを使用してプログラムをコンパイルします。$ mvn clean package
java
コマンドを使用してプログラムを実行します。$ java -jar target/example-1.0.0-SNAPSHOT.jar
Hello World の例を実行すると、以下のコンソール出力が表示されます。
$ java -jar target/example-1.0.0-SNAPSHOT.jar . ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.0.5.RELEASE) [...] 2018-11-05 16:21:09.849 INFO 14805 --- [main] net.example.HelloWorld: Started HelloWorld in 1.074 seconds (JVM running for 1.38) Sending 'Hello World!' Received 'Hello World!'
3.3. その他の例
他のプログラムの例は、AMQP 1.0 JMS Spring Boot プロジェクト および Spring プロジェクト から入手できます。
第4章 設定
以下のオプションは application-properties
ファイルで使用して、Spring Boot アプリケーションを設定できます。
4.1. 接続オプション
これらのオプションは、AMQ Spring Boot Starter がリモート AMQP ピアへの接続を確立する方法を決定します。スターターは、AMQ JMS を使用してネットワーク上で通信します。詳細は、「AMQ JMS クライアントの使用」を参照してください。
- amqphub.amqp10jms.remoteUrl
AMQ JMS クライアントが新しい接続を確立するために使用する接続 URI。
接続 URI 形式
amqp[s]://host:port[?option=value[&option2=value...]]
詳細は、『AMQ JMS クライアントの使用』の「接続 URI」を参照してください。
- amqphub.amqp10jms.username
- 接続の認証に使用されるユーザー名。
- amqphub.amqp10jms.password
- 接続の認証に使用されるパスワード。
- amqphub.amqp10jms.clientId
- 接続に適用されるクライアント ID。
- amqphub.amqp10jms.receiveLocalOnly
-
これを有効にすると、timeout 引数を指定した
receive
の呼び出しは、コンシューマーのローカルメッセージバッファーのみを確認します。それ以外の場合は、リモートピアをチェックし、利用可能なメッセージがないことを確認することができます。これはデフォルトで無効にされます。 - amqphub.amqp10jms.receiveNoWaitLocalOnly
-
有効にすると、
receiveNoWait
に対する呼び出しは、コンシューマーのローカルメッセージバッファーのみを確認します。それ以外の場合は、リモートピアをチェックし、利用可能なメッセージがないことを確認することができます。これはデフォルトで無効にされます。
4.2. プーリングオプション
これらのオプションは、AMQ Spring Boot Starter が JMS 接続およびセッションをキャッシュする方法を決定します。スターターは、プーリングに AMQ JMS プールを使用します。詳細は、「AMQ JMS Pool Library の使用」を参照してください。
- amqphub.amqp10jms.pool.enabled
- プーリングを有効にするかどうかを制御します。これはデフォルトで無効にされます。
- amqphub.amqp10jms.pool.maxConnections
- 1 つのプールの最大接続数。デフォルトは 1 です。
- amqphub.amqp10jms.pool.maxSessionsPerConnection
各接続のセッションの最大数。デフォルトは 500 です。負の値を指定すると制限が削除されます。
制限を超えた場合、
createSession()
は設定に応じて例外をブロックするか、または例外を出力します。- amqphub.amqp10jms.pool.blockIfSessionPoolIsFull
有効な場合は、プールでセッションが利用可能になるまで
createSession()
ブロックを呼び出します。これはデフォルトで有効になっています。無効な場合は、
createSession()
に対する呼び出しは、セッションが利用できない場合にIllegalStateException
を出力します。- amqphub.amqp10jms.pool.blockIfSessionPoolIsFullTimeout
-
createSession()
へのブロックされた呼び出しがIllegalStateException
を出力するまでの時間 (ミリ秒単位)。デフォルトは -1 で、呼び出しが永久にブロックされることを意味します。 - amqphub.amqp10jms.pool.connectionIdleTimeout
- 現在貸し出されていない接続をプールから削除できるようになるまでのミリ秒単位の時間。デフォルトは 30 秒です。値 0 を指定すると、タイムアウトが無効になります。
- amqphub.amqp10jms.pool.connectionCheckInterval
- 期限切れ接続の定期的なチェックの間隔 (ミリ秒単位)。デフォルトは 0 で、チェックが無効になっていることを意味します。
- amqphub.amqp10jms.pool.useAnonymousProducers
これを有効にすると、
createProducer()
へのすべての呼び出しに単一の匿名 JMSMessageProducer
を使用します。これはデフォルトで有効になっています。まれに、この動作が望ましくない場合があります。これを無効にすると、
createProducer()
へのすべての呼び出しは新しいMessageProducer
インスタンスになります。- amqphub.amqp10jms.pool.explicitProducerCacheSize
-
匿名プロデューサーを使用しない場合、JMS
Session
は明示的な宛先で、一定数のMessageProducer
オブジェクトをキャッシュするように設定できます。キャッシュされたプロデューサーに一致しない新しいプロデューサーが作成されると、キャッシュ内の最も古いエントリーがエビクトされます。 - amqphub.amqp10jms.pool.useProviderJMSContext
これを有効にすると、基礎となる JMS プロバイダーの
JMSContext
クラスを使用します。これはデフォルトで無効にされます。通常、プールは独自の汎用
JMSContext
実装を使用して、プロバイダー実装ではなく、プールから接続をラップします。汎用の実装には、プロバイダーの実装が制限されない可能性があります。ただし、有効にすると、JMSContext
API からの接続はプールによって管理されません。
付録A サブスクリプションの使用
AMQ は、ソフトウェアサブスクリプションから提供されます。サブスクリプションを管理するには、Red Hat カスタマーポータルでアカウントにアクセスします。
A.1. アカウントへのアクセス
手順
- access.redhat.com に移動します。
- アカウントがない場合は、作成します。
- アカウントにログインします。
A.2. サブスクリプションのアクティベート
手順
- access.redhat.com に移動します。
- サブスクリプション に移動します。
- Activate a subscription に移動し、16 桁のアクティベーション番号を入力します。
A.3. リリースファイルのダウンロード
.zip、.tar.gz、およびその他のリリースファイルにアクセスするには、カスタマーポータルを使用してダウンロードする関連ファイルを検索します。RPM パッケージまたは Red Hat Maven リポジトリーを使用している場合、この手順は必要ありません。
手順
- ブラウザーを開き、access.redhat.com/downloads で Red Hat カスタマーポータルの Product Downloads ページにログインします。
- INTEGRATION AND AUTOMATION カテゴリーで Red Hat AMQ エントリーを見つけます。
- 必要な AMQ 製品を選択します。Software Downloads ページが開きます。
- コンポーネントの Download リンクをクリックします。
A.4. パッケージを受信するためのシステムの登録
この製品の RPM パッケージを Red Hat Enterprise Linux にインストールするには、お使いのシステムを登録する必要があります。ダウンロードしたリリースファイルを使用している場合は、この手順は必要ありません。
手順
- access.redhat.com に移動します。
- Registration Assistant に移動します。
- ご使用の OS バージョンを選択し、次のページに進みます。
- システムの端末に一覧表示されたコマンドを使用して、登録を完了します。
システムを登録する方法は、以下のリソースを参照してください。
付録B Red Hat Maven リポジトリーの使用
本セクションでは、ソフトウェアで Red Hat が提供する Maven リポジトリーを使用する方法を説明します。
B.1. オンラインリポジトリーの使用
Red Hat は、Maven ベースのプロジェクトで使用する中央 Maven リポジトリーを維持します。詳細は、リポジトリーの welcome ページ を参照してください。
Red Hat リポジトリーを使用するように Maven を設定する方法は 2 つあります。
Maven 設定へのリポジトリーの追加
この設定の手法は、POM ファイルがリポジトリー設定を上書きせず、含まれるプロファイルが有効になっている限り、ユーザーが所有するすべての Maven プロジェクトに適用されます。
手順
Maven
settings.xml
ファイルを見つけます。通常、これはユーザーのホームディレクトリー内の.m2
ディレクトリー内にあります。ファイルが存在しない場合は、テキストエディターを使用して作成します。Linux または UNIX の場合:
/home/<username>/.m2/settings.xml
Windows の場合:
C:\Users\<username>\.m2\settings.xml
以下の例のように、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 でなければなりません。
オペレーティングシステム | ファイルシステムパス | URL |
---|---|---|
Linux または UNIX |
|
|
Windows |
|
|
付録C サンプルでの AMQ Broker の使用
AMQ Spring Boot Starter の例では、example
という名前のキューが含まれる実行中のメッセージブローカーが必要です。以下の手順に従って、ブローカーをインストールして起動し、キューを定義します。
C.1. ブローカーのインストール
『AMQ Broker の使用』の説明に従い ブロッカーをインストール して、ブローカーインスタンスを作成 します。匿名アクセスを有効にします。
以下の手順では、<broker-instance-dir>
としてブローカーインスタンスの場所を参照します。
C.2. ブローカーの起動
手順
artemis run
コマンドを使用してブローカーを起動します。$ <broker-instance-dir>/bin/artemis run
コンソールの出力で、起動時にログに記録される重要なエラーの有無を確認します。ブローカーは、準備が整う際に
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
コマンドを使用して example
という名前のキューを作成します。
$ <broker-instance-dir>/bin/artemis queue create --name example --address example --auto-create-address --anycast
yes または no の質問への回答を求めるプロンプトが表示されます。そのすべてに no (N
) と回答します。
キューが作成されると、ブローカーはサンプルプログラムと使用できるようになります。
C.4. ブローカーの停止
サンプルの実行が終了したら、artemis stop
コマンドを使用してブローカーを停止します。
$ <broker-instance-dir>/bin/artemis stop
改訂日時: 2021-08-29 15:42:47 +1000