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

AMQ JavaScript は、以下に示す OS と言語のバージョンをサポートしています。詳細は、Red Hat AMQ 7 Supported Configurations を参照してください。

AMQ JavaScript は、次の AMQ コンポーネントおよびバージョンとの組み合わせでサポートされています。

本セクションでは、コア API エンティティーを紹介し、コア API が連携する方法を説明します。

AMQ JavaScript は メッセージ を送受信します。メッセージは、senders と receivers を介して、接続されたピアの間で転送されます。送信側および受信側は セッション 上で確立されます。セッションは接続上で確立されます。接続は、一意に識別された 2 つの コンテナー 間で 確立されます。コネクションには複数のセッションを含めることができますが、多くの場合、必要ありません。API を使用すると、セッションが必要でない限り、セッションを無視できます。

送信ピアは、メッセージ送信用の送信者を作成します。送信側には、リモートピアでキューまたはトピックを識別する ターゲット があります。受信ピアは、メッセージ受信用の受信者を作成します。受信側には、リモートピアでキューまたはトピックを識別する ソース があります。

メッセージの送信は 配信 と呼ばれます。メッセージとは、送信される内容のことで、ヘッダーやアノテーションなどのすべてのメタデータが含まれます。配信は、そのコンテンツの移動に関連するプロトコルエクスチェンジです。

配信が完了したことを示すには、送信側または受信側セットのいずれかが解決します。送信側または受信側が解決されたことを知らせると、その配信の通信ができなくなります。受信側は、メッセージを受諾するか、拒否するかどうかを指定することもできます。

sudo コマンド

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

ファイルパス

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

変数テキスト

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

$ cd <project-dir>

.zip ファイルの内容を抽出すると、amq-clients-2.7.0-javascript という名前のディレクトリーが作成されます。これはインストールの最上位ディレクトリーであり、本書では <install-dir> と呼びます。

インストールされたライブラリーを使用するように環境を設定するには、node_modules ディレクトリーを NODE_PATH 環境変数に追加します。

$ cd amq-clients-2.7.0-javascript
$ export NODE_PATH=$PWD/node_modules:$NODE_PATH

新しいコンソールセッションすべてでこの設定を有効にするには $HOME/.bashrcファイルに NODE_PATH を設定します。

インストールをテストするには、次のコマンドを使用します。インストールされたライブラリーを正常にインポートすると、コンソールに OK と出力されます。

$ node -e 'require("rhea")' && echo OK
OK

.zip ファイルの内容を抽出すると、amq-clients-2.7.0-javascript という名前のディレクトリーが作成されます。これはインストールの最上位ディレクトリーであり、本書では <install-dir> と呼びます。

インストールされたライブラリーを使用するように環境を設定するには、node_modules ディレクトリーを NODE_PATH 環境変数に追加します。

$ cd amq-clients-2.7.0-javascript
$ set NODE_PATH=%cd%\node_modules;%NODE_PATH%

AMQ JavaScript は Web ブラウザー内で実行できます。ブラウザーと互換性のあるライブラリーのバージョンを作成するには、npm run browserify コマンドを使用します。

$ cd amq-clients-2.7.0-javascript/node_modules/rhea
$ npm install
$ npm run browserify

これにより、ブラウザーベースのアプリケーションで使用できる rhea.js という名前のファイルが作成されます。

Hello World の例では、ブローカーへの接続を作成し、グリーティングを含むメッセージをexamplesキューに送信して、受信しなおします。成功すると、受信したメッセージをコンソールに出力します。

examples ディレクトリーに移動し、helloworld.js の例を実行します。

$ cd <install-dir>/node_modules/rhea/examples
$ node helloworld.js
Hello World!

Hello World の例では、ブローカーへの接続を作成し、グリーティングを含むメッセージをexamplesキューに送信して、受信しなおします。成功すると、受信したメッセージをコンソールに出力します。

examples ディレクトリーに移動し、helloworld.js の例を実行します。

> cd <install-dir>/node_modules/rhea/examples
> node helloworld.js
Hello World!

このクライアントプログラムは <connection-url> を使用してサーバーに接続し、ターゲット <address> の送信者を作成し、<message-body> を含むメッセージを送信して接続を切断して終了します。

"use strict";

var rhea = require("rhea");
var url = require("url");

if (process.argv.length !== 5) {
    console.error("Usage: send.js <connection-url> <address> <message-body>");
    process.exit(1);
}

var conn_url = url.parse(process.argv[2]);
var address = process.argv[3];
var message_body = process.argv[4];

var container = rhea.create_container();

container.on("sender_open", function (event) {
    console.log("SEND: Opened sender for target address '" +
                event.sender.target.address + "'");
});

container.on("sendable", function (event) {
    var message = {
        body: message_body
    };

    event.sender.send(message);

    console.log("SEND: Sent message '" + message.body + "'");

    event.sender.close();
    event.connection.close();
});

var opts = {
    host: conn_url.hostname,
    port: conn_url.port || 5672,
    // To connect with a user and password:
    // username: "<username>",
    // password: "<password>",
};

var conn = container.connect(opts);
conn.open_sender(address);

サンプルの実行

サンプルプログラムを実行するには、サンプルプログラムをローカルファイルにコピーし、node コマンドを使用して呼び出します。

$ node send.js amqp://localhost queue1 hello

このクライアントプログラムは <connection-url> を使用してサーバーに接続し、ソース <address> の受信側を作成し、終了するか、<count> メッセージに到達するまでメッセージを受信します。

"use strict";

var rhea = require("rhea");
var url = require("url");

if (process.argv.length !== 4 && process.argv.length !== 5) {
    console.error("Usage: receive.js <connection-url> <address> [<message-count>]");
    process.exit(1);
}

var conn_url = url.parse(process.argv[2]);
var address = process.argv[3];
var desired = 0;
var received = 0;

if (process.argv.length === 5) {
    desired = parseInt(process.argv[4]);
}

var container = rhea.create_container();

container.on("receiver_open", function (event) {
    console.log("RECEIVE: Opened receiver for source address '" +
                event.receiver.source.address + "'");
});

container.on("message", function (event) {
    var message = event.message;

    console.log("RECEIVE: Received message '" + message.body + "'");

    received++;

    if (received == desired) {
        event.receiver.close();
        event.connection.close();
    }
});

var opts = {
    host: conn_url.hostname,
    port: conn_url.port || 5672,
    // To connect with a user and password:
    // username: "<username>",
    // password: "<password>",
};

var conn = container.connect(opts);
conn.open_receiver(address);

サンプルの実行

サンプルプログラムを実行するには、サンプルプログラムをローカルファイルにコピーし、python コマンドを使用して呼び出します。

$ node receive.js amqp://localhost queue1

AMQ JavaScript は非同期イベント駆動型 API です。アプリケーションがイベントを処理する方法を定義するには、ユーザーはイベント処理関数をコンテナーオブジェクトに登録します。これらの関数は、ネットワークアクティビティーとして呼び出され、タイマーが新規イベントをトリガーします。

var rhea = require("rhea");
var container = rhea.create_container();

container.on("sendable", function (event) {
    console.log("A message can be sent");
});

container.on("message", function (event) {
    console.log("A message is received");
});

これらはごく一部の一般的なケースイベントのみです。完全なセットは {ClientAmqpJavaScriptApiLink} に記載されています。

イベント引数には、イベントが関係するオブジェクトにアクセスするための属性が含まれます。たとえば、connection_open イベントはイベント 接続 属性を設定します。

イベントのプライマリーオブジェクトに加えて、イベントのコンテキストを形成する全オブジェクトも設定されます。特定のイベントに対する関連性のない属性は null です。

event.container
event.connection
event.session
event.sender
event.receiver
event.delivery
event.message

コンテナーは最上位の API オブジェクトです。これは、接続を作成するエントリーポイントであり、メインのイベントループを実行します。多くの場合、これはグローバルイベントハンドラーで構築されます。

var rhea = require("rhea");
var container = rhea.create_container();

各コンテナーインスタンスには、コンテナー ID と呼ばれる一意のアイデンティティーがあります。AMQ JavaScript がネットワーク接続を作成する場合、コンテナー ID をリモートピアに送信します。コンテナー ID を設定するには、 id オプションを create_container メソッドに渡します。

var container = rhea.create_container({id: "job-processor-3"});

ユーザーが ID を設定しない場合には、コンテナーが処理されると、ライブラリーは UUID を生成します。

リモートサーバーに接続するには、ホストとポートを含む接続オプションを container.connect() メソッドに渡します。

container.on("connection_open", function (event) {
    console.log("Connection " + event.connection + " is open");
});

var opts = {
    host: "example.com",
    port: 5672
};

container.connect(opts);

デフォルトのホストは localhost です。デフォルトのポートは 5672 です。

セキュアな接続の作成については、7章セキュリティー セクションを参照してください。

再接続することで、クライアントは失われた接続から復旧できます。これは、一時的なネットワークまたはコンポーネントの障害後に、分散システムのコンポーネントが再確立されるように使用されます。

AMQ JavaScript はデフォルトで再接続を有効にします。接続試行に失敗すると、クライアントは少しの遅延の後に再度試行します。遅延は、デフォルトの最大値 60 秒まで、新しい試行ごとに指数関数的に増加します。

再接続を無効にするには、reconnect 接続オプションを false に設定します。

var opts = {
    host: "example.com",
    reconnect: false
};

container.connect(opts);

次の接続試行までの間の遅延を制御するには、initial_reconnect_delay および max_reconnect_delay 接続オプションを設定します。遅延オプションはミリ秒単位で指定します。

再接続試行回数を制限するには、reconnect_limit オプションを設定します。

var opts = {
    host: "example.com",
    initial_reconnect_delay: 100,
    max_reconnect_delay: 60 * 1000,
    reconnect_limit: 10
};

container.connect(opts);

AMQ JavaScript を使用すると、代わりの接続エンドポイントをプログラムで設定できます。

複数の接続エンドポイントを指定するには、新しい接続オプションを返す関数を定義し、connection_details オプションで関数を渡します。この関数は、接続試行ごとに 1 回呼び出されます。

var hosts = ["alpha.example.com", "beta.example.com"];
var index = -1;

function failover_fn() {
    index += 1;

    if (index == hosts.length) index = 0;

    return {host: hosts[index].hostname};
};

var opts = {
    host: "example.com",
    connection_details: failover_fn
}

container.connect(opts);

この例では、ホストの一覧に対してラウンドロビンフェイルオーバーを繰り返すように実装します。このインターフェイスを使用して、独自のフェイルオーバー動作を実装できます。

AMQ JavaScript はインバウンドネットワーク接続を受け入れ、カスタムメッセージングサーバーを構築できます。

接続のリッスンを開始するには、container.listen() メソッドを使用して、ローカルホストアドレスとリッスンするポートが含まれるオプションを指定します。

container.on("connection_open", function (event) {
    console.log("New incoming connection " + event.connection);
});

var opts = {
    host: "0.0.0.0",
    port: 5672
};

container.listen(opts);

特別な IP アドレス 0.0.0.0 は、利用可能なすべての IPv4 インターフェイスでリッスンします。すべての IPv6 インターフェイスをリッスンするには [::0] を使用します。

詳細は、サーバー receive.js の例 を参照してください。

AMQ JavaScript は SSL/TLS を使用して、クライアントとサーバー間の通信を暗号化します。

SSL/TLS を使用してリモートサーバーに接続するには、トランスポート 接続オプションを tls に設定します。

var opts = {
    host: "example.com",
    port: 5671,
    transport: "tls"
};

container.connect(opts);

AMQ JavaScript は、ユーザーとパスワードによる接続を認証できます。

認証に使用する認証情報を指定するには、 username と password の接続オプションを設定します。

var opts = {
    host: "example.com",
    username: "alice",
    password: "secret"
};

container.connect(opts);

AMQ JavaScript は SASL プロトコルを使用して認証を実行します。SASL はさまざまな認証 メカニズム を使用できます。2 つのネットワークピアが接続すると、許可されたメカニズムが交換され、両方で許可されている最も強力なメカニズムが選択されます。

AMQ JavaScript は、ユーザーとパスワード情報があるかどうかによって SASL メカニズムを有効にします。ユーザーとパスワードの両方が指定されている場合は、PLAIN が使用されます。ユーザーのみを指定すると、ANONYMOUS が使用されます。いずれも指定されていない場合、SASL は無効になります。

メッセージサーバーによっては、キューとトピックのオンデマンド作成をサポートします。送信側または受信側が割り当てられている場合、サーバーは送信側ターゲットアドレスまたは受信側ソースアドレスを使用して、アドレスに一致する名前でキューまたはトピックを作成します。

メッセージサーバーは通常、キュー (1 対 1 のメッセージ配信用) またはトピック (1 対多のメッセージ配信用) を作成します。クライアントは、ソースまたはターゲットに queue または topic 機能を設定してどちらを優先するかを示すことができます。

キューまたはトピックセマンティクスを選択するには、以下の手順に従います。

var conn = container.connect({host: "example.com"});

var sender_opts = {
    target: {
        address: "jobs",
        capabilities: ["queue"]
    }
}

conn.open_sender(sender_opts);

var conn = container.connect({host: "example.com"});

var receiver_opts = {
    source: {
        address: "notifications",
        capabilities: ["topic"]
    }
}

conn.open_receiver(receiver_opts);

詳細は、以下の例を参照してください。

永続サブスクリプションは、メッセージの受信側を表すリモートサーバーの状態です。通常、メッセージ受信者は、クライアントが終了すると、破棄されます。ただし、永続サブスクリプションは永続的であるため、クライアントはそれらのサブスクリプションの割り当てを解除してから、後で再度アタッチできます。デタッチ時に受信したすべてのメッセージは、クライアントの再割り当て時に利用できます。

永続サブスクリプションは、クライアントコンテナー ID とレシーバー名を組み合わせてサブスクリプション ID を形成することで一意に識別されます。これらには、サブスクリプションを回復できるように、安定した値が必要です。

サブスクリプションからデタッチするには、receiver.detach() メソッドを使用します。サブスクリプションを終了するには、receiver.close() メソッドを使用します。

詳細は、durable-subscribe.js の例 を参照してください。

共有サブスクリプションとは、1 つ以上のメッセージレシーバーを表すリモートサーバーの状態のことです。このサブスクリプションは共有されているため、複数のクライアントが同じメッセージのストリームから消費できます。

クライアントは、受信者のソースにshared 機能を設定して、共有サブスクリプションを設定します。

共有サブスクリプションは、クライアントコンテナー ID とレシーバー名を組み合わせてサブスクリプション ID を形成することで一意に識別されます。複数のクライアントプロセスで同じサブスクリプションを特定できるように、これらに安定した値を指定する必要があります。shared に加えて global 機能が設定されている場合、サブスクリプション識別に受信者名だけが使用されます。

永続サブスクリプションを作成するには、以下の手順に従います。

サブスクリプションからデタッチするには、receiver.detach() メソッドを使用します。サブスクリプションを終了するには、receiver.close() メソッドを使用します。

詳細は、shared-subscribe.js の例 を参照してください。

設定されている場合には、AMQ JavaScript は MESSAGING_CONNECT_FILE 環境変数の値を使用して設定ファイルを検索します。

MESSAGING_CONNECT_FILE が設定されていない場合には、AMQ JavaScript は以下の場所で connect.json という名前のファイルを検索します。最初の一致で停止します。

connect.json ファイルが見つからない場合、ライブラリーはすべてのオプションにデフォルト値を使用します。

connect.json ファイルには JSON データが含まれ、JavaScript コメントの追加サポートが提供されます。

設定属性はすべてオプションであるか、デフォルト値があるため、簡単な例では詳細をいくつか指定するだけで済みます。

{
    "host": "example.com",
    "user": "alice",
    "password": "secret"
}

SASL および SSL/TLS オプションは、"sasl" および "tls" namespace で入れ子になっています。

{
    "host": "example.com",
    "user": "ortega",
    "password": "secret",
    "sasl": {
        "mechanisms": ["SCRAM-SHA-1", "SCRAM-SHA-256"]
    },
    "tls": {
        "cert": "/home/ortega/cert.pem",
        "key": "/home/ortega/key.pem"
    }
}

ドット (.) を含むオプションキーは、namespace にネストされた属性を表します。

AMQP メッセージは AMQP タイプシステムを使用して設定されます。このような一般的な形式は、異なる言語の AMQP クライアントが相互に対話できる理由の 1 つです。

メッセージを送信する場合、AMQ JavaScript は自動的に言語ネイティブの型を AMQP でエンコードされたデータに変換します。メッセージの受信時に、リバース変換が行われます。

JavaScript にあるネイティブ型は、AMQP がエンコードできる数よりも少なくなっています。特定の AMQP タイプを含むメッセージを送信するには、 rhea/types.js モジュールの wrap_ 関数を使用します。

AMQP は JMS メッセージングモデルへの標準マッピングを定義します。本セクションでは、そのマッピングのさまざまな側面について説明します。詳細は、AMQ JMS Interoperability の章を参照してください。

JMS メッセージタイプ

AMQ JavaScript は、本文タイプが異なる、単一のメッセージを提供します。一方、JMS API は異なるメッセージタイプを使用してさまざまな種類のデータを表します。次の表は、特定の本文タイプが JMS メッセージタイプにどのようにマップされるかを示しています。

作成される JMS メッセージタイプをさらに明示的に制御するには、x-opt-jms-msg-type メッセージアノテーションを設定できます。詳細は、AMQ JMS Interoperability の章を参照してください。

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

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