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

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

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

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

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

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

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

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

sudo コマンド

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

ファイルパス

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

変数テキスト

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

$ cd <project-dir>

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

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

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

この例では、exampleQueue という名前のキューにコンシューマーおよびプロデューサーを作成します。テキストメッセージを送信した後、それを受信して、受信したメッセージをコンソールに出力します。

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

$ java -cp "target/classes:target/dependency/*" org.apache.activemq.artemis.jms.example.QueueExample
Sent message: This is a text message
Received message: This is a text message

この例のソースコードは <install-dir>/examples/protocols/openwire/queue/src ディレクトリーにあります。その他の例は、<install-dir>/examples/protocols/openwire ディレクトリーにあります。

JMS アプリケーションは、InitialContextFactory から取得した JNDI InitialContext オブジェクトを使用して、接続ファクトリーなどの JMS オブジェクトを検索します。AMQ OpenWire JMS は、org.apache.activemq.jndi.ActiveMQInitialContextFactory クラスで 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 キーでプロパティーを追加します。

java.naming.factory.initial = org.apache.activemq.jndi.ActiveMQInitialContextFactory

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

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

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

$ java -Djava.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory ...

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

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

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

env.put("java.naming.factory.initial", "org.apache.activemq.jndi.ActiveMQInitialContextFactory");

InitialContext context = new InitialContext(env);

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

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

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

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

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

connectionFactory.app1 = tcp://example.net:61616?jms.clientID=backend

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

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

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

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

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

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

tcp://example.net:61616?jms.clientID=backend

フェイルオーバー URI

再接続およびフェイルオーバーに使用される URI には複数の接続 URI を含めることができます。以下の形式を使用します。

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

nested. で始まるトランスポートオプションは、リストの各接続 URI に適用されます。

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

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

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

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

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

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

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

prefetch ポリシーオプション

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

prefetch の値は、キューの複数のコンシューマーへのメッセージの分散に影響します。値が大きいと、各コンシューマーに一度に送信されるバッチが大きくなる可能性があります。コンシューマーが異なるレートで動作している場合に、より均等にラウンドロビンの分散を実現するには、小さい値を使用します。

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

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

大きなメッセージに書き込むには、BytesMessage.writeBytes() メソッドを使用します。以下の例では、ファイルからバイトを読み取り、メッセージに書き込みます。

BytesMessage message = session.createBytesMessage();
File inputFile = new File(inputFilePath);
InputStream inputStream = new FileInputStream(inputFile);

int numRead;
byte[] buffer = new byte[1024];

while ((numRead = inputStream.read(buffer, 0, buffer.length)) != -1) {
    message.writeBytes(buffer, 0, numRead);
}

大規模メッセージから読み取るには、BytesMessage.readBytes() メソッドを使用します。以下の例は、メッセージからバイトを読み取り、ファイルに書き込みます。

BytesMessage message = (BytesMessage) consumer.receive();
File outputFile = new File(outputFilePath);
OutputStream outputStream = new FileOutputStream(outputFile);

int numRead;
byte buffer[] = new byte[1024];

for (int pos = 0; pos < message.getBodyLength(); pos += buffer.length) {
    numRead = message.readBytes(buffer);
    outputStream.write(buffer, 0, numRead);
}