第16章 Hot Rod インターフェース

16.1. Hot Rod について

Hot Rod は、Red Hat JBoss Data Grid で使用されるバイナリー TCP クライアントサーバープロトコルであり、Memcached などの他のクライアントサーバープロトコルの欠点を解消するために作成されました。

Hot Rod はサーバークラスターでフェイルオーバーを行い、トポロジーが変更されます。Hot Rod は、クラスタートポロジーに関する更新をクライアントに定期的に提供することによりこれを行います。

Hot Rod では、クライアントはパーティション化されたまたは分散された Red Hat JBoss Data Grid サーバークラスターで要求をスマートにルーティングできます。これを行うために、Hot Rod ではクライアントはキーを格納するパーティションを決定し、キーがあるサーバーと直接通信できます。この機能は、クライアントでクラスタートポロジーを更新する Hot Rod に依存し、クライアントはサーバーと同じ一貫性のあるハッシュアルゴリズムを使用します。

Red Hat JBoss Data Grid には、Hot Rod プロトコルを実装するサーバーモジュールが含まれます。Hot Rod プロトコルを使用すると、他のテキストベースのプロトコルに比べて、クライアントとサーバーの対話が高速になり、クライアントが負荷分散、フェイルオーバー、およびデータ場所運用に関する決定を行えるようになります。

16.2. Hot Rod ヘッダー

16.2.1. Hot Rod ヘッダーデータタイプ

Red Hat JBoss Data Grid の Hot Rod で使用されたすべてのキーおよび値はバイトアレイとして格納されます。ただし、特定のヘッダー値 (REST や Memcached の値) は以下のデータタイプを使用して格納されます。

表16.1 ヘッダーデータタイプ

データタイプSize説明

vInt

1 - 5 バイト。

符号なし可変長整数値。

vLong

1-9 バイト。

符号なし可変長 long 値。

string

-

文字列は常に UTF-8 エンコーディングを使用して表されます。

16.2.2. 要求ヘッダー

Hot Rod を使用して Red Hat JBoss Data Grid にアクセスする場合、要求ヘッダーの内容は以下のものから構成されます。

表16.2 要求ヘッダーフィールド

フィールド名データタイプ/サイズ説明

Magic

1 バイト

ヘッダーが要求ヘッダーまたは応答ヘッダーであるかどうかを示します。

Message ID

vLong

メッセージ ID を含みます。この一意の ID は、要求に応答するときに使用されます。これにより、Hot Rod クライアントは非同期でプロトコルを実装できるようになります。

Version

1 バイト

Hot Rod サーバーバージョンを含みます。

Opcode

1 バイト

関連する操作コードを含みます。要求ヘッダー内でopcode には要求操作コードのみを含めることができます。

Cache Name Length

vInt

キャッシュ名の長さを格納します。キャッシュ名の長さが 0 に設定され、キャッシュ名に値が提供されない場合、操作はデフォルトのキャッシュと対話します。

Cache Name

string

指定された操作のターゲットキャッシュの名前を格納します。この名前は、キャッシュ設定ファイルの事前定義済みキャッシュの名前に一致する必要があります。

Flags

vInt

システムに渡されるフラグを表す可変長の数値を含みます。さらに多くのバイトを読み取る必要があるかどうかを決定するために使用される最大ビットを除き、各ビットはフラグを表します。各フラグを表すためにビットを使用すると、フラグの組み合わせが連結された状態で表されます。

Client Intelligence

1 バイト

サーバーに対するクライアント機能を示す値を含みます。

Topology ID

vInt

クライアントの最後の既知なビュー ID を含みます。基本的なクライアントはこのフィールドに値 0 を提供します。トポロジーまたはハッシュ情報をサポートするクライアントは、サーバーが現在のビュー ID に応答するまで値 0 (新しいビュー ID が現在のビュー ID を置き換えるためにサーバーにより返されるまで使用されます) を提供します。

16.2.3. 応答ヘッダー

Hot Rod を使用して Red Hat JBoss Data Grid にアクセスする場合、応答ヘッダーの内容は以下のものから構成されます。

表16.3 応答ヘッダーフィールド

フィールド名データタイプ説明

Magic

1 バイト

ヘッダーが要求または応答ヘッダーであるかどうかを示します。

Message ID

vLong

メッセージ ID を含みます。この一意の ID は、応答を元の要求とペアにするために使用されます。これにより、Hot Rod クライアントは非同期でプロトコルを実装できるようになります。

Opcode

1 バイト

関連する操作コードを含みます。応答ヘッダー内で opcode には応答操作コードのみを含めることができます。

Status

1 バイト

応答のステータスを表すコードを含みます。

Topology Change Marker

1 バイト

応答がトポロジー変更情報に含まれるかどうかを示すマーカーバイトを含みます。

16.2.4. トポロジー変更ヘッダー

16.2.4.1. トポロジー変更ヘッダー

Hot Rod を使用して Red Hat JBoss Data Grid にアクセスする場合は、応答ヘッダーが、異なるトポロジーまたはハッシュ分散を区別できるクライアントを探すことによりクラスターまたはビューフォーメーションの変更に応答します。Hot Rod サーバーは現在の topology ID と、クライアントにより送信された topology ID を比較し、2 つの値が異なる場合は、新しい topology ID を返します。

16.2.4.2. トポロジー変更マーカー値

以下は、応答ヘッダー内の Topology Change Marker フィールドの有効な値のリストです。

表16.4 Topology Change Marker フィールド値

Value説明

0

トポロジーの変更情報は追加されません。

1

トポロジーの変更情報が追加されます。

16.2.4.3. トポロジー認識クライアントのトポロジー変更ヘッダー

トポロジーの変更がサーバーにより返された場合、トポロジー認識クライアントに送信された応答ヘッダーには以下の要素が含まれます。

表16.5 トポロジー変更ヘッダーフィールド

応答ヘッダーフィールドデータタイプ/サイズ説明

Response Header with Topology Change Marker

変数

応答ヘッダー」を参照してください。

Topology ID

vInt

トポロジー ID。

Num Servers in Topology

vInt

クラスターで稼働している Hot Rod サーバーの数を含みます。一部のノードのみが Hot Rod サーバーを稼働している場合に、この値は、クラスター全体のサブセットになることがあります。

mX: Host/IP Length

vInt

個別クラスターメンバーのホスト名または IP アドレスの長さを含みます。可変長により、この要素にはホスト名、IPv4、および IPv6 アドレスを含めることができます。

mX: Host/IP Address

string

個別クラスターメンバーのホスト名または IP アドレスを含みます。Hot Rod クライアントはこの情報を使用して個別クラスターメンバーにアクセスします。

mX: Port

符号なしショート。2 バイト

クラスターメンバーと通信するために Hot Rod クライアントが使用するポートを含みます。

トポロジー内の各サーバーに対して、接頭辞 mX の 3 つのエントリーが繰り返されます。トポロジーの情報フィールド内の最初のサーバーには接頭辞 m1 が付けられ、X の値が num servers in topology フィールドで指定されたサーバーの数と等しくなるまで、各追加サーバーに対して数値が 1 つずつ増分されます。

16.2.4.4. ハッシュ配布認識クライアントのトポロジー変更ヘッダー

トポロジーの変更がサーバーにより返された場合、クライアントに送信された応答ヘッダーには以下の要素が含まれます。

表16.6 トポロジー変更ヘッダーフィールド

フィールドデータタイプ/サイズ説明

Response Header with Topology Change Marker

変数

応答ヘッダー」を参照してください。

Topology ID

vInt

トポロジー ID。

Number Key Owners

符号なしショート、2 バイト

配布された各キーに対してグローバルに設定されたコピーの数を含みます。配布がキャッシュで設定されていない場合は、値 0 を含みます。

Hash Function Version

1 バイト

使用中のハッシュ機能へのポインターを含みます。配布がキャッシュで設定されていない場合は、値 0 を含みます。

Hash Space Size

vInt

ハッシュコード生成に関連するすべてのモジュール計算のために JBoss Data Grid により使用されるモジュールを含みます。クライアントはこの情報を使用して正しいハッシュ計算をキーに適用します。配布がキャッシュで設定されていない場合は、値 0 を含みます。

Number servers in topology

vInt

クラスター内で稼働している [path]_ Hot Rod_ サーバーの数を含みます。一部のノードのみが [path]_ Hot Rod_ サーバーを稼働している場合に、この値は、クラスター全体のサブセットになることがあります。また、この値はヘッダーに含まれるホストとポートのペアの数を表します。

Number Virtual Nodes Owners

vInt

設定された仮想ノードの数を含みます。仮想ノードが設定されていない場合、または配布がキャッシュで設定されていない場合は、値 0 を含みます。

mX: Host/IP Length

vInt

個別クラスターメンバーのホスト名または [path]_ IP_ アドレスの長さを含みます。可変長により、この要素にはホスト名、[path]_ IPv4_ および [path]_ IPv6_ アドレスを含めることができます。

mX: Host/IP Address

string

個別クラスターメンバーのホスト名または [path]_ IP_ アドレスを含みます。[path]_ Hot Rod_ クライアントはこの情報を使用して個別クラスターメンバーにアクセスします。

mX: Port

符号なしショート、2 バイト

クラスターメンバーと通信するために [path]_ Hot Rod_ クライアントが使用するポートを含みます。

Hash Function Version

1 バイト

0x03

Number of Segments in Topology

vInt

トポロジーの合計セグメント数。

Number of Owners in Segment

1 バイト

所有者の数は 0、1、または 2 のいずれか。

First Wwner’s Index

vInt

全ノードのリストにおけるこの所有者の位置。このセグメントの所有者の数が 1 または 2 である場合のみ含まれます。

Second Owner’s Index

vInt

全ノードのリストにおけるこの所有者の位置。このセグメントの所有者の数が 2 である場合のみ含まれます。

注記

セグメントごとに所有者の数を 3 以上にすることもできますが、Hot Rod プロトコルは効率性の理由で送信する所有者の数を制限します。

トポロジー内の各サーバーに対して、接頭辞 mX の 3 つのエントリーが繰り返されます。トポロジーの情報フィールド内の最初のサーバーには接頭辞 m1 が付けられ、X の値が num servers in topology フィールドで指定されたサーバーの数と等しくなるまで、各追加サーバーに対して数値が 1 つずつ増分されます。

16.3. Hot Rod 操作

16.3.1. Hot Rod 操作

以下は、Hot Rod プロトコル 1.3 を使用して Red Hat JBoss Data Grid と対話する場合に有効な操作です。

  • Authenticate
  • AuthMechList
  • BulkGet
  • BulkKeysGet
  • Clear
  • ContainsKey
  • Exec
  • Get
  • GetAll
  • GetWithMetadata
  • GetWithVersion
  • IterationEnd
  • IterationNext
  • IterationStart
  • Ping
  • Put
  • PutAll
  • PutIfAbsent
  • Query
  • Remove
  • RemoveIfUnmodified
  • Replace
  • ReplaceIfUnmodified
  • Stats
  • Size
重要

RemoteCache API を使用して Hot Rod クライアントの Put 操作、PutIfAbsent 操作、Replace 操作、および ReplaceWithVersion 操作を呼び出す場合に、ライフスパンが 30 日よりも大きい値に設定されると、その値は UNIX 時間として処理され、1970 年 1 月 1 日以降の秒数を表します。

16.3.2. Hot Rod の Authenticate 操作

この操作の目的は、SASL を使用してクライアントをサーバーに対して認証することです。選択した mech によっては、認証プロセスが複数のステップの操作になることがあります。この操作が完了すると、接続が認証されます。

Authenticate 操作の要求形式には以下が含まれます。

表16.7 Authenticate 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Mech

String

認証用にクライアントによって選択された mech の名前が含まれる String。後続の呼び出しでは空になります。

Response length

vInt

SASL クライアント応答の長さ

Response data

バイトアレイ

SASL クライアント応答。

この操作の応答ヘッダーには以下のものが含まれます。

表16.8 Authenticate 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

Completed

バイト

さらに処理が必要な場合は 0、認証が完了した場合は 1 。

Challenge length

vInt

SASL サーバーチャレンジの長さ

Challenge data

バイトアレイ

SASL サーバーチャレンジ。

16.3.3. Hot Rod の AuthMechList 操作

この操作の目的は、サーバーによってサポートされる 有効な SASL 認証 mech のリストを取得することです。クライアントは優先される mech で Authenticate 要求を発行する必要があります。

AuthMechList 操作の要求形式には以下が含まれます。

表16.9 AuthMechList 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

この操作の応答ヘッダーには以下のものが含まれます。

表16.10 AuthMechList 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー

Mech count

vInt

mech の数。

Mech

String

IANA で登録された形式 (GSSAPI、CRAM-MD5 など) で SASL mech の名前が含まれる String

Mech の値はサポートされる mech ごとに繰り返されます。

16.3.4. Hot Rod の BulkGet 操作

Hot Rod の BulkGet 操作は、以下の要求形式を使用します。

表16.11 BulkGet 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Entry Count

vInt

サーバーによって返される Red Hat JBoss Data Grid エントリーの最大数が含まれます。エントリーはキーと値のペアです。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.12 BulkGet 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー

More

vInt

ストリームからエントリーをさらに読み取る必要があるかどうかを示します。More1 に設定される一方で、More の値が 0 (ストリームの最後を示します) に設定されるまで追加のエントリーが続きます。

Key Length

vInt

キーの長さを含みます。

Key

バイトアレイ

キーの値を含みます。

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

値を含みます。

要求された各エントリーに対して、MoreKey SizeKeyValue Size、および Value エントリーが応答に追加されます。

16.3.5. Hot Rod の BulkKeysGet 操作

Hot Rod の BulkKeysGet 操作は、以下の要求形式を使用します。

表16.13 BulkKeysGet 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Scope

vInt

  • 0 = デフォルトのスコープ - このスコープは RemoteCache.keySet() メソッドにより使用されます。リモートキャッシュが分散キャッシュである場合は、サーバーによりマップ/削減操作が実行され、すべてのノードからすべてのキーが取得されます (トポロジー認識 Hot Rod クライアントはクラスター内の任意のノードへの要求を負荷分散できます)。それ以外の場合は、要求を受信するサーバーに対してローカルのキャッシュインスタンスからキーを取得します。キーはレプリケートされたキャッシュのすべてのノードで同じである必要があります。
  • 1 = グローバルスコープ - このスコープはデフォルトスコープと同じように動作します。
  • 2 = ローカルスコープ - リモートキャッシュが分散キャッシュである状況では、サーバーはマップ/削減操作を開始してすべてのノードからキーを取得しません。代わりに、要求を受け取るサーバーに対してローカルなキャッシュインスタンスからローカルなキーのみを取得します。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.14 BulkKeysGet 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

Response Status

1 バイト

0x00 = 成功 (データが続きます)。

More

1 バイト

ストリームからより多くのキーを読み取る必要があるかを表す 1 つのバイト。1 に設定されている場合はエントリーが続き、0 に設定されている場合はストリームの最後であり、読み取るエントリーが残っていません。

Key Length

vInt

キーの長さ

Key

バイトアレイ

取得されたキー

More

1 バイト

ストリームからより多くのエントリーを読み取る必要があるかどうかを表す 1 つのバイト。1 に設定された場合はエントリーが続きます。0 に設定された場合はストリームの最後であり、読み取るエントリーが残っていません。

Key Length および Key の値はキーごとに繰り返されます。

16.3.6. Hot Rod の Clear 操作

clear 操作の形式にはヘッダーのみが含まれます。

この操作に有効な応答ステータスは以下のとおりです。

表16.15 clear 操作の応答

Response Status説明

0x00

Red Hat JBoss Data Grid が正常に消去されました。

16.3.7. Hot Rod の ContainsKey 操作

Hot Rod の ContainsKey 操作は、以下の要求形式を使用します。

表16.16 ContainsKey 操作の要求形式

フィールドデータタイプ説明

Header

-

-

Key Length

vInt

キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) であるため、vInt データタイプが使用されます。ただし、Java では単一のアレイサイズを Integer.MAX_VALUE よりも大きくすることはできません。結果として、この vIntInteger.MAX_VALUE の最大サイズに制限されます。

Key

バイトアレイ

キーを含みます (このキーの対応する値が要求されます)。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.17 ContainsKey 操作の応答形式

Response Status説明

0x00

操作が成功。

0x02

キーが存在しない。

この操作の応答は空白です。

16.3.8. Hot Rod の Exec 操作

Exec 操作の要求形式には以下が含まれます。

表16.18 Exec 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Script

String

実行するスクリプトの名前。

Parameter Count

vInt

パラメーターの数。

Parameter Name (per parameter)

String

パラメーターの名前。

Parameter Length (per parameter)

vInt

パラメーターの長さ。

Parameter Value (per parameter)

バイトアレイ

パラメーターの値。

この操作の応答ヘッダーには以下のものが含まれます。

表16.19 Exec 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

Response status

1 バイト

正常に実行が完了した場合は 0x00、サーバーにエラーが発生した場合は 0x85。

Value Length

vInt

成功した場合は、戻り値の長さ。

Value

バイトアレイ

成功した場合は、実行の結果。

16.3.9. Hot Rod の Get 操作

Hot Rod の Get 操作は、以下の要求形式を使用します。

表16.20 Get 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) であるため、vInt データタイプが使用されます。ただし、Java では単一のアレイサイズを Integer.MAX_VALUE よりも大きくすることはできません。結果として、この vInt も Integer.MAX_VALUE の最大サイズに制限されます。

Key

バイトアレイ

キーを含みます (このキーの対応する値が要求されます)。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.21 Get 操作の応答形式

Response Status説明

0x00

操作が成功。

0x02

キーが存在しない。

キーが見つかった場合の get 操作の応答形式は以下のとおりです。

表16.22 Get 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

要求された値を含みます。

16.3.10. Hot Rod の GetAll 操作

指定のキーセットへマップするすべてのエントリーを取得する一括操作。

Hot Rod の GetAll 操作は、以下の要求形式を使用します。

表16.23 GetAll 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Count

vInt

エンティティーを見つけるためのキーの数。

Key Length

vInt

キーの長さ。

Key

バイトアレイ

取得されたキー

Key Length および Key の値はキーごとに繰り返されます。

この操作の応答ヘッダーには以下のものが含まれます。

表16.24 GetAll 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー

Entry count

vInt

返されたエントリーの数。

Key Length

vInt

キーの長さ。

Key

バイトアレイ

取得されたキー

Value Length

vInt

値の長さ。

Value

バイトアレイ

取得された値。

Key LengthKeyValue Length、および Value エントリーはキーおよび値ごとに繰り返されます。

16.3.11. Hot Rod の GetWithMetadata 操作

Hot Rod の GetWithMetadata 操作は、以下の要求形式を使用します。

表16.25 GetWithMetadata 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さ。vInt のサイズは最大 5 バイトであり、理論的には Integer.MAX_VALUE よりも大きい数を生成できます。ただし、Java では Integer.MAX_VALUE よりも大きい単一アレイを作成できず、プロトコルにより vInt アレイの長さが Integer.MAX_VALUE に制限されます。

Key

バイトアレイ

値が要求されるキーを含むバイトアレイ。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.26 GetWithMetadata 操作の応答要求

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

Response status

1 バイト

0x00 = 成功 (キーが取得された場合)。

0x02 =  キーが存在しない場合。

Flag

1 バイト

応答に期限切れに関する情報が含まれるかどうかを示すフラグ。フラグの値は、 INFINITE_LIFESPAN (0x01)INFINITE_MAXIDLE (0x02) 間のビットごとの OR 演算として取得されます。

Created

Long

(任意) サーバーでエントリーが作成されたときのタイムスタンプを表す Long。この値は、フラグの INFINITE_LIFESPAN ビットが設定されていない場合にのみ返されます。

Lifespan

vInt

(任意) 秒単位でエントリーのライフスパンを表すvInt 。この値は、フラグの INFINITE_LIFESPAN ビットが設定されていない場合にのみ返されます。

LastUsed

Long

(任意) サーバーでエントリーが最後にアクセスされたときのタイムスタンプを表す Long。この値は、フラグの INFINITE_MAXIDLE ビットが設定されていない場合にのみ返されます。

MaxIdle

vInt

(任意) 秒単位でエントリーの maxIdle を表すvInt 。この値は、フラグの INFINITE_MAXIDLE ビットが設定されていない場合にのみ返されます。

Entry Version

8 バイト

既存のエントリー変更の一意な値。プロトコルでは entry_version の値はシーケンシャルであることが保証されず、キーレベルで更新ごとに一意である必要があります。

Value Length

vInt

成功した場合は、値の長さ。

Value

バイトアレイ

成功した場合は、要求された値。

16.3.12. Hot Rod の GetWithVersion 操作

Hot Rod の GetWithVersion 操作は、以下の要求形式を使用します。

表16.27 GetWithVersion 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) であるため、vInt データタイプが使用されます。ただし、Java では単一のアレイサイズを Integer.MAX_VALUE よりも大きくすることはできません。結果として、この vInt も Integer.MAX_VALUE の最大サイズに制限されます。

Key

バイトアレイ

キーを含みます (このキーの対応する値が要求されます)。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.28 GetWithVersion 操作の応答形式

Response Status説明

0x00

操作が成功。

0x02

キーが存在しない。

キーが見つかった場合の GetWithVersion 操作の応答形式は以下のとおりです。

表16.29 GetWithVersion 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー

Entry Version

8 バイト

既存のエントリー変更の一意な値。プロトコルでは entry_version の値はシーケンシャルであることが保証されません。キーレベルで更新ごとに一意である必要があります。

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

要求された値を含みます。

16.3.13. Hot Rod の IterationEnd 操作

IterationEnd 操作の要求形式には以下が含まれます。

表16.30 IterationEnd 操作の要求形式

フィールドデータタイプ説明

iterationId

String

イテレーションの一意な ID。

以下は、この操作から返される有効な応答値です。

表16.31 IterationEnd 操作の応答形式

Response Status説明

0x00

操作が成功。

0x05

存在しない iterationId に対するエラー。

16.3.14. Hot Rod の IterationNext 操作

IterationNext 操作の要求形式には以下が含まれます。

表16.32 IterationNext 操作の要求形式

フィールドデータタイプ説明

IterationId

String

イテレーションの一意な ID。

この操作の応答ヘッダーには以下のものが含まれます。

表16.33 IterationNext 操作の応答形式

フィールドデータタイプ説明

Finished segments size

vInt

イテレーションを終了したセグメントを表すビットセットのサイズ。

Finished segments

バイトアレイ

イテレーションを終了したセグメントのビットセットエンコーディング。

Entry count

vInt

返されたエントリーの数。

Number of value projections

vInt

値の射影の数。

Metadata

1 バイト

設定された場合、エントリーにメタデータが関連付けされます。

Expiration

1 バイト

応答に期限切れに関する情報が含まれるかどうかを示すフラグ。フラグの値は、INFINITE_LIFESPAN (0x01)INFINITE_MAXIDLE (0x02) 間のビットごとの OR 演算として取得されます。上記の Metadata フラグが設定されている場合のみ含まれます。

Created

Long

(任意) サーバーでエントリーが作成されたときのタイムスタンプを表す Long。この値は、フラグの INFINITE_LIFESPAN ビットが設定されていない場合にのみ返されます。

Lifespan

vInt

(任意) 秒単位でエントリーのライフスパンを表すvInt 。この値は、フラグの INFINITE_LIFESPAN ビットが設定されていない場合にのみ返されます。

LastUsed

Long

(任意) サーバーでエントリーが最後にアクセスされたときのタイムスタンプを表す Long。この値は、フラグの INFINITE_MAXIDLE ビットが設定されていない場合にのみ返されます。

MaxIdle

vInt

(任意) 秒単位でエントリーの maxIdle を表すvInt 。この値は、フラグの INFINITE_MAXIDLE ビットが設定されていない場合にのみ返されます。

Entry Version

8 バイト

既存のエントリー変更の一意な値。Metadata フラグが設定されている場合のみ含まれます。

Key Length

vInt

キーの長さ。

Key

バイトアレイ

取得されたキー

Value Length

vInt

値の長さ。

Value

バイトアレイ

取得された値。

エントリーごとに MetadataExpirationCreatedLifespanLastUsedMaxIdleEntry VersionKey LengthKeyValue Length、および Value フィールドが繰り返されます。

16.3.15. Hot Rod の IterationStart 操作

IterationStart 操作の要求形式には以下が含まれます。

表16.34 IterationStart 操作の要求形式

フィールドデータタイプ説明

Segments size

signed vInt

イテレーションを行うセグメント ID のビットセットエンコーディングのサイズ。サイズは、最も近い 8 の倍数に切り上げまたは切り捨てされた最大セグメント ID になります。-1 の値はセグメントのフィルターが実行されないことを示します。

Segments

バイトアレイ

(任意) ビットセットがエンコードされた セグメント ID が含まれ、1 が値の各ビットはセットのセグメントを表します。バイトの順番はリトルエンディアン (little endian) です。たとえば、セグメント [1,3,12,13] は以下のエンコーディングになります。

00001010 00110000
size: 16 bits
first byte: represents segments from 0 to 7, from which 1 and 3 are set
second byte: represents segments from 8 to 15, from which 12 and 13 are set

詳細は java.util.BitSet 実装を参照してください。前のフィールドが負の値でない場合、セグメントは送信されます。

FilterConverter size

signed vInt

サーバーにデプロイされた KeyValueFilterConverter ファクトリー名を表す String のサイズ、またはフィルターが使用されない場合は -1。

FilterConverter

UTF-8 バイトアレイ

(任意) サーバーにデプロイされた KeyValueFilterConverter ファクトリー名。前のフィールドが負の値でない場合に含まれます。

Parameters size

バイト

フィルターのパラメーター数。FilterConverter が提供される場合のみ含まれます。

Parameters

byte[][]

パラメーターのアレイ。各パラメーターがバイトアレイになります。Parameters サイズが 0 よりも大きい場合のみ含まれます。

BatchSize

vInt

一度にサーバーから転送するエントリーの数。

Metadata

1 バイト

各エントリーに対してメタデータを返す場合は 1。その他の場合は 0。

この操作の応答ヘッダーには以下のものが含まれます。

表16.35 IterationEnd 操作の応答形式

フィールドデータタイプ説明

IterationId

String

イテレーションの一意な ID。

16.3.16. Hot Rod の Ping 操作

ping は、サーバーの可用性を確認するアプリケーションレベルの要求です。

この操作に有効な応答ステータスは以下のとおりです。

表16.36 ping 操作の応答

Response Status説明

0x00

エラーなしの正常な ping。

16.3.17. Hot Rod の Put 操作

put 操作の要求形式には以下が含まれます。

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

-

キーの長さを含みます。

Key

バイトアレイ

キーの値を含みます。

TimeUnits

バイト

lifespan (最初の 4 ビット) および maxIdle (最後の 4 ビット) の時間単位。デフォルトのサーバー期限切れには DEFAULT、期限切れのない場合は INFINITE を使用できます。可能な値は次のとおりです。

0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE

Lifespan

vInt

エントリーが存続できる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Max Idle

vInt

各エントリーがキャッシュからエビクトされる前に、アイドル状態でいられる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

要求された値。

以下は、この操作から返される有効な応答値です。

Response Status説明

0x00

値が正常に格納されました。

0x03

値が正常に格納され、以前の値が続きます。

この操作では空の応答がデフォルト応答になります。ただし、ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。

16.3.18. Hot Rod の PutAll 操作

すべてのキーバリューエントリーを同時にキャッシュに置く一括操作。

PutAll 操作の要求形式には以下が含まれます。

表16.37 PutAll 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

TimeUnits

バイト

lifespan (最初の 4 ビット) および maxIdle (最後の 4 ビット) の時間単位。デフォルトのサーバー期限切れには DEFAULT、期限切れのない場合は INFINITE を使用できます。可能な値は次のとおりです。

0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE

Lifespan

vInt

エントリーが存続できる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Max Idle

vInt

各エントリーがキャッシュからエビクトされる前に、アイドル状態でいられる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Entry count

vInt

挿入されたエントリーの数。

Key Length

vInt

キーの長さ。

Key

バイトアレイ

取得されたキー

Value Length

vInt

値の長さ。

Value

バイトアレイ

取得された値。

Key LengthKeyValue Length、および Value フィールドは、置かれたエントリーごとに繰り返されます。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.38 PutAll 操作の応答形式

Response Status説明

0x00

操作に成功し、すべてのキーが正常に置かれたことを示します。

16.3.19. Hot Rod の PutIfAbsent 操作

PutIfAbsent 操作の要求形式には以下が含まれます。

表16.39 PutIfAbsent 操作の要求フィールド

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さを含みます。

Key

バイトアレイ

キーの値を含みます。

TimeUnits

バイト

lifespan (最初の 4 ビット) および maxIdle (最後の 4 ビット) の時間単位。デフォルトのサーバー期限切れには DEFAULT、期限切れのない場合は INFINITE を使用できます。可能な値は次のとおりです。

0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE

Lifespan

vInt

エントリーが存続できる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Max Idle

vInt

各エントリーがキャッシュからエビクトされる前に、アイドル状態でいられる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

要求された値を含みます。

以下は、この操作から返される有効な応答値です。

Response Status説明

0x00

値が正常に格納されました。

0x01

キーが存在したため値は保存されませんでした。キーの現在の値が返されます。

0x04

キーが存在したため操作に失敗し、応答でその値が続きます。

この操作では空の応答がデフォルト応答になります。ただし、ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。

16.3.20. Hot Rod の Query 操作

Query 操作の要求形式には以下が含まれます。

表16.40 Query 操作の要求フィールド

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Query Length

vInt

Protobuf エンコードされたクエリーオブジェクトの長さ。

Query

バイトアレイ

Protobuf エンコードされたクエリーオブジェクトを含むバイトアレイ。長さは前のフィールドにより指定されます。

以下は、この操作から返される有効な応答値です。

表16.41 Query 操作の応答

Response Statusデータ説明

Header

変数

応答ヘッダー。

Response payload Length

vInt

Protobuf エンコードされた応答オブジェクトの長さ。

Response payload

バイトアレイ

Protobuf エンコードされた応答オブジェクトを含むバイトアレイ。長さは前のフィールドにより指定されます。

Hot Rod の Query 操作の要求および応答タイプは、infinispan-remote-query-client.jar 内にある org/infinispan/query/remote/client/query.proto リソースファイルで定義されます。

16.3.21. Hot Rod の Remove 操作

Hot RodRemove 操作は、以下の要求形式を使用します。

表16.42 Remove 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) であるため、vInt データタイプが使用されます。ただし、Java では単一のアレイサイズを Integer.MAX_VALUE よりも大きくすることはできません。結果として、この vIntInteger.MAX_VALUE の最大サイズに制限されます。

Key

バイトアレイ

キーを含みます (このキーの対応する値が要求されます)。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.43 Remove 操作の応答形式

Response Status説明

0x00

操作が成功。

0x02

キーが存在しない。

0x03

キーが削除され、応答で以前の値または削除された値が続きます。

通常、この操作の応答ヘッダーは空白です。ただし、ForceReturnPreviousValue が渡された場合は、応答ヘッダーに以下のいずれかが含まれます。

  • 以前のキーの値および長さ。
  • キーが存在しないことを示す、値の長さ 0 と応答ステータス 0x02

remove 操作の応答ヘッダーには、提供されたキーの以前の値と、以前の値の長さが含まれます (ForceReturnPreviousValue が渡された場合)。キーが存在しない場合、または以前の値が null の場合、値の長さは 0 です。

16.3.22. Hot Rod の RemoveIfUnmodified 操作

RemoveIfUnmodified 操作の要求形式には以下が含まれます。

表16.44 RemoveIfUnmodified 操作の要求フィールド

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さを含みます。

Key

バイトアレイ

キーの値を含みます。

Entry Version

8 バイト

エントリーのバージョン番号。

以下は、この操作から返される有効な応答値です。

表16.45 RemoveIfUnmodified 操作の応答

Response Status説明

0x00

エントリーは置換または削除されました。

0x01

キーが変更されたため、エントリーの置換または削除に失敗しました。

0x02

キーが存在しない。

0x03

キーが削除され、応答で以前の値または置き換えられた値が続きます。

0x04

キーが変更されたためエントリーの削除に失敗し、応答で変更された値が続きます。

この操作では空の応答がデフォルト応答になります。ただし、ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。

16.3.23. Hot Rod の Replace 操作

replace 操作の要求形式には以下が含まれます。

表16.46 Replace 操作の要求フィールド

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さを含みます。

Key

バイトアレイ

キーの値を含みます。

TimeUnits

バイト

lifespan (最初の 4 ビット) および maxIdle (最後の 4 ビット) の時間単位。デフォルトのサーバー期限切れには DEFAULT、期限切れのない場合は INFINITE を使用できます。可能な値は次のとおりです。

0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE

Lifespan

vInt

エントリーが存続できる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Max Idle

vInt

各エントリーがキャッシュからエビクトされる前に、アイドル状態でいられる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

要求された値を含みます。

以下は、この操作から返される有効な応答値です。

表16.47 Replace 操作の応答

Response Status説明

0x00

値が正常に格納されました。

0x01

キーが存在しないため、値が格納されませんでした。

0x03

値が正常に置換され、応答で以前の値または置き換えられた値が続きます。

この操作では空の応答がデフォルト応答になります。ただし、ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。

16.3.24. Hot Rod の ReplaceIfUnmodified 操作

ReplaceIfUnmodified 操作の要求形式には以下が含まれます。

表16.48 ReplaceIfUnmodified 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Key Length

vInt

キーの長さ。vInt のサイズは最大 5 バイトであり、理論的には Integer.MAX_VALUE よりも大きい数を生成できます。ただし、Java では Integer.MAX_VALUE よりも大きい単一アレイを作成できず、プロトコルにより vInt アレイの長さが Integer.MAX_VALUE に制限されます。

Key

バイトアレイ

値が要求されるキーを含むバイトアレイ。

TimeUnits

バイト

lifespan (最初の 4 ビット) および maxIdle (最後の 4 ビット) の時間単位。デフォルトのサーバー期限切れには DEFAULT、期限切れのない場合は INFINITE を使用できます。可能な値は次のとおりです。

0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE

Lifespan

vInt

エントリーが存続できる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Max Idle

vInt

各エントリーがキャッシュからエビクトされる前に、アイドル状態でいられる期間。TimeUnits が DEFAULT または INFINITE でない場合のみ送信されます。

Entry Version

8 バイト

GetWithVersion 操作により返された値を使用します。

Value Length

vInt

値の長さ。

Value

バイトアレイ

格納する値。

この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。

表16.49 ReplaceIfUnmodified 操作の応答ステータス

Response Status説明

0x00

値が正常に格納されました。

0x01

キーが変更されたため、置換が実行されませんでした。

0x02

キーが存在しないため、置換が実行されませんでした。

0x03

キーは置換され、応答で以前の値または置き換えられた値が続きます。

0x04

キーが変更されたためエントリーの置き換えに失敗し、応答で変更された値が続きます。

以下は、この操作から返される有効な応答値です。

表16.50 ReplaceIfUnmodified 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

Previous value length

vInt

以前の値を強制的に戻すフラグが要求で送信された場合、以前の値の長さが返されます。キーが存在しない場合、値の長さは 0 になります。送信されたフラグがない場合、値の長さは含まれません。

Previous value

バイトアレイ

以前の値を強制的に戻すフラグが要求で送信され、キーが置き換えられた場合、前の値になります。

16.3.25. Hot Rod の ReplaceWithVersion 操作

ReplaceWithVersion 操作の要求形式には以下が含まれます。

注記

RemoteCache API では、Hot Rod の ReplaceWithVersion 操作は ReplaceIfUnmodified 操作を使用します。結果として、これらの 2 つの操作は JBoss Data Grid ではまったく同じになります。

表16.51 ReplaceWithVersion 操作の要求フィールド

フィールドデータタイプ説明

Header

-

-

Key Length

vInt

キーの長さを含みます。

Key

バイトアレイ

キーの値を含みます。

Lifespan

vInt

エントリーが期限切れになるまでの秒数を含みます。秒数が 30 日を超える場合、その値はエントリーライフスパンの UNIX 時間 (つまり、日付 1/1/1970 以降の秒数) として処理されます。値が 0 に設定された場合、エントリーは期限切れになりません。

Max Idle

vInt

キャッシュからエビクトされるまでエントリーがアイドル状態のままになることが許可される秒数を含みます。このエントリーが 0 に設定された場合、エントリーは無期限でアイドル状態のままになることが許可され、max idle 値のため、エビクトされません。

Entry Version

8 バイト

エントリーのバージョン番号。

Value Length

vInt

値の長さを含みます。

Value

バイトアレイ

要求された値を含みます。

以下は、この操作から返される有効な応答値です。

表16.52 ReplaceWithVersion 操作の応答

Response Status説明

0x00

エントリーが置換または削除された場合に返されたステータス。

0x01

キーが変更されたため、エントリーの置換または削除が失敗した場合に、ステータスを返します。

0x02

キーが存在しない場合に、ステータスを返します。

この操作では空の応答がデフォルト応答になります。ただし、ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。

16.3.26. Hot Rod の Stats 操作

この操作は、利用可能なすべての統計の概要を返します。返された各統計に対して、名前と値が文字列形式と UTF-8 形式の両方で返されます。

この操作では、以下の統計がサポートされます。

表16.53 Stats 操作の要求フィールド

Name説明

timeSinceStart

Hot Rod が起動した以降の秒数を含みます。

currentNumberOfEntries

Hot Rod サーバーに現在存在するエントリーの数を含みます。

totalNumberOfEntries

Hot Rod サーバーに格納されたエントリーの合計数を含みます。

stores

put 操作の試行回数を含みます。

retrievals

get 操作の試行回数を含みます。

hits

get ヒット数を含みます。

misses

get 失敗数を含みます。

removeHits

remove ヒット数を含みます。

removeMisses

removal 失敗数を含みます。

globalCurrentNumberOfEntries

Hot Rod クラスター全体における現在のエントリー数。

globalStores

Hot Rod クラスター全体における put 操作の合計数

globalRetrievals

Hot Rod クラスター全体における get 操作の合計数

globalHits

Hot Rod クラスター全体における get ヒット数の合計。

globalMisses

Hot Rod クラスター全体における get 失敗数の合計。

globalRemoveHits

Hot Rod クラスター全体における removal ヒット数の合計。

globalRemoveMisses

Hot Rod クラスター全体における removal 失敗数の合計。

注記

Hot Rod がローカルモードで実行されている場合、global で始まる統計は利用できません。

この操作の応答ヘッダーには以下のものが含まれます。

表16.54 Stats 操作の応答

Nameデータタイプ説明

Header

変数

応答ヘッダー。

Number of Stats

vInt

返された個別統計の数を含みます。

Name Length

vInt

名前付き統計の長さを含みます。

Name

string

統計の名前を含みます。

Value Length

vInt

値の長さを含みます。

Value

string

統計値を含みます。

要求された各統計に対して、値 Name LengthNameValue Length、および Value が繰り返されます。

16.3.27. Hot Rod の Size 操作

Size 操作の要求形式には以下が含まれます。

表16.55 Size 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

この操作の応答ヘッダーには以下のものが含まれます。

表16.56 Size 操作の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

Size

vInt

クラスター化された構成でグローバルに計算されるリモートキャッシュのサイズ。存在する場合はキャッシュストアの内容も考慮されます。

16.4. Hot Rod 操作の値

16.4.1. Hot Rod 操作の値

以下は、要求ヘッダーと対応する応答ヘッダー値の有効な opcode 値のリストです。

表16.57 opcode 要求および応答ヘッダー値

操作要求操作コード応答操作コード

put

0x01

0x02

get

0x03

0x04

putIfAbsent

0x05

0x06

replace

0x07

0x08

replaceIfUnmodified

0x09

0x0A

remove

0x0B

0x0C

removeIfUnmodified

0x0D

0x0E

containsKey

0x0F

0x10

clear

0x13

0x14

stats

0x15

0x16

ping

0x17

0x18

bulkGet

0x19

0x1A

getWithMetadata

0x1B

0x1C

bulkKeysGet

0x1D

0x1E

query

0x1F

0x20

authMechList

0x21

0x22

auth

0x23

0x24

addClientListener

0x25

0x26

removeClientListener

0x27

0x28

size

0x29

0x2A

exec

0x2B

0x2C

putAll

0x2D

0x2E

getAll

0x2F

0x30

iterationStart

0x31

0x32

iterationNext

0x33

0x34

iterationEnd

0x35

0x36

また、応答ヘッダーの opcode 値が 0x50 の場合は、エラー応答を示します。

16.4.2. Magic 値

以下は要求および応答ヘッダー内の Magic フィールドの有効な値のリストです。

表16.58 Magic フィールド値

Value説明

0xA0

キャッシュ要求マーカー。

0xA1

キャッシュ応答マーカー。

16.4.3. Status 値

以下は、応答ヘッダー内の Status フィールドに有効なすべての値を含む表です。

表16.59 Status 値

Value説明

0x00

エラーなし。

0x01

配置、削除、置換なし。

0x02

キーは存在しません。

0x06

成功ステータス、互換性モードが有効です。

0x07

互換性モードの成功ステータスおよび前の値の返信が有効です。

0x08

互換性モードの非実行および前の値の返信が有効です。

0x81

無効なマジック値またはメッセージ ID。

0x82

不明なコマンド。

0x83

不明なバージョン。

0x84

要求解析エラー。

0x85

サーバーエラー。

0x86

コマンドタイムアウト。

16.4.4. Client Intelligence 値

以下は、要求ヘッダー内の Client Intelligence の有効な値のリストです。

表16.60 Client Intelligence フィールド値

Value説明

0x01

クラスターまたはハッシュ情報が必要でない基本的なクライアントを示します。

0x02

トポロジーを認識し、クラスター情報が必要なクラスターを示します。

0x03

ハッシュと配布を認識し、クラスターおよびハッシュ情報が必要なクライアントを示します。

16.4.5. フラグ値

以下は、要求ヘッダー内の有効な flag 値のリストです。

表16.61 フラグフィールド値

Value説明

0x0001

ForceReturnPreviousValue

16.4.6. Hot Rod のエラー処理

表16.62 応答ヘッダーフィールドを使用した Hot Rod エラー処理

フィールドデータタイプ説明

Error Opcode

-

エラー操作コードを含みます。

Error Status Number

-

error opcode に対応するステータス番号を含みます。

Error Message Length

vInt

エラーメッセージの長さを含みます。

Error Message

string

実際のエラーメッセージを含みます。要求の解析エラーが存在したことを示す 0x84 エラーコードが返された場合、このフィールドには、[path]_ Hot Rod_ サーバーでサポートされた最新バージョンが含まれます。

16.5. Hot Rod のリモートイベント

16.5.1. Hot Rod のリモートイベント

クライアントはリモートイベントリスナーを登録して、サーバーで発生するイベントの更新を受信することができます。クライアントリスナーが追加された直後にイベントが生成および送信されるため、リスナーの追加後に発生したすべてのイベントを受け取ることができます。

16.5.2. Hot Rod におけるリモートイベントのクライアントリスナーの追加

リモートイベントのクライアントリスナーを追加するには、以下の要求形式を使用します。

表16.63 Add Client Listener 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Listener ID

バイトアレイ

リスナーの識別子。

Include state

バイト

このバイトが 1 に設定された場合、初めてキャッシュリスナーを追加するとき、またはクラスター化環境でリモートリスナーが登録されたノードに変更があったときに、キャッシュされた状態がリモートクライアントへ返信されます。有効にすると、状態はクライアントへイベントを作成したキャッシュエントリーとして返信されます。0 に設定された場合、リスナーの追加時に状態はクライアントへ返信されず、リスナーが登録されたノードに変更があっても状態を受信しません。

Key/value filter factory name

String

このリスナーと使用されるキーバリューフィルターファクトリーの任意の名前。Hot Rod サーバーで直接イベントがフィルターされるようにし、クライアントに関係ないイベントが送信されないようにするキーバリューフィルターインスタンスを作成するために、このファクトリーが使用されます。使用されるファクトリーがない場合、文字列の長さは 0 になります。

Key/value filter factory parameter count

バイト

フィルターインスタンスの作成時、キーバリューフィルターファクトリーに任意の数のパラメーターを使用できるため、このファクトリーを使用して異なるフィルターインスタンスを動的に作成できます。このカウントフィールドは、ファクトリーへ渡されるパラメーターの数を示します。ファクトリー名を指定しないと、このフィールドはリクエストに含まれません。

Key/value filter factory parameter (per parameter)

バイトアレイ

キーバリューフィルターファクトリーのパラメーター。

Converter factory name

String

このリスナーと使用するコンバーターファクトリーの任意の名前。このファクトリーは、クライアントへ送信されるイベントの内容を変換するために使用されます。使用されるコンバーターがないと、。デフォルトでは生成されたイベントタイプに応じてイベントが明確に定義されます。しかし、イベントに情報を追加する必要がある場合や、イベントのサイズを縮小する必要がある場合があります。このような場合、コンバーターを使用してイベントの内容を変換することができます。コンバーターファクトリー名を指定すると、この処理を行うコンバーターインスタンスが作成されます。ファクトリーが使用されない場合は、文字列の長さが 0 になります。

Converter factory parameter count

バイト

コンバーターインスタンスの作成時、コンバーターファクトリーに任意の数のパラメーターを使用できるため、このファクトリーを使用して異なるコンバーターインスタンスを動的に作成できます。このカウントフィールドは、ファクトリーへ渡されるパラメーターの数を示します。ファクトリー名を指定しないと、このフィールドはリクエストに含まれません。

Converter factory parameter (per parameter)

バイトアレイ

コンバーターファクトリーのパラメーター。

Use raw data

バイト

フィルターまたはコンバーターパラメーターを raw バイナリーにする必要がある場合は 1、その他の場合は 0。

操作の応答形式は次のとおりです。

表16.64 Add Client Listener の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

16.5.3. リモートイベントの Hot Rod リモートクライアントリスナー

以前追加したクライアントリスナーを削除するには、以下の要求形式を使用します。

表16.65 Remove Client Listener 操作の要求形式

フィールドデータタイプ説明

Header

変数

要求ヘッダー

Listener ID

バイトアレイ

リスナーの識別子。

操作の応答形式は次のとおりです。

表16.66 Add Client Listener の応答形式

フィールドデータタイプ説明

Header

変数

応答ヘッダー。

16.5.4. Hot Rod イベントヘッダー

各リモートイベントは以下の形式に準拠するヘッダーを使用します。

表16.67 リモートイベントヘッダー

フィールド名SizeValue

Magic

1 バイト

0xA1 = response

Message ID

vLong

イベントの ID

Opcode

1 バイト

イベントタイプに応答するコード。

0x60 = cache entry created event
0x61 = cache entry modified event
0x62 = cache entry removed event
0x50 = error

Status

1 バイト

応答の状態。可能な値は次のとおりです。

0x00 = No error

Topology Change Marker

1 バイト

新しいトポロジーの送信が必要であるかどうかを決定できるようにするため、イベントは特定の受信トポロジー ID に関連付けられていません。そのため、新しいトポロジーはイベントとともに送信されません。よって、このマーカーはイベントに対して常に 0 の値を持ちます。

16.5.5. Hot Rod の CacheEntryCreated イベント

CacheEntryCreated イベントには以下が含まれます。

表16.68 CacheEntryCreated イベント

フィールド名SizeValue

Header

変数

0x60 操作コードが含まれるイベントヘッダー。

Listener ID

バイトアレイ

このイベントが転送されるリスナー。

Custom Marker

バイト

カスタムイベントマーカー。作成されたイベントは 0 になります。

Command Retried

バイト

再試行されたコマンドによって発生したイベントのマーカー。コマンドが再試行された場合は 1、その他の場合は 0。

Key

バイトアレイ

作成されたキー。

Version

long

作成されたエントリーのバージョン。このバージョン情報を使用して、このキャッシュエントリーで条件付き操作を作成できます。

16.5.6. Hot Rod の CacheEntryModified イベント

CacheEntryModified イベントには以下が含まれます。

表16.69 CacheEntryModified イベント

フィールド名SizeValue

Header

変数

0x61 操作コードが含まれるイベントヘッダー。

Listener ID

バイトアレイ

このイベントが転送されるリスナー。

Custom Marker

バイト

カスタムイベントマーカー。作成されたイベントは 0 になります。

Command Retried

バイト

再試行されたコマンドによって発生したイベントのマーカー。コマンドが再試行された場合は 1、その他の場合は 0。

Key

バイトアレイ

変更されたキー。

Version

long

変更されたエントリーのバージョン。このバージョン情報を使用して、このキャッシュエントリーで条件付き操作を作成できます。

16.5.7. Hot Rod の CacheEntryRemoved イベント

CacheEntryRemoved イベントには以下が含まれます。

表16.70 CacheEntryRemoved イベント

フィールド名SizeValue

Header

変数

0x62 操作コードが含まれるイベントヘッダー。

Listener ID

バイトアレイ

このイベントが転送されるリスナー。

Custom Marker

バイト

カスタムイベントマーカー。作成されたイベントは 0 になります。

Command Retried

バイト

再試行されたコマンドによって発生したイベントのマーカー。コマンドが再試行された場合は 1、その他の場合は 0。

Key

バイトアレイ

削除されたキー。

16.5.8. Hot Rod の Custom イベント

Custom イベントには以下が含まれます。

表16.71 Custom イベント

フィールド名SizeValue

Header

変数

イベント固有の操作コードが含まれるイベントヘッダー

Listener ID

バイトアレイ

このイベントが転送されるリスナー。

Custom Marker

バイト

カスタムイベントマーカー。ユーザーに返す前にイベントデータをアンマーシャルする必要があるカスタムイベントの場合、値は 1 になります。エベントデータをそのままユーザーに返す必要があるカスタムイベントの場合、値は 2 になります。

Event Data

バイトアレイ

カスタムイベントデータ。カスタムマーカーが 1 の場合、バイトはコンバーターによって返されたインスタンスのマーシャルされたバージョンを表します。カスタムマーカーが 2 の場合、コンバーターによって返されたバイトアレイを表します。

16.6. Put 要求の例

以下は、Hot Rod を使用した put 要求例からのコーディングされた要求です。

表16.72 Put 要求の例

バイト01234567

8

0xA0

0x09

0x41

0x01

0x07

0x4D ('M')

0x79 ('y')

0x43 ('C')

16

0x61 ('a')

0x63 ('c')

0x68 ('h')

0x65 ('e')

0x00

0x03

0x00

0x00

24

0x00

0x05

0x48 ('H')

0x65 ('e')

0x6C ('l')

0x6C ('l')

0x6F ('o')

0x00

32

0x00

0x05

0x57 ('W')

0x6F ('o')

0x72 ('r')

0x6C ('l')

0x64 ('d')

-

以下の表には、要求の例に対するすべてのヘッダーフィールドと値が含まれます。

表16.73 要求例のフィールド名と値

フィールド名バイトValue

Magic

0

0xA0

Version

2

0x41

Cache Name Length

4

0x07

Flag

12

0x00

Topology ID

14

0x00

Transaction ID

16

0x00

Key

18-22

'Hello'

Max Idle

24

0x00

Value

26-30

'World'

Message ID

1

0x09

Opcode

3

0x01

Cache Name

5-11

'MyCache'

Client Intelligence

13

0x03

Transaction Type

15

0x00

Key Field Length

17

0x05

Lifespan

23

0x00

Value Field Length

25

0x05

以下は、put 要求の例に対するコーディングされた応答です。

表16.74 put 要求の例のコーディングされた応答

バイト01234567

8

0xA1

0x09

0x01

0x00

0x00

-

-

-

以下の表には、応答の例のヘッダーフィールドと値がすべて含まれます。

表16.75 応答例のフィールド名および値

フィールド名バイトValue

Magic

0

0xA1

Opcode

2

0x01

Topology Change Marker

4

0x00

Message ID

1

0x09

Status

3

0x00

16.7. Hot Rod Java クライアント

16.7.1. Hot Rod Java クライアント

Hot Rod はバイナリーの言語非依存プロトコルです。Java クライアントは、Hot Rod Java Client API を使用して Hot Rod プロトコルを介してサーバーと対話できます。

16.7.2. Hot Rod Java クライアントのダウンロード

JBoss Data Grid Hot Rod Java クライアントをダウンロードするには、次の手順に従ってください。

手順: Hot Rod Java クライアントのダウンロード

  1. https://access.redhat.com のカスタマーポータルにログインします。
  2. ページの上部にある ダウンロード ボタンをクリックします。
  3. 製品のダウンロード ページで Red Hat JBoss Data Grid をクリックします。
  4. Version: ドロップダウンメニューで適切な JBoss Data Grid のバージョンを選択します。
  5. Red Hat JBoss Data Grid 7.2 Hot Rod Java Client エントリーを見つけ、その Download リンクをクリックします。

16.7.3. Hot Rod Java クライアントの設定

Hot Rod Java クライアントは、プログラムを使用したり、設定ファイルまたはプロパティーファイルを外部的に使用したりして設定されます。次の例は、利用可能な Java 対応 API を使用したクライアントインスタンスの作成を示しています。

クライアントインスタンスの作成

org.infinispan.client.hotrod.configuration.ConfigurationBuilder cb
= new org.infinispan.client.hotrod.configuration.ConfigurationBuilder();
cb.tcpNoDelay(true)
  .connectionPool()
      .numTestsPerEvictionRun(3)
      .testOnBorrow(false)
      .testOnReturn(false)
      .testWhileIdle(true)
  .addServer()
      .host("localhost")
      .port(11222);
RemoteCacheManager rmc = new RemoteCacheManager(cb.build());

プロパティーファイルを使用した Hot Rod Java クライアントの設定

Hot Rod Java クライアントを設定するには、クラスパス上の hotrod-client.properties ファイルを編集します。

次の例は、hotrod-client.properties ファイルの内容を示しています。

設定

infinispan.client.hotrod.transport_factory = org.infinispan.client.hotrod.impl.transport.tcp.TcpTransportFactory

infinispan.client.hotrod.server_list = 127.0.0.1:11222

infinispan.client.hotrod.marshaller = org.infinispan.commons.marshall.jboss.GenericJBossMarshaller

infinispan.client.hotrod.async_executor_factory = org.infinispan.client.hotrod.impl.async.DefaultAsyncExecutorFactory

infinispan.client.hotrod.default_executor_factory.pool_size = 1

infinispan.client.hotrod.default_executor_factory.queue_size = 10000

infinispan.client.hotrod.hash_function_impl.1 = org.infinispan.client.hotrod.impl.consistenthash.ConsistentHashV1

infinispan.client.hotrod.tcp_no_delay = true

infinispan.client.hotrod.ping_on_startup = true

infinispan.client.hotrod.request_balancing_strategy = org.infinispan.client.hotrod.impl.transport.tcp.RoundRobinBalancingStrategy

infinispan.client.hotrod.key_size_estimate = 64

infinispan.client.hotrod.value_size_estimate = 512

infinispan.client.hotrod.force_return_values = false

infinispan.client.hotrod.tcp_keep_alive = true

## below is connection pooling config

maxActive=-1

maxTotal = -1

maxIdle = -1

whenExhaustedAction = 1

timeBetweenEvictionRunsMillis=120000

minEvictableIdleTimeMillis=300000

testWhileIdle = true

minIdle = 1

注記

TCPKEEPALIVE 設定は、 例で示された設定プロパティー (infinispan.client.hotrod.tcp_keep_alive = true/false) または org.infinispan.client.hotrod.ConfigurationBuilder.tcpKeepAlive() メソッドを使用したプログラムによって Hot Rod Java クライアントで有効または無効になります。

Red Hat JBoss Data Grid でプロパティーファイルを使用するには、次の 2 つのコンストラクターのいずれかを使用する必要があります。

  1. new RemoteCacheManager(boolean start)
  2. new RemoteCacheManager()

16.7.4. Hot Rod Java クライアントベーシック API

以下のコードは、クライアント API を使用して Hot Rod Java クライアントで Hot Rod サーバーから情報を保存または取得する方法を示しています。この例では、Hot Rod サーバーがデフォルトの場所 localhost:11222にバインドするよう起動されていることを前提とします。

ベーシック API

//API entry point, by default it connects to localhost:11222
        BasicCacheContainer cacheContainer = new RemoteCacheManager();
//obtain a handle to the remote default cache
        BasicCache<String, String> cache = cacheContainer.getCache();
//now add something to the cache and ensure it is there
        cache.put("car", "ferrari");
        assert cache.get("car").equals("ferrari");
//remove the data
        cache.remove("car");
        assert !cache.containsKey("car") : "Value must have been removed!";

RemoteCacheManagerDefaultCacheManager に対応し、両方が BasicCacheContainer を実装します。

この API は、Hot Rod を介したローカルコールからリモートコールへの移行を実現します。これは、DefaultCacheManagerRemoteCacheManager を切り替えることによって行うことができ、共通の BasicCacheContainer インターフェースによって単純化されます。

すべてのキーは、keySet() メソッドを使用してリモートキャッシュから取得できます。リモートキャッシュが分散キャッシュである場合は、サーバーにより Map/Reduce ジョブが開始され、クラスター化されたノードからすべてのキーが取得され、すべてのキーがクライアントに返されます。

キーの数が多い場合は、このメソッドを注意して使用してください。

Set keys = remoteCache.keySet();

16.7.5. Hot Rod Java クライアントバージョン API

データの整合性を確保するために、Hot Rod は各変更を一意に識別するバージョン番号を保存します。getVersioned を使用して、クライアントはキーと現在のバージョンに関連付けられた値を取得できます。

Hot Rod Java クライアントを使用する場合、RemoteCacheManager は、リモートクラスター上の名前付きキャッシュまたはデフォルトのキャッシュにアクセスする RemoteCache インターフェースのインスタンスを提供します。これにより、バージョン API を含む、新しいメソッドを追加する Cache インターフェースが拡張されます。

バージョンメソッドの使用

// To use the versioned API, remote classes are specifically needed
RemoteCacheManager remoteCacheManager = new RemoteCacheManager();
RemoteCache<String, String> remoteCache = remoteCacheManager.getCache();
remoteCache.put("car", "ferrari");
VersionedValue valueBinary = remoteCache.getWithMetadata("car");
// removal only takes place only if the version has not been changed
// in between. (a new version is associated with 'car' key on each change)
assert remoteCache.removeWithVersion("car", valueBinary.getVersion());
assert !remoteCache.containsKey("car");

置換の使用

remoteCache.put("car", "ferrari");
VersionedValue valueBinary = remoteCache.getWithMetadata("car");
assert remoteCache.replaceWithVersion("car", "lamborghini", valueBinary.getVersion());

16.7.6. Hot Rod Java クライアントでのクラスター全体の動的キャッシュ作成

クライアントからキャッシュを動的に作成する必要がある場合は、次のように createCache() メソッドを使用します。

BasicCache<String, String> cache = client(0).administration().createCache("newCacheName", "newTemplate");

このように作成されたキャッシュはクラスターのすべてのノードで利用可能になりますが、それは一時的です。クラスター全体をシャットダウンし、再起動しても、キャッシュは自動的に再作成されません。キャッシュを永続化するには、PERMANENT フラグを以下のように使用します。

BasicCache<String, String> cache = client(0).administration().withFlags(AdminFlag.PERMANENT).createCache("newCacheName", "newTemplate");

上記は、グローバル状態を有効にし、適切な設定ストレージを選択しないと動作しません。選択可能な設定ストレージは以下のとおりです。

  • VOLATILE: 名前が意味するとおり、この設定ストレージは PERMANENT キャッシュをサポートしません。
  • OVERLAY: caches.xml という名前のファイルのグローバルな共有状態永続パスに設定を保存します。
  • MANAGED: サーバーデプロイメントでのみサポートされ、PERMANENT キャッシュをサーバーモデルに保存します。
  • CUSTOM: カスタムの設定ストア。

16.8. Hot Rod C++ クライアント

16.8.1. Hot Rod C++ クライアント

Hot Rod C++ クライアントを使用すると、C++ ランタイムアプリケーションによる Red Hat JBoss Data Grid リモートサーバーへの接続や対話が可能になり、リモートキャッシュへデータを読み書きできます。Hot Rod C ++ クライアントは 3 つのレベルすべてでクライアントインテリジェンスをサポートし、以下のプラットフォームでサポートされます。

  • Red Hat Enterprise Linux 6、64 ビット
  • Red Hat Enterprise Linux 7、64 ビット

    Hot Rod C++ クライアントは、Visual Studio 2015 がインストールされた 64 ビット Windows ではテクノロジープレビューとして利用できます。

16.8.2. Hot Rod C++ クライアント形式

Hot Rod C++ クライアントは、以下の 2 つのライブラリー形式で利用可能です。

  • 静的ライブラリー
  • 共有/動的ライブラリー

静的ライブラリー

静的ライブラリーはアプリケーションに静的にリンクされます。これにより、最終的な実行可能ファイルのサイズは増加します。アプリケーションは自己完結型であり、別のライブラリーを提供する必要はありません。

共有/動的ライブラリー

共有/動的ライブラリーは、実行時にアプリケーションに動的にリンクされます。ライブラリーは別のファイルに格納され、アプリケーションを再コンパイルせずアプリケーションとは別にアップグレードできます。

注記

これは、ライブラリーのメジャーバージョンがコンパイル時にアプリケーションがリンクされたものと同じである (バイナリー互換性がある) 場合にのみ可能です。

16.8.3. Hot Rod C++ クライアントの前提条件

以下の表は、基盤の OS に応じた Hot Rod C++ クライアントの使用要件の詳細を示しています。

表16.76 Hot Rod C++ クライアントの OS 別の前提条件

オペレーティングシステムHot Rod C++ クライアントの前提条件

RHEL 6、64 ビット

shared_ptr TR1 (GCC 4.0+) をサポートする C++ 03 コンパイラー

RHEL 7、64 ビット

C++ 11 コンパイラー (GCC 4.8.1)

Windows 7 x64

C 11 コンパイラー(Visual Studio 2015、x64 プラットフォーム用 Microsoft Visual C 2013 再頒布可能パッケージ)

16.8.4. Hot Rod C++ クライアントのインストール

16.8.4.1. Hot Rod C++ クライアントのダウンロードおよびインストール

Hot Rod C++ クライアントは、クライアントが使用されるオペレーティングシステムを基に 2 つのファイルタイプで配布されます。

  • RPM ディストリビューションによる RHEL サーバーのインストール
  • zip による Windows サーバーのインストール

16.8.4.2. RHEL における Hot Rod C++ クライアントのダウンロードおよびインストール

以下の手順にしたがってクライアントをインストールします。

  1. Red Hat Subscription Manager を使用して Red Hat Enterprise Linux (RHEL) システムがアカウントに登録されている必要があります。詳細は Red Hat Subscription Management のドキュメント を参照してください。
  2. Red Hat Subscription Manager を使用して、RHEL のバージョンに応じて適切なリポジトリーを有効にします。

    表16.77 RHSM リポジトリー

    RHEL バージョンリポジトリー名

    RHEL 6

    jb-datagrid-7.2-for-rhel-6-server-rpms

    RHEL 7

    jb-datagrid-7.2-for-rhel-7-server-rpms

    たとえば、RHEL 7 リポジトリーを有効にするには、以下のコマンドを使用できます。

    subscription-manager repos --enable=jb-datagrid-7.2-for-rhel-7-server-rpms

    RHEL 7 では、rhel-7-server-optional-rpms リポジトリーも有効にする必要があります。このリポジトリーは必要な protobuf-devel および protobuf-static RPM を提供します。

    subscription-manager repos --enable=rhel-7-server-optional-rpms
  3. 適切なリポジトリーが追加されたら、以下を実行して C++ クライアント RPM をインストールできます。

    yum install jdg-cpp-client

16.8.4.3. Windows における Hot Rod C++ クライアントのダウンロードおよびインストール

Windows の Hot Rod C++ は、Red Hat カスタマーポータル (https://access.redhat.com) の Red Hat JBoss Data Grid バイナリーにある jboss-datagrid-<version>-hotrod-cpp-WIN-x86_64.zip という個別の zip ファイルに含まれています。

この zip ファイルをダウンロードした後、システム上の任意の場所に展開すると C++ クライアントをインストールできます。

16.8.5. Hot Rod C++ クライアントでの Protobuf コンパイラーの使用

16.8.5.1. RHEL 7 における Protobuf コンパイラーの使用

RHEL 7 の C++ Hot Rod クライアントチャンネルには Protobuf コンパイラーが含まれています。このコンパイラーを使用するには、以下の手順にしたがいます。

  1. RHEL における Hot Rod C++ クライアントのダウンロードおよびインストール」の説明どおりに、C++ チャンネルが RHEL システムに追加されている必要があります。
  2. protobuf rpm をインストールします。

    yum install protobuf
  3. 含まれている protobuf ライブラリーをライブラリーのパスに追加します。これらのライブラリーはデフォルトでは /opt/lib64 に含まれています。

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/lib64
  4. 必要な protobuf ファイルを C++ ヘッダーおよびソースファイルにコンパイルします。

    /bin/protoc --cpp_out dllexport_decl=HR_PROTO_EXPORT:/path/to/output/ $FILE
    注記

    HR_PROTO_EXOPRT は Hot Rod クライアントコード内でマクロ定義され、ファイルが続いてコンパイルされたときに拡張されます。

  5. 結果となるヘッダーとソースファイルは指定の出力ディレクトリーに生成され、特定のアプリケーションコードで通常どおりに参照およびコンパイルされます。

Protobuf の詳細は「Protobuf エンコーディング」を参照してください。

16.8.5.2. Windows における Protobuf コンパイラーの使用

Windows 用の C++ Hot Rod クライアントには、事前コンパイルされた Hot Rod コンポーネントと Protobuf コンパイラーが含まれます。多くの場合で、含まれるコンポーネントは追加のコンパイルなしで使用されますが、.proto ファイルにコンパイルが必要な場合は以下の手順にしたがいます。

  1. jboss-datagrid-<version>-hotrod-cpp-client-WIN-x86_64.zip をローカルのファイルシステムに展開します。
  2. コマンドプロンプトを開き、展開されたディレクトリーに移動します。
  3. 必要な protobuf ファイルを C++ ヘッダーおよびソースファイルにコンパイルします。

    bin\protoc --cpp_out dllexport_decl=HR_PROTO_EXPORT:path\to\output\ $FILE
    注記

    HR_PROTO_EXOPRT は Hot Rod クライアントコード内でマクロ定義され、ファイルが続いてコンパイルされたときに拡張されます。

  4. 結果となるヘッダーとソースファイルは指定の出力ディレクトリーに生成され、特定のアプリケーションコードで通常どおりに参照およびコンパイルされます。

Protobuf の詳細は「Protobuf エンコーディング」を参照してください。

16.8.6. Hot Rod C++ クライアントの設定

Hot Rod C++ クライアントは RemoteCache API を使用してリモートの Hot Rod サーバーと対話します。特定の Hot Rod サーバーとの通信を開始するために、RemoteCache を設定し、Hot Rod サーバーの特定のキャッシュを選択します。

ConfigurationBuilder API を使用して以下を設定します。

  • 最初に接続するサーバーのセット。
  • 接続プール属性。
  • 接続/ソケットタイムアウトおよび TCP nodelay。
  • Hot Rod プロトコルバージョン。

C++ の主な実行可能ファイルの設定例

以下の例は、ConfigurationBuilder を使用して RemoteCacheManager を設定する方法とデフォルトのリモートキャッシュを取得する方法を示しています。

SimpleMain.cpp

#include "infinispan/hotrod/ConfigurationBuilder.h"
#include "infinispan/hotrod/RemoteCacheManager.h"
#include "infinispan/hotrod/RemoteCache.h"
#include <stdlib.h>
using namespace infinispan::hotrod;
int main(int argc, char** argv) {
    ConfigurationBuilder b;
    b.addServer().host("127.0.0.1").port(11222);
    RemoteCacheManager cm(builder.build());
    RemoteCache<std::string, std::string> cache = cm.getCache<std::string, std::string>();
    return 0;
}

16.8.7. Hot Rod C++ クライアント API

RemoteCacheManager は、RemoteCache への参照を取得する開始点です。RemoteCache API は、リモート Hot Rod サーバーとサーバー上の特定のキャッシュと対話できます。

前の例で取得した RemoteCache 参照を使用すると、リモートキャッシュで値を挿入、取得、置換、および削除できます。また、すべてのキーの取得やキャッシュのクリアなどの一括操作を実行することもできます。

RemoteCacheManager が停止されると、使用中のすべてのリソースが解放されます。

SimpleMain.cpp

RemoteCache<std::string, std::string> rc = cm.getCache<std::string, std::string>();
    std::string k1("key13");
    std::string v1("boron");
    // put
    rc.put(k1, v1);
    std::auto_ptr<std::string> rv(rc.get(k1));
    rc.putIfAbsent(k1, v1);
    std::auto_ptr<std::string> rv2(rc.get(k1));
    std::map<HR_SHARED_PTR<std::string>,HR_SHARED_PTR<std::string> > map = rc.getBulk(0);
    std::cout << "getBulk size" << map.size() << std::endl;
    ..
    .
    cm.stop();

16.8.8. Hot Rod C++ クライアント非同期 API

Hot Rod C++ クライアントは多くの同期メソッドの非同期のバージョンを提供し、リモートキャッシュと対話するための非ブロッキングメソッドを実現します。

非同期メソッドは同期メソッドと同じ命名規則にしたがいますが、各メソッドの末尾に Async が追加されます。非同期メソッドは操作の結果が含まれる std::future を返します。メソッドが std::string を返す場合は、代わりに std::future < std::string* > を返します。

以下に非同期メソッドのリストを示します。

  • clearAsync
  • getAsync
  • putAsync
  • putAllAsync
  • putIfAbsentAsync
  • removeAsync
  • removeWithVersionAsync
  • replaceAsync
  • replaceWithVersionAsync

Hot Rod C++ 非同期 API の例

以下の例ではこれらのメソッドが使用されます。

#include "infinispan/hotrod/ConfigurationBuilder.h"
#include "infinispan/hotrod/RemoteCacheManager.h"
#include "infinispan/hotrod/RemoteCache.h"
#include "infinispan/hotrod/Version.h"

#include "infinispan/hotrod/JBasicMarshaller.h"
#include <iostream>
#include <thread>
#include <future>

using namespace infinispan::hotrod;

int main(int argc, char** argv) {
    ConfigurationBuilder builder;
    builder.addServer().host(argc > 1 ? argv[1] : "127.0.0.1").port(argc > 2 ? atoi(argv[2]) : 11222).protocolVersion(Configuration::PROTOCOL_VERSION_24);
    RemoteCacheManager cacheManager(builder.build(), false);
    auto *km = new BasicMarshaller<std::string>();
    auto *vm = new BasicMarshaller<std::string>();
    auto cache = cacheManager.getCache<std::string, std::string>(km, &Marshaller<std::string>::destroy, vm, &Marshaller<std::string>::destroy );
    cacheManager.start();
    std::string ak1("asyncK1");
    std::string av1("asyncV1");
    std::string ak2("asyncK2");
    std::string av2("asyncV2");
    cache.clear();

    // Put ak1,av1 in async thread
    std::future<std::string*> future_put= cache.putAsync(ak1,av1);
    // Get the value in this thread
    std::string* arv1= cache.get(ak1);

    // Now wait for put completion
    future_put.wait();

    // All is synch now
    std::string* arv11= cache.get(ak1);
    if (!arv11 || arv11->compare(av1))
    {
        std::cout << "fail: expected " << av1 << "got " << (arv11 ? *arv11 : "null") << std::endl;
        return 1;
    }

    // Read ak1 again, but in async way and test that the result is the same
    std::future<std::string*> future_ga= cache.getAsync(ak1);
    std::string* arv2= future_ga.get();
    if (!arv2 || arv2->compare(av1))
    {
        std::cerr << "fail: expected " << av1 << " got " << (arv2 ? *arv2 : "null") << std::endl;
        return 1;
    }

    // Now user pass a simple lambda func that set a flag to true when the put completes
    bool flag=false;
    std::future<std::string*> future_put1= cache.putAsync(ak2,av2,0,0,[&] (std::string *v){flag=true; return v;});
    // The put is not completed here so flag must be false
    if (flag)
    {
        std::cerr << "fail: expected false got true" << std::endl;
        return 1;
    }
    // Now wait for put completion
    future_put1.wait();
    // The user lambda must be executed so flag must be true
    if (!flag)
    {
        std::cerr << "fail: expected true got false" << std::endl;
        return 1;
    }

    // Same test for get
    flag=false;
    // Now user pass a simple lambda func that set a flag to true when the put completes
    std::future<std::string*> future_get1= cache.getAsync(ak2,[&] (std::string *v){flag=true; return v;});
    // The get is not completed here so flag must be false
    if (flag)
    {
        std::cerr << "fail: expected false got true" << std::endl;
        return 1;
    }
    // Now wait for get completion
    future_get1.wait();
    if (!flag)
    {
        std::cerr << "fail: expected true got false" << std::endl;
        return 1;
    }
    std::string* arv3= future_get1.get();
    if (!arv3 || arv3->compare(av2))
    {
        std::cerr << "fail: expected " << av2 << " got " << (arv3 ? *arv3 : "null") << std::endl;
        return 1;
    }
    cacheManager.stop();
}

16.8.9. Hot Rod C++ クライアントのリモートイベントリスナー

The Hot Rod C++ クライアントはリモートキャッシュリスナーをサポートします。これらのリスナーを追加するには ClientCacheListeneradd_listener 関数を使用します。

重要

リモートイベントリスナーは、Red Hat JBoss Data Grid 7.2 の Hot Rod C++ クライアントではテクノロジープレビューの機能となります。

この関数は各イベントタイプ (createmodifyremoveexpire、または custom) のリスナーを取ります。リモートイベントリスナーの詳細は「リモートイベントリスナー (Hot Rod)」を参照してください。例を以下に示します。

ConfigurationBuilder builder;
    builder.balancingStrategyProducer(nullptr);
builder.addServer().host("127.0.0.1").port(11222);
builder.protocolVersion(Configuration::PROTOCOL_VERSION_24);
RemoteCacheManager cacheManager(builder.build(), false);
cacheManager.start();
JBasicMarshaller<int> *km = new JBasicMarshaller<int>();
JBasicMarshaller<std::string> *vm = new JBasicMarshaller<std::string>();
RemoteCache<int, std::string> cache = cacheManager.getCache<int, std::string>(km,
    &Marshaller<int>::destroy,
    vm,
    &Marshaller<std::string>::destroy);
cache.clear();
std::vector<std::vector<char> > filterFactoryParams;
std::vector<std::vector<char> > converterFactoryParams;
CacheClientListener<int, std::string> cl(cache);
int createdCount=0, modifiedCount=0, removedCount=0, expiredCount=0;

// We're using future and promise to have a basic listeners/main thread synch
int setFutureEventKey=0;
std::promise<void> promise;
std::function<void(ClientCacheEntryCreatedEvent<int>)> listenerCreated = [&createdCount, &setFutureEventKey, &promise](ClientCacheEntryCreatedEvent<int> e) { createdCount++; if (setFutureEventKey==e.getKey()) promise.set_value(); };
std::function<void(ClientCacheEntryModifiedEvent<int>)> listenerModified = [&modifiedCount, &setFutureEventKey, &promise](ClientCacheEntryModifiedEvent <int> e) { modifiedCount++; if (setFutureEventKey==e.getKey()) promise.set_value(); };
std::function<void(ClientCacheEntryRemovedEvent<int>)> listenerRemoved = [&removedCount, &setFutureEventKey, &promise](ClientCacheEntryRemovedEvent <int> e) { removedCount++; if (setFutureEventKey==e.getKey()) promise.set_value(); };
std::function<void(ClientCacheEntryExpiredEvent<int>)> listenerExpired = [&expiredCount, &setFutureEventKey, &promise](ClientCacheEntryExpiredEvent <int> e) { expiredCount++; if (setFutureEventKey==e.getKey()) promise.set_value(); };

cl.add_listener(listenerCreated);
cl.add_listener(listenerModified);
cl.add_listener(listenerRemoved);
cl.add_listener(listenerExpired);

cache.addClientListener(cl, filterFactoryParams, converterFactoryParams);

16.8.10. サイトと動作する Hot Rod C++ クライアント

複数の Red Hat JBoss Data Grid サーバークラスターをデプロイし、各クラスターが異なるサイトに属するようにすることができます。このようなデプロイメントは、あるクラスターから別のクラスター (地理的に異なる場所にある可能性がある) にデータをバックアップできるようにするために行われます。C++ クライアント実装はクラスター内のノードの間でフェイルオーバーでき、元のクラスターが応答しなくなった場合は全体を他のクラスターにフェイルオーバーできます。クラスター間でのフェイルオーバーを可能にするには、すべての Red Hat JBoss Data Grid サーバーがクロスデータセンターレプリケーションで設定されている必要があります。この手順は、Red Hat JBoss Data Grid の『Administration and Configuration Guide』を参照してください。

フェイルオーバーが発生した場合、クライアントの代替クラスターへの接続は、例外が発生して代替クラスターが利用できなくなるまで維持されます。元のクラスターが操作可能になっても、クライアントは接続を自動的に切り替えません。元のクラスターに接続を切り替える場合は、以下の switchToDefaultCluster() メソッドを使用します。

クロスデータセンターレプリケーションがサーバー上で設定されたら、クライアントは代替クラスターの設定を提供し、設定した各クラスターに対して 1 つ以上のホスト/ポートペアの詳細情報を指定する必要があります。以下に例を示します。

#include "infinispan/hotrod/ConfigurationBuilder.h"
#include "infinispan/hotrod/RemoteCacheManager.h"
#include "infinispan/hotrod/RemoteCache.h"
#include <stdlib.h>
using namespace infinispan::hotrod;
int main(int argc, char** argv) {
    ConfigurationBuilder b;
    b.addServer().host("127.0.0.1").port(11222);
    b.addCluster("nyc").addClusterNode("127.0.0.1", 11322);

    RemoteCacheManager cm(builder.build());
    RemoteCache<std::string, std::string> cache = cm.getCache<std::string, std::string>();
    return 0;
}

16.8.10.1. 手動クラスター切り替え

自動サイトフェイルオーバーの他にも、C++ クライアントは以下のメソッドのいずれかを呼び出してクラスターの切り替えを行うことができます。

  • switchToCluster(clusterName) - クライアントを事前定義されたクラスター名に強制的に切り替えます。
  • switchToDefaultCluster - クライアントをクライアント設定で定義された最初のサーバーに強制的に切り替えます。

16.8.11. Hot Rod C++ クライアントを用いたリモートクエリーの実行

Protobuf マーシャラーで RemoteCacheManager が設定された後、Hot Rod C++ クライアントでは Google の Protocol Buffers を使用してリモートクエリーを実行できます。

重要

リモートクエリーの実行は、Red Hat JBoss Data Grid 7.2 の Hot Rod C++ クライアントではテクノロジープレビューの機能となります。

Hot Rod C++ クライアントでのリモートクエリーの有効化

  1. リモートの Red Hat JBoss Data Grid サーバーへの接続を取得します。

    #include "addressbook.pb.h"
    #include "bank.pb.h"
    #include <infinispan/hotrod/BasicTypesProtoStreamMarshaller.h>
    #include <infinispan/hotrod/ProtoStreamMarshaller.h>
    #include "infinispan/hotrod/ConfigurationBuilder.h"
    #include "infinispan/hotrod/RemoteCacheManager.h"
    #include "infinispan/hotrod/RemoteCache.h"
    #include "infinispan/hotrod/Version.h"
    #include "infinispan/hotrod/query.pb.h"
    #include "infinispan/hotrod/QueryUtils.h"
    #include <vector>
    #include <tuple>
    
    #define PROTOBUF_METADATA_CACHE_NAME "___protobuf_metadata"
    #define ERRORS_KEY_SUFFIX  ".errors"
    
    using namespace infinispan::hotrod;
    using namespace org::infinispan::query::remote::client;
    
    std::string read(std::string file)
    {
      std::ifstream t(file);
      std::stringstream buffer;
      buffer << t.rdbuf();
      return buffer.str();
    }
    
    int main(int argc, char** argv) {
      std::cout << "Tests for Query" << std::endl;
        ConfigurationBuilder builder;
        builder.addServer().host(argc > 1 ? argv[1] : "127.0.0.1").port(argc > 2 ? atoi(argv[2]) : 11222).protocolVersion(Configuration::PROTOCOL_VERSION_24);
        RemoteCacheManager cacheManager(builder.build(), false);
        cacheManager.start();
  2. Protobuf マーシャラーで Protobuf メタデータキャッシュを作成します。

        // This example continues the previous codeblock
        // Create the Protobuf Metadata cache peer with a Protobuf marshaller
        auto *km = new BasicTypesProtoStreamMarshaller<std::string>();
        auto *vm = new BasicTypesProtoStreamMarshaller<std::string>();
        auto metadataCache = cacheManager.getCache<std::string, std::string>(
            km, &Marshaller<std::string>::destroy,
            vm, &Marshaller<std::string>::destroy,PROTOBUF_METADATA_CACHE_NAME, false);
  3. データモデルを Protobuf メタデータキャッシュにインストールします。

        // This example continues the previous codeblock
        // Install the data model into the Protobuf metadata cache
        metadataCache.put("sample_bank_account/bank.proto", read("proto/bank.proto"));
        if (metadataCache.containsKey(ERRORS_KEY_SUFFIX))
        {
            std::cerr << "fail: error in registering .proto model" << std::endl;
            return -1;
        }
  4. このステップは、この実証の目的でデータをキャッシュに追加します。リモートキャッシュを単にクエリーする場合、これは無視されることがあります。

        // This example continues the previous codeblock
        // Fill the cache with the application data: two users Tom and Jerry
        testCache.clear();
        sample_bank_account::User_Address a;
        sample_bank_account::User user1;
        user1.set_id(3);
        user1.set_name("Tom");
        user1.set_surname("Cat");
        user1.set_gender(sample_bank_account::User_Gender_MALE);
        sample_bank_account::User_Address * addr= user1.add_addresses();
        addr->set_street("Via Roma");
        addr->set_number(3);
        addr->set_postcode("202020");
        testCache.put(3, user1);
        user1.set_id(4);
        user1.set_name("Jerry");
        user1.set_surname("Mouse");
        addr->set_street("Via Milano");
        user1.set_gender(sample_bank_account::User_Gender_MALE);
        testCache.put(4, user1);
  5. リモートキャッシュをクエリーします。

        // This example continues the previous codeblock
        // Simple query to get User objects
        {
            QueryRequest qr;
            std::cout << "Query: from sample_bank_account.User" << std::endl;
            qr.set_jpqlstring("from sample_bank_account.User");
            QueryResponse resp = testCache.query(qr);
            std::vector<sample_bank_account::User> res;
            unwrapResults(resp, res);
            for (auto i : res) {
                std::cout << "User(id=" << i.id() << ",name=" << i.name()
                << ",surname=" << i.surname() << ")" << std::endl;
            }
        }
        cacheManager.stop();
        return 0;
    }

その他のクエリー例

以下の例は、より複雑なクエリーを示すために含まれています。上記の手順の同じデータセットで使用することができます。

条件を用いたクエリーの使用

// Simple query to get User objects with where condition
{
    QueryRequest qr;
    std::cout << "from sample_bank_account.User u where u.addresses.street=\"Via Milano\"" << std::endl;
    qr.set_jpqlstring("from sample_bank_account.User u where u.addresses.street=\"Via Milano\"");
    QueryResponse resp = testCache.query(qr);
    std::vector<sample_bank_account::User> res;
    unwrapResults(resp, res);
    for (auto i : res) {
        std::cout << "User(id=" << i.id() << ",name=" << i.name()
        << ",surname=" << i.surname() << ")" << std::endl;
    }
}

射影を用いたクエリーの使用

// Simple query to get projection (name, surname)
{
    QueryRequest qr;
    std::cout << "Query: select u.name, u.surname from sample_bank_account.User u" << std::endl;
    qr.set_jpqlstring(
        "select u.name, u.surname from sample_bank_account.User u");
    QueryResponse resp = testCache.query(qr);

    //Typed resultset
    std::vector<std::tuple<std::string, std::string> > prjRes;
    unwrapProjection(resp, prjRes);
    for (auto i : prjRes) {
        std::cout << "Name: " << std::get<0> (i)
        << " Surname: " << std::get<1> (i) << std::endl;
    }
}

16.8.12. Hot Rod C++ クライアントでのニアキャッシュの使用

ニアキャッシュは Hot Rod C++ クライアントの任意のキャッシュで、ユーザーの近くに最近アクセスされたデータを保持することで、頻繁に使用されるデータへのアクセスをより迅速にします。このキャッシュは、バックグラウンドでリモートサーバーに同期されたローカルの Hot Rod クライアントキャッシュとして動作します。

ニアキャッシュをプログラムを使用して ConfigurationBuilder で有効にするには、以下の例のように nearCache() メソッドを使用します。

int main(int argc, char** argv) {
    ConfigurationBuilder confBuilder;
    confBuilder.addServer().host("127.0.0.1").port(11222);
    confBuilder.protocolVersion(Configuration::PROTOCOL_VERSION_24);
    confBuilder.balancingStrategyProducer(nullptr);

    // Enable the near cache support
    confBuilder.nearCache().mode(NearCacheMode::INVALIDATED).maxEntries(4);

ニアキャッシュの動作の設定には、以下のメソッドが使用されます。

  • nearCache() - さらに変更を追加できる NearCacheConfigurationBuilder を定義します。
  • mode(NearCacheMode mode) - NearCacheMode を渡す必要があります。デフォルトは DISABLED で、ニアキャッシュはすべて無効になります。
  • maxEntries(int maxEntries) - ニヤキャッシュに含まれるエントリーの最大数を示します。ニアキャッシュが満杯になると、最も古いエントリーがエビクトされます。この値を 0 に設定すると、バインドされないニアキャッシュが定義されます。

ニアキャッシュのエントリーは、イベントを介してリモートキャッシュとのアライメントを維持します。サーバーで変更が発生すると、適切なイベントがクライアントへ送信され、ニアキャッシュを更新します。

16.8.13. Hot Rod C++ クライアントを使用したスクリプトの実行

Hot Rod C++ クライアントを使用すると、リモート実行を介してタスクを直接 JBoss Data Grid サーバーで実行できます。この機能はデータに近いロジックを実行し、クラスターのノードすべてのリソースを利用します。タスクはサーバーインスタンスにデプロイでき、デプロイ後にプログラムを使用して実行できます。

重要

リモート実行は、Red Hat JBoss Data Grid 7.2 の Hot Rod C++ クライアントではテクノロジープレビューの機能となります。

タスクのインストール

___script_cacheput(std::string name, std::string script) メソッドが使用されると、タスクはサーバーにインストールされます。スクリプト名の拡張はスクリプトの実行に使用されるエンジンを判断しますが、これはスクリプト自体のメタデータによって上書きされます。

以下の例はスクリプトをインストールします。

C++ クライアントでのタスクのインストール

#include "infinispan/hotrod/ConfigurationBuilder.h"
#include "infinispan/hotrod/RemoteCacheManager.h"
#include "infinispan/hotrod/RemoteCache.h"
#include "infinispan/hotrod/Version.h"
#include "infinispan/hotrod/JBasicMarshaller.h"
using namespace infinispan::hotrod;
int main(int argc, char** argv) {
    // Configure the client
    ConfigurationBuilder builder;
    builder.addServer().host("127.0.0.1").port(11222).protocolVersion(
        Configuration::PROTOCOL_VERSION_24);
    RemoteCacheManager cacheManager(builder.build(), false);
    try {
    // Create the cache with the given marshallers
    auto *km = new JBasicMarshaller<std::string>();
    auto *vm = new JBasicMarshaller<std::string>();
    RemoteCache<std::string, std::string> cache = cacheManager.getCache<
        std::string, std::string>(km, &Marshaller<std::string>::destroy,
        vm, &Marshaller<std::string>::destroy,
        std::string("namedCache"));
    cacheManager.start();

    // Obtain a reference to the ___script_cache
    RemoteCache<std::string, std::string> scriptCache =
        cacheManager.getCache<std::string, std::string>(
        "___script_cache", false);
    // Install on the server the getValue script
    std::string getValueScript(
        "// mode=local,language=javascript\n "
        "var cache = cacheManager.getCache(\"namedCache\");\n "
        "var ct = cache.get(\"accessCounter\");\n "
        "var c = ct==null ? 0 : parseInt(ct);\n "
        "cache.put(\"accessCounter\",(++c).toString());\n "
        "cache.get(\"privateValue\") ");
    std::string getValueScriptName("getValue.js");
    std::string pGetValueScriptName =
        JBasicMarshaller<std::string>::addPreamble(getValueScriptName);
    std::string pGetValueScript =
        JBasicMarshaller<std::string>::addPreamble(getValueScript);
    scriptCache.put(pGetValueScriptName, pGetValueScript);
    // Install on the server the get access counter script
    std::string getAccessScript(
        "// mode=local,language=javascript\n "
        "var cache = cacheManager.getCache(\"namedCache\");\n "
        "cache.get(\"accessCounter\")");
    std::string getAccessScriptName("getAccessCounter.js");
    std::string pGetAccessScriptName =
        JBasicMarshaller<std::string>::addPreamble(getAccessScriptName);
    std::string pGetAccessScript =
        JBasicMarshaller<std::string>::addPreamble(getAccessScript);
    scriptCache.put(pGetAccessScriptName, pGetAccessScript);

タスクの実行

インストール後、タスクは execute(std::string name, std::map<std::string, std::string> args) メソッドを使用して実行されます。このメソッドには、実行するスクリプトの名前と実行に必要な引数を指定します。

以下の例はスクリプトを実行します。

C++ クライアントでのスクリプトの実行

    // The following is a continuation of the above example
    cache.put("privateValue", "Counted Access Value");
    std::map<std::string, std::string> s;
    // Execute the getValue script
    std::vector<unsigned char> execValueResult = cache.execute(
        getValueScriptName, s);
    // Execute the getAccess script
    std::vector<unsigned char> execAccessResult = cache.execute(
        getAccessScriptName, s);

    std::string value(
        JBasicMarshallerHelper::unmarshall<std::string>(
            (char*) execValueResult.data()));
    std::string access(
        JBasicMarshallerHelper::unmarshall<std::string>(
            (char*) execAccessResult.data()));

    std::cout << "Returned value is '" << value
        << "' and has been accessed: " << access << " times."
        << std::endl;

  } catch (const Exception& e) {
  std::cout << "is: " << typeid(e).name() << '\n';
  std::cerr << "fail unexpected exception: " << e.what() << std::endl;
  return 1;
  }

	cacheManager.stop();
	return 0;
}

16.9. Hot Rod C# クライアント

16.9.1. Hot Rod C# クライアント

Hot Rod C# クライアントでは、.NET ランタイムアプリケーションは Red Hat JBoss Data Grid サーバーへ接続し、対話できます。Hot Rod C# クライアントは、クラスタートポロジーとハッシュスキームを認識し、Hot Rod Java クライアントと Hot Rod C++ クライアントに類似した単一のホップでサーバー上のエントリーにアクセスできます。

Hot Rod C# クライアントは、.NET Framework が Microsoft Visual Studio 2015 によりサポートされる 64 ビットのオペレーティングシステムと互換性があります。NET 4.6.2 は Hot Rod C# クライアントに必須です。

16.9.2. Hot Rod C# クライアントのダウンロードとインストール

Hot Rod C# クライアントは、Red Hat JBoss Data Grid でダウンロード用にパッケージされた .msi ファイル jboss-datagrid-<version>-hotrod-dotnet-client.msi に含まれます。Hot Rod C# クライアントをインストールするには、以下の手順を実行してください。

Hot Rod C# クライアントのインストール

  1. 管理者として、Hot Rod C# .msi ファイルがダウンロードされた場所に移動します。.msi ファイルを実行してウィンドウインストーラーを起動し、Next をクリックします。

    図16.1 Hot Rod C# クライアントのセットアップの開始

    Hot Rod C# Client Setup Welcome
  2. 使用許諾契約書の内容を確認します。I accept the terms in the License Agreement (使用許諾契約に同意します) チェックボックスを選択し、Next をクリックします。

    図16.2 Hot Rod C# クライアントの使用許諾契約

    Hot Rod C# Client End-User License Agreement
  3. デフォルトのディレクトリーを変更するには、Change…​ または Next をクリックしてデフォルトのディレクトリーをインストールします。

    図16.3 Hot Rod C# クライアントの宛先フォルダー

    Hot Rod C# Client Destination Folder
  4. Install をクリックして、Hot Rod C# クライアントのインストールを開始します。

    図16.4 Hot Rod C# クライアントのインストールを開始

    Hot Rod C# Client Begin Installation
  5. Finish をクリックして Hot Rod C# クライアントのインストールを完了します。

    図16.5 Hot Rod C# クライアントのセットアップの完了

    Hot Rod C# Client Setup Completion

16.9.3. Hot Rod C# .NET プロジェクトの作成

.NET プロジェクトで Hot Rod C# クライアントを使用するには、以下の手順を実行する必要があります。

Hot Rod C# プロジェクトの設定

  1. Path 環境変数の追加

    PATH 環境変数に以下のフォルダーを追加する必要があります。

    C:\path\to\infinispan-hotrod-dotnet 8.5.0.Final\bin
    C:\path\to\infinispan-hotrod-dotnet 8.5.0.Final\lib
  2. Prefer 32 bit の削除

    Build タブの Project プロパティーにある Prefer 32 bit にチェックマークが入っていないようにしてください。

  3. Hot Rod C# dll の追加

    1. Solution Explorer ビューで Project を選択します。
    2. References を選択します。
    3. 参照を右クリックし、Add Reference を選択します。
    4. 表示されたウインドウで Browse をクリックし、 C:\path\to\infinispan-hotrod-dotnet 8.5.0.Final\lib\hotrodcs.dll ファイルに移動します。
    5. OK をクリックします。

Hot Rod C# API が .NET プロジェクトで使用できるようになりました。

16.9.4. Hot Rod C# クライアントの設定

Hot Rod C# クライアントは ConfigurationBuilder を使用してプログラミングにより設定されます。クライアントが接続する必要があるホストとポートを設定します。

C# ファイルの設定例

以下の例は、ConfigurationBuilder を使用して RemoteCacheManager を設定する方法を示しています。

C# の設定

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Infinispan.HotRod;
using Infinispan.HotRod.Config;
namespace simpleapp
{
    class Program
    {
        static void Main(string[] args)
        {
            ConfigurationBuilder builder = new ConfigurationBuilder();
            builder.AddServer()
                .Host(args.Length > 1 ? args[0] : "127.0.0.1")
                .Port(args.Length > 2 ? int.Parse(args[1]) : 11222);
            Configuration config = builder.Build();
            RemoteCacheManager cacheManager = new RemoteCacheManager(config);
            [...]
        }
    }
}

16.9.5. Hot Rod C# クライアント API

RemoteCacheManagerは、RemoteCache への参照を取得する開始点です。

以下の例は、サーバーからのデフォルトキャッシュの取得と基本的な複数の操作を示しています。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Infinispan.HotRod;
using Infinispan.HotRod.Config;
namespace simpleapp
{
    class Program
    {
        static void Main(string[] args)
        {
            ConfigurationBuilder builder = new ConfigurationBuilder();
            builder.AddServer()
                .Host(args.Length > 1 ? args[0] : "127.0.0.1")
                .Port(args.Length > 2 ? int.Parse(args[1]) : 11222);
            Configuration config = builder.Build();
            RemoteCacheManager cacheManager = new RemoteCacheManager(config);
            cacheManager.Start();
            // Retrieve a reference to the default cache.
            IRemoteCache<String, String> cache = cacheManager.GetCache<String, String>();
            // Add entries.
            cache.Put("key1", "value1");
            cache.PutIfAbsent("key1", "anotherValue1");
            cache.PutIfAbsent("key2", "value2");
            cache.PutIfAbsent("key3", "value3");
            // Retrive entries.
            Console.WriteLine("key1 -> " + cache.Get("key1"));
            // Bulk retrieve key/value pairs.
            int limit = 10;
            IDictionary<String, String> result = cache.GetBulk(limit);
            foreach (KeyValuePair<String, String> kv in result)
            {
                Console.WriteLine(kv.Key + " -> " + kv.Value);
            }
            // Remove entries.
            cache.Remove("key2");
            Console.WriteLine("key2 -> " + cache.Get("key2"));
            cacheManager.Stop();
        }
    }
}

16.9.6. Hot Rod C# クライアント非同期 API

Hot Rod C# クライアントは多くの同期メソッドの非同期のバージョンを提供し、リモートキャッシュと対話するための非ブロッキングメソッドを実現します。

非同期メソッドは同期メソッドと同じ命名規則にしたがいますが、各メソッドの末尾に Async が追加されます。非同期メソッドは操作の結果が含まれる Task を返します。メソッドが String を返す場合は、代わりに Task<String> を返します。

以下に非同期メソッドのリストを示します。

  • ClearAsync
  • GetAsync
  • PutAsync
  • PutAllAsync
  • PutIfAbsentAsync
  • RemoveAsync
  • RemoveWithVersionAsync
  • ReplaceAsync
  • ReplaceWithVersionAsync

Hot Rod C# 非同期 API の例

以下の例ではこれらのメソッドが使用されます。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Infinispan.HotRod;
using Infinispan.HotRod.Config;
namespace simpleapp
{
    class Program
    {
        static void Main(string[] args)
        {
            ConfigurationBuilder builder = new ConfigurationBuilder();
            builder.AddServer()
                .Host(args.Length > 1 ? args[0] : "127.0.0.1")
                .Port(args.Length > 2 ? int.Parse(args[1]) : 11222);
            Configuration config = builder.Build();
            RemoteCacheManager cacheManager = new RemoteCacheManager(config);
            IRemoteCache<String,String> cache = cacheManager.GetCache<String,String>();

            // Add Entries Async
            cache.PutAsync("key1","value1");
            cache.PutAsync("key2","value2");

            // Retrieve Entries Async
            Task<string> futureExec = cache.GetAsync("key1");

            string result = futureExec.Result;
        }
    }
}

16.9.7. Hot Rod C# クライアントのリモートイベントリスナー

The Hot Rod C++ クライアントはリモートキャッシュリスナーをサポートします。これらのリスナーを追加するには ClientListeneraddListener 関数を使用します。

重要

リモートイベントリスナーは、Red Hat JBoss Data Grid 7.2 の Hot Rod C++ クライアントではテクノロジープレビューの機能となります。

このメソッドは各イベントタイプ (createmodifyremoveexpire、または custom) のリスナーを取ります。リモートイベントリスナーの詳細は「リモートイベントリスナー (Hot Rod)」を参照してください。modifiedEvent の例は次のとおりです。

[...]
private static void modifiedEventAction(Event.ClientCacheEntryModifiedEvent<string> e)
{
    ++modifiedEventCounter;
    modifiedSemaphore.Release();
}
[...]
public void ModifiedEventTest()
{
    IRemoteCache<string, string> cache = remoteManager.GetCache<string, string>();
    cache.Clear();
    Event.ClientListener<string, string> cl = new Event.ClientListener<string, string>();
    cl.filterFactoryName = "";
    cl.converterFactoryName = "";
    cl.addListener(modifiedEventAction);
    cache.addClientListener(cl, new string[] { }, new string[] { }, null);
}

16.9.8. サイトと動作する Hot Rod C# クライアント

複数の Red Hat JBoss Data Grid サーバークラスターをデプロイし、各クラスターが異なるサイトに属するようにすることができます。このようなデプロイメントは、あるクラスターから別のクラスター (地理的に異なる場所にある可能性がある) にデータをバックアップできるようにするために行われます。C# クライアント実装はクラスター内のノードの間でフェイルオーバーでき、元のクラスターが応答しなくなった場合は全体を他のクラスターにフェイルオーバーできます。クラスター間でのフェイルオーバーを可能にするには、すべての Red Hat JBoss Data Grid サーバーがクロスデータセンターレプリケーションで設定されている必要があります。この手順は、Red Hat JBoss Data Grid 『Administration and Configuration Guide』を参照してください。

フェイルオーバーが発生した場合、クライアントの代替クラスターへの接続は、例外が発生して代替クラスターが利用できなくなるまで維持されます。元のクラスターが操作可能になっても、クライアントは接続を自動的に切り替えません。元のクラスターに接続を切り替える場合は、以下の SwitchToDefaultCluster() メソッドを使用します。

クロスデータセンターレプリケーションがサーバー上で設定されたら、クライアントは代替クラスターの設定を提供し、設定した各クラスターに対して 1 つ以上のホスト/ポートペアの詳細情報を指定する必要があります。以下に例を示します。

ConfigurationBuilder conf1 = new ConfigurationBuilder();
conf1.AddServer().Host("127.0.0.1").Port(11222);
conf1.AddCluster("nyc").AddClusterNode("127.0.0.1", 11322);
RemoteCacheManager manager1 = new RemoteCacheManager(conf1.Build(), true);

ConfigurationBuilder conf2 = new ConfigurationBuilder();
conf2.AddServer().Host("127.0.0.1").Port(11322);
conf2.AddCluster("lon").AddClusterNode("127.0.0.1", 11222);
RemoteCacheManager remoteManager = new RemoteCacheManager(conf2.Build(), true);

16.9.8.1. 手動クラスター切り替え

自動サイトフェイルオーバーの他にも、C++ クライアントは以下のメソッドのいずれかを呼び出してクラスターの切り替えを行うことができます。

  • SwitchToCluster(clusterName) - クライアントを事前定義されたクラスター名に強制的に切り替えます。
  • SwitchToDefaultCluster() - クライアントをクライアント設定で定義された最初のサーバーに強制的に切り替えます。

16.9.9. Hot Rod C# クライアントを用いたリモートクエリーの実行

Protobuf マーシャラーで RemoteCacheManager が設定された後、Hot Rod C# クライアントでは Google の Protocol Buffers を使用してリモートクエリーを実行できます。

重要

リモートクエリーの実行は、Red Hat JBoss Data Grid 7.2 の Hot Rod C# クライアントではテクノロジープレビューの機能となります。

Hot Rod C# クライアントでのリモートクエリーの有効化

  1. Protobuf マーシャラーを設定に渡し、リモートの Red Hat JBoss Data Grid サーバーへの接続を取得します。

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;
    using Infinispan.HotRod;
    using Infinispan.HotRod.Config;
    using Google.Protobuf;
    using Org.Infinispan.Protostream;
    using Org.Infinispan.Query.Remote.Client;
    using QueryExampleBankAccount;
    using System.IO;
    
    namespace Query
    {
        /// <summary>
        /// This sample code shows how to perform Infinispan queries using the C# client
        /// </summary>
        class Query
        {
            static void Main(string[] args)
            {
                // Cache manager setup
                RemoteCacheManager remoteManager;
                const string ERRORS_KEY_SUFFIX = ".errors";
                const string PROTOBUF_METADATA_CACHE_NAME = "___protobuf_metadata";
                ConfigurationBuilder conf = new ConfigurationBuilder();
                conf.AddServer().Host("127.0.0.1").Port(11222).ConnectionTimeout(90000).SocketTimeout(6000);
                conf.Marshaller(new BasicTypesProtoStreamMarshaller());
                remoteManager = new RemoteCacheManager(conf.Build(), true);
                IRemoteCache<String, String> metadataCache = remoteManager.GetCache<String, String>(PROTOBUF_METADATA_CACHE_NAME);
                IRemoteCache<int, User> testCache = remoteManager.GetCache<int, User>("namedCache");
  2. Protobuf エンティティーモデルをインストールします。

                // This example continues the previous codeblock
                // Installing the entities model into the Infinispan __protobuf_metadata cache
                metadataCache.Put("sample_bank_account/bank.proto", File.ReadAllText("resources/proto2/bank.proto"));
                if (metadataCache.ContainsKey(ERRORS_KEY_SUFFIX))
                {
                    Console.WriteLine("fail: error in registering .proto model");
                    Environment.Exit(-1);
                }
  3. このステップは、この実証の目的でデータをキャッシュに追加します。リモートキャッシュを単にクエリーする場合、これは無視されることがあります。

                // This example continues the previous codeblock
                // The application cache must contain entities only
                testCache.Clear();
                // Fill the application cache
                User user1 = new User();
                user1.Id = 4;
                user1.Name = "Jerry";
                user1.Surname = "Mouse";
                User ret = testCache.Put(4, user1);
  4. リモートキャッシュをクエリーします。

                // This example continues the previous codeblock
                // Run a query
                QueryRequest qr = new QueryRequest();
                qr.JpqlString = "from sample_bank_account.User";
                QueryResponse result = testCache.Query(qr);
                List<User> listOfUsers = new List<User>();
                unwrapResults(result, listOfUsers);
    
            }
  5. 結果を処理するには、protobuf を C# オブジェクトに変換します。以下の例はこの変換を示しています。

            // Convert Protobuf matter into C# objects
            private static bool unwrapResults<T>(QueryResponse resp, List<T> res) where T : IMessage<T>
            {
                if (resp.ProjectionSize > 0)
                {  // Query has select
                    return false;
                }
                for (int i = 0; i < resp.NumResults; i++)
                {
                    WrappedMessage wm = resp.Results.ElementAt(i);
    
                    if (wm.WrappedBytes != null)
                    {
                        WrappedMessage wmr = WrappedMessage.Parser.ParseFrom(wm.WrappedBytes);
                        if (wmr.WrappedMessageBytes != null)
                        {
                            System.Reflection.PropertyInfo pi = typeof(T).GetProperty("Parser");
    
                            MessageParser<T> p = (MessageParser<T>)pi.GetValue(null);
                            T u = p.ParseFrom(wmr.WrappedMessageBytes);
                            res.Add(u);
                        }
                    }
                }
                return true;
            }
        }
    }

16.9.10. Hot Rod C# クライアントでのニアキャッシュの使用

ニアキャッシュは Hot Rod C# クライアントの任意のキャッシュで、ユーザーの近くに最近アクセスされたデータを保持することで、頻繁に使用されるデータへのアクセスをより迅速にします。このキャッシュは、バックグラウンドでリモートサーバーに同期されたローカルの Hot Rod クライアントキャッシュとして動作します。

ニアキャッシュをプログラムを使用して ConfigurationBuilder で有効にするには、以下の例のように NearCache() メソッドを使用します。

ConfigurationBuilder conf = new ConfigurationBuilder();
conf.AddServer().Host("127.0.0.1").Port(11222)

// Define a Near Cache that contains up to 10 entries
.NearCache().Mode(NearCacheMode.INVALIDATED).MaxEntries(10);

ニアキャッシュの動作の設定には、以下のメソッドが使用されます。

  • NearCache() - さらに変更を追加できる NearCacheConfigurationBuilder を定義します。
  • Mode(NearCacheMode mode) - NearCacheMode を渡す必要があります。デフォルトは DISABLED で、ニアキャッシュはすべて無効になります。
  • MaxEntries(int maxEntries) - ニヤキャッシュに含まれるエントリーの最大数を示します。ニアキャッシュが満杯になると、最も古いエントリーがエビクトされます。この値を 0 に設定すると、バインドされないニアキャッシュが定義されます。

ニアキャッシュのエントリーは、イベントを介してリモートキャッシュとのアライメントを維持します。サーバーで変更が発生すると、適切なイベントがクライアントへ送信され、ニアキャッシュを更新します。

16.9.11. Hot Rod C# クライアントを使用したスクリプトの実行

Hot Rod C# クライアントを使用すると、リモート実行を介してタスクを直接 Red Hat JBoss Data Grid サーバーで実行できます。この機能はデータに近いロジックを実行し、クラスターのノードすべてのリソースを利用します。タスクはサーバーインスタンスにデプロイでき、デプロイ後にプログラムを使用して実行できます。

タスクのインストール

___script_cachePut(string name, string script) メソッドが使用されると、タスクはサーバーにインストールされます。スクリプト名の拡張はスクリプトの実行に使用されるエンジンを判断しますが、これはスクリプト自体のメタデータによって上書きされます。

以下の例はスクリプトをインストールします。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Infinispan.HotRod;
using Infinispan.HotRod.Config;

namespace RemoteExec
{
    /// <summary>
    /// This sample code shows how to perform a server remote execution using the C# client
    /// </summary>
    class RemoteExec
    {
        static void Main(string[] args)
        {
            // Cache manager setup
            RemoteCacheManager remoteManager;
            IMarshaller marshaller;
            ConfigurationBuilder conf = new ConfigurationBuilder();
            conf.AddServer().Host("127.0.0.1").Port(11222).ConnectionTimeout(90000).SocketTimeout(6000);
            marshaller = new JBasicMarshaller();
            conf.Marshaller(marshaller);
            remoteManager = new RemoteCacheManager(conf.Build(), true);

            // Install the .js code into the Infinispan __script_cache
            const string SCRIPT_CACHE_NAME = "___script_cache";
            string valueScriptName = "getValue.js";
            string valueScript = "// mode=local,language=javascript\n "
                 + "var cache = cacheManager.getCache(\"namedCache\");\n "
                 + "var ct = cache.get(\"accessCounter\");\n "
                 + "var c = ct==null ? 0 : parseInt(ct);\n "
                 + "cache.put(\"accessCounter\",(++c).toString());\n "
                 + "cache.get(\"privateValue\") ";
            string accessScriptName = "getAccess.js";
            string accessScript = "// mode=local,language=javascript\n "
                + "var cache = cacheManager.getCache(\"namedCache\");\n "
                + "cache.get(\"accessCounter\")";
            IRemoteCache<string, string> scriptCache = remoteManager.GetCache<string, string>(SCRIPT_CACHE_NAME);
            IRemoteCache<string, string> testCache = remoteManager.GetCache<string, string>("namedCache");
            scriptCache.Put(valueScriptName, valueScript);
            scriptCache.Put(accessScriptName, accessScript);

タスクの実行

インストール後、タスクは Execute(string name, Dictionary<string, string> scriptArgs) メソッドを使用して実行されます。このメソッドには、実行するスクリプトの名前と実行に必要な引数を指定します。

以下の例はスクリプトを実行します。

            // This example continues the previous codeblock
            testCache.Put("privateValue", "Counted Access Value");
            Dictionary<string, string> scriptArgs = new Dictionary<string, string>();
            byte[] ret1 = testCache.Execute(valueScriptName, scriptArgs);
            string value = (string)marshaller.ObjectFromByteBuffer(ret1);
            byte[] ret2 = testCache.Execute(accessScriptName, scriptArgs);
            string accessCount = (string)marshaller.ObjectFromByteBuffer(ret2);
            Console.Write("Return value is '" + value + "' and has been accessed '" + accessCount + "' times.");

        }
    }
}
重要

Hot Rod C# クライアントを使用したスクリプトの実行は、JBoss Data Grid 7.2 ではテクノロジープレビューの機能となります。

16.9.12. 相互運用性を維持するための文字列マーシャラー

文字列互換性マーシャラーを使用するには、以下の例のように CompatibilityMarshaller のインスタンスを ConfigurationBuilder オブジェクトの Marshaller() メソッドに渡します。

ConfigurationBuilder builder = new ConfigurationBuilder();
builder.Marshaller(new CompatibilityMarshaller());
RemoteCacheManager cacheManager = new RemoteCacheManager(builder.build(), true);
IRemoteCache<String, String> cache = cacheManager.GetCache<String, String>();
[....]
cache.Put("key", "value");
[...]
cache.Get("key");
[...]
注記

非文字列キー/値を格納または取得しようとすると、HotRodClientException が発生します。

16.10. Hot Rod Node.js クライアント

16.10.1. Hot Rod Node.js クライアント

Hot Rod Node.js クライアントは非同期型のイベント駆動クライアントで、Node.js ユーザーは Red Hat JBoss Data Grid サーバーとの通信が可能です。このクライアントは、スクリプトの実行および格納、キャッシュリスナーの利用、完全なクラスタートポロジーの受信など、Java クライアントの多くの機能をサポートします。

非同期操作の結果は Promise インスタンスで提供されるため、クライアントは簡単に複数の呼び出しをチェーンでき、エラーの処理を一元化できます。

16.10.2. Hot Rod Node.js クライアントのインストール

Hot Rod Node.js クライアントは別のディストリビューションに含まれているため、Red Hat JBoss Data Grid とは別にダウンロードする必要があります。以下の手順にしたがってこのクライアントをインストールします。

手順: Hot Rod Node.js クライアントのインストール

  1. Red Hat カスタマーポータルから jboss-datagrid-7.2.1-nodejs-client.zip をダウンロードします。
  2. ダウンロードしたアーカイブを展開します。
  3. 以下のコマンドのように、npm を使用して tarball をインストールします。

    npm install /path/to/jboss-datagrid-7.2.0-nodejs-client/infinispan-7.2.0-Final-redhat-9.tgz

16.10.3. Hot Rod Node.js の要件

Hot Rod Node.js を使用するには、以下の要件を満たす必要があります。

  • Node.js バージョン 0.10 以上。
  • Red Hat JBoss Data Grid サーバーインスタンス 7.0.0 以上。

16.10.4. Hot Rod Node.js の基本機能

以下の例は Red Hat JBoss Data Grid サーバーに接続し、データの配置や取得などの基本操作を実行する方法を示しています。以下の例では、Red Hat JBoss Data Grid サーバーがデフォルトの localhost:11222 で利用できることを前提としています。

var infinispan = require('infinispan');

// Obtain a connection to the JBoss Data Grid server
// As no cache is specified all operations will occur on the 'default' cache
var connected = infinispan.client({port: 11222, host: '127.0.0.1'});

connected.then(function (client) {

  // Attempt to put a value in the cache.
  var clientPut = client.put('key', 'value');

  // Retrieve the value just placed
  var clientGet = clientPut.then(
      function() { return client.get('key'); });

  // Print out the value that was retrieved
  var showGet = clientGet.then(
      function(value) { console.log('get(key)=' + value); });

  // Disconnect from the server
  return showGet.finally(
      function() { return client.disconnect(); });
}).catch(function(error) {

  // Log any errors received
  console.log("Got error: " + error.message);

});

名前付きキャッシュへの接続

特定のキャッシュに接続するには、以下の例のように Red Hat JBoss Data Grid サーバーインスタンスの場所を指定するときに cacheName 属性を定義します。

var infinispan = require('infinispan');

// Obtain a connection to the JBoss Data Grid server
// and connect to namedCache
var connected = infinispan.client(
  {port: 11222, host: '127.0.0.1'}, {cacheName: 'namedCache'});

connected.then(function (client) {

  // Log the result of the connection
  console.log('Connected to `namedCache`');

  // Disconnect from the server
  return client.disconnect();

}).catch(function(error) {

  // Log any errors received
  console.log("Got error: " + error.message);

});

データセットの使用

putAll および getAll メソッドを使用すると、単一のエントリーだけでなく、データセットを配置または取得できます。この操作の例を以下に示します。

var infinispan = require('infinispan');

// Obtain a connection to the JBoss Data Grid server
// As no cache is specified all operations will occur on the 'default' cache
var connected = infinispan.client({port: 11222, host: '127.0.0.1'});

connected.then(function (client) {
  var data = [
    {key: 'multi1', value: 'v1'},
    {key: 'multi2', value: 'v2'},
    {key: 'multi3', value: 'v3'}];

  // Place all of the key/value pairs in the cache
  var clientPutAll = client.putAll(data);

  // Obtain the values for two of the keys
  var clientGetAll = clientPutAll.then(
    function() { return client.getAll(['multi2', 'multi3']); });

  // Print out the values obtained.
  var showGetAll = clientGetAll.then(
    function(entries) {
      console.log('getAll(multi2, multi3)=%s', JSON.stringify(entries));
    }
  );

  // Obtain an iterator for the cache
  var clientIterator = showGetAll.then(
    function() { return client.iterator(1); });

  // Iterate over the entries in the cache, printing the values
  var showIterated = clientIterator.then(
    function(it) {
      function loop(promise, fn) {
        // Simple recursive loop over iterator's next() call
        return promise.then(fn).then(function (entry) {
          return !entry.done ? loop(it.next(), fn) : entry.value;
        });
      }

      return loop(it.next(), function (entry) {
        console.log('iterator.next()=' + JSON.stringify(entry));
        return entry;
      });
    }
  );

  // Clear the cache of all values
  var clientClear = showIterated.then(
    function() { return client.clear(); });

  // Disconnect from the server
  return clientClear.finally(
    function() { return client.disconnect(); });

}).catch(function(error) {

  // Log any errors received
  console.log("Got error: " + error.message);

});

16.10.5. Hot Rod Node.js の条件付き操作

Hot Rod プロトコルは、キーに関連する各値だけでなく、メタデータも格納します。getWithMetadata は値とキーに関連するメタデータを取得します。

以下はメタデータを利用する例になります。

var infinispan = require('infinispan');

// Obtain a connection to the JBoss Data Grid server
// As no cache is specified all operations will occur on the 'default' cache
var connected = infinispan.client({port: 11222, host: '127.0.0.1'});

connected.then(function (client) {

  // Attempt to put a value in the cache if it does not exist
  var clientPut = client.putIfAbsent('cond', 'v0');

  // Print out the result of the put operation
  var showPut = clientPut.then(
      function(success) { console.log(':putIfAbsent(cond)=' + success); });

  // Replace the value in the cache
  var clientReplace = showPut.then(
      function() { return client.replace('cond', 'v1'); } );

  // Print out the result of the replace
  var showReplace = clientReplace.then(
      function(success) { console.log('replace(cond)=' + success); });

  // Obtain the value and metadata
  var clientGetMetaForReplace = showReplace.then(
      function() { return client.getWithMetadata('cond'); });

  // Replace the value only if the version matches
  var clientReplaceWithVersion = clientGetMetaForReplace.then(
      function(entry) {
        console.log('getWithMetadata(cond)=' + JSON.stringify(entry));
        return client.replaceWithVersion('cond', 'v2', entry.version);
      }
  );

  // Print out the result of the previous replace
  var showReplaceWithVersion = clientReplaceWithVersion.then(
      function(success) { console.log('replaceWithVersion(cond)=' + success); });

  // Obtain the value and metadata
  var clientGetMetaForRemove = showReplaceWithVersion.then(
      function() { return client.getWithMetadata('cond'); });

  // Remove the value only if the version matches
  var clientRemoveWithVersion = clientGetMetaForRemove.then(
      function(entry) {
        console.log('getWithMetadata(cond)=' + JSON.stringify(entry));
        return client.removeWithVersion('cond', entry.version);
      }
  );

  // Print out the result of the previous remove
  var showRemoveWithVersion = clientRemoveWithVersion.then(
      function(success) { console.log('removeWithVersion(cond)=' + success)});

  // Disconnect from the server
  return showRemoveWithVersion.finally(
      function() { return client.disconnect(); });

}).catch(function(error) {

  // Log any errors received
  console.log("Got error: " + error.message);

});

16.10.6. Hot Rod Node.js のデータセット

クライアントは接続を定義するときに複数のサーバーアドレスを指定できます。複数のサーバーが定義されると、正常にノードへの接続が確立されるまで各サーバーをループします。この設定の例を以下に示します。

var infinispan = require('infinispan');

// Accepts multiple addresses and fails over if connection not possible
var connected = infinispan.client(
  [{port: 99999, host: '127.0.0.1'}, {port: 11222, host: '127.0.0.1'}]);

connected.then(function (client) {

  // Obtain a list of all members in the cluster
  var members = client.getTopologyInfo().getMembers();

  // Print out the list of members
  console.log('Connected to: ' + JSON.stringify(members));

  // Disconnect from the server
  return client.disconnect();

}).catch(function(error) {

  // Log any errors received
  console.log("Got error: " + error.message);

});

16.10.7. Hot Rod Node.js のリモートイベント

Hot Rod Node.js クライアントはリモートキャッシュリスナーをサポートします。これらのリスナーは addListener メソッドを使用して追加できます。このメソッドはイベントタイプ (createmodifyremove、および expiry) と関数コールバックをパラメーターとして取ります。リモートイベントリスナーの詳細は、「リモートイベントリスナー (Hot Rod)」を参照してください。例を以下に示します。

var infinispan = require('infinispan');
var Promise = require('promise');

var connected = infinispan.client({port: 11222, host: '127.0.0.1'});

connected.then(function (client) {

  var clientAddListenerCreate = client.addListener(
    'create', function(key) { console.log('[Event] Created key: ' + key); });

  var clientAddListeners = clientAddListenerCreate.then(
    function(listenerId) {
      // Multiple callbacks can be associated with a single client-side listener.
      // This is achieved by registering listeners with the same listener id
      // as shown in the example below.
      var clientAddListenerModify = client.addListener(
        'modify', function(key) { console.log('[Event] Modified key: ' + key); },
        {listenerId: listenerId});

      var clientAddListenerRemove = client.addListener(
        'remove', function(key) { console.log('[Event] Removed key: ' + key); },
        {listenerId: listenerId});

      return Promise.all([clientAddListenerModify, clientAddListenerRemove]);
    });

  var clientCreate = clientAddListeners.then(
    function() { return client.putIfAbsent('eventful', 'v0'); });

  var clientModify = clientCreate.then(
    function() { return client.replace('eventful', 'v1'); });

  var clientRemove = clientModify.then(
    function() { return client.remove('eventful'); });

  var clientRemoveListener =
        Promise.all([clientAddListenerCreate, clientRemove]).then(
          function(values) {
            var listenerId = values[0];
            return client.removeListener(listenerId);
          });

  return clientRemoveListener.finally(
    function() { return client.disconnect(); });

}).catch(function(error) {

  console.log("Got error: " + error.message);

});

16.10.8. クラスターと動作する Hot Rod Node.js

複数の Red Hat JBoss Data Grid サーバーインスタンスをクラスター化してフェイルオーバーおよびスケールアップの機能を提供できます。クラスターとの動作は単一インスタンスを使用した場合と大変似ていますが、以下を考慮する必要があります。

  • クライアントは、クラスターの大きさに関わらず、サーバークラスター全体の情報を受け取るために単一のサーバーのアドレスのみを認識する必要があります。
  • 分散キャッシュでは、サーバーによって使用される一貫した同じハッシュアルゴリズムを使用してキーベースの操作がクラスターでルーティングされます。そのため、追加のネットワークホップを必要とせずに、クライアントはキーの場所を特定できます。
  • 分散キャッシュでは、複数キー操作またはキーなし操作はラウンドロビン形式でルーティングされます。
  • レプリケートされたキャッシュおよびインバリデートされたキャッシュでは、キーベース、複数キー、またはキーなしであるかに関わらず、すべての操作はラウンドロビン形式でルーティングされます。

すべてのルーティングとフェイルオーバーはクライアントに透過的であるため、クラスターに対して実行された操作は上記で実行されたコードサンプルと同じように見えます。

以下の例を使用するとクラスタートポロジーを取得できます。

var infinispan = require('infinispan');

var connected = infinispan.client({port: 11322, host: '127.0.0.1'});

connected.then(function (client) {

  var members = client.getTopologyInfo().getMembers();

  // Should show all expected cluster members
  console.log('Connected to: ' + JSON.stringify(members));

  // Add your own operations here...

  return client.disconnect();

}).catch(function(error) {

  // Log any errors received
  console.log("Got error: " + error.message);

});

16.10.9. サイトと動作する Hot Rod Node.js

複数の Red Hat JBoss Data Grid サーバークラスターをデプロイし、各クラスターが異なるサイトに属するようにすることができます。このようなデプロイメントは、あるクラスターから別のクラスター (地理的に異なる場所にある可能性がある) にデータをバックアップできるようにするために行われます。Node.js クライアント実装はクラスター内のノードの間でフェイルオーバーでき、元のクラスターが応答しなくなった場合は全体を他のクラスターにフェイルオーバーできます。クラスター間でのフェイルオーバーを可能にするには、すべての Red Hat JBoss Data Grid サーバーがクロスデータセンターレプリケーションで設定されている必要があります。この手順は、Red Hat JBoss Data Grid の『Administration and Configuration Guide』を参照してください。

フェイルオーバーが発生した場合、クライアントの代替クラスターへの接続は、例外が発生して代替クラスターが利用できなくなるまで維持されます。利用できなくなると、元のサーバー設定を含む定義された他のクラスターを試行します。

クロスデータセンターレプリケーションがサーバー上で設定されたら、クライアントは代替クラスターの設定を提供し、設定した各クラスターに対して 1 つ以上のホスト/ポートペアの詳細情報を指定する必要があります。以下に例を示します。

var connected = infinispan.client({port: 11322, host: '127.0.0.1'},
  {
    clusters: [
      {
        name: 'LON',
        servers: [{port: 1234, host: 'LONA1'}]
      },
      {
        name: 'NYC',
        servers: [{port: 2345, host: 'NYCB1'}, {port: 3456, host: 'NYCB2'}]
      }
    ]
  });

16.10.9.1. 手動クラスター切り替え

自動サイトフェイルオーバーの他にも、Node.js クライアントは以下のメソッドのいずれかを呼び出してサイトクラスターの手動で切り替えることができます。

  • switchToCluster(clusterName) - クライアントを事前定義されたクラスター名に強制的に切り替えます。
  • switchToDefaultCluster() - クライアントをクライアント設定で定義された最初のサーバーに強制的に切り替えます。

たとえば、手動で NYC クラスターへ切り替える場合は以下を使用できます。

var connected = infinispan.client({port: 11322, host: '127.0.0.1'},
  {
    clusters: [
      {
        name: 'LON',
        servers: [{port: 1234, host: 'LONA1'}]
      },
      {
        name: 'NYC',
        servers: [{port: 2345, host: 'NYCB1'}, {port: 3456, host: 'NYCB2'}]
      }
    ]
  });

connected.then(function (client) {

  var switchToB = client.getTopologyInfo().switchToCluster('NYC');
  [...]
  });

16.11. Hot Rod C++ と Hot Rod Java クライアント間の相互運用性

Red Hat JBoss Data Grid は、構造化データにアクセスするために Hot Rod Java と Hot Rod C++ クライアント間の相互運用性を提供します。これは、Google の Protobuf 形式を使用してデータを構造化およびシリアライズすることにより可能になります。

たとえば、言語間の相互運用性を使用すると、Hot Rod C++ クライアントが Protobuf を使用して構造化およびシリアライズされた次の Person オブジェクトを記述し、Hot Rod Java クライアントが Protobuf として構造化された同じ Person オブジェクトを読み取ることができます。

言語間の相互運用性の使用

package sample;
message Person {
    required int32 age = 1;
    required string name = 2;
}

C++ と Hot Rod Java クライアント間の相互運用性は基本データタイプ、文字列、バイトアレイにおいて完全にサポートされています。Protobuf と Protostream はこれらのタイプの相互運用性のために必要ありません。

16.12. サーバーと Hot Rod クライアントバージョン間の互換性

Hot Rod Java、Hot Rod C++、および Hot Rod C# などの Hot Rod クライアントは異なるバージョンの Red Hat JBoss Data Grid サーバーと互換性があります。このサーバーのバージョンは、複数の異なる Hot Rod クライアントと共に実行するために最新バージョンである必要があります。

注記

既知の問題を防ぐために、移行またはアップグレードの場合を除き、同じバージョンの Hot Rod クライアントおよび Red Hat JBoss Data Grid サーバーを使用することをお勧めします。

以下のシナリオを見てみましょう。

シナリオ 1: サーバーが Hot Rod クライアントよりも新しいバージョンで実行される。

以下の影響がクライアント側に及ぶことが考えられます。

  • クライアントには、プロトコルの最新改良によるメリットはない。
  • クライアントはサーバー側のバージョンで修正されている既知の問題に直面する可能性がある。
  • クライアントは現在のバージョンと以前のバージョンで利用可能な機能のみを使用できる。

シナリオ 2: Hot Rod クライアントがサーバーよりも新しいバージョンで実行される。

Hot Rod クライアントが Red Hat JBoss Data Grid サーバーに接続される場合、その接続は例外エラーを出して拒否されます。クライアント側のプロパティー infinispan.client.hotrod.protocol_version を設定するか、ConfigurationBuilderprotocolVersion(String version) を使用すると、クライアントを既知のプロトコルバージョンにダウングレードできます。どちらかの方法でクライアントのバージョンをダウングレードすると、適切なバージョンが含まれる String が渡されるはずです。この場合、クライアントはサーバーに接続できますが、そのバージョンの機能に制限されます。このプロトコルのバージョンでサポートされないコマンドは機能せず、例外が発生します。さらに、この場合のトポロジー情報は効率的でない可能性があります。

クライアントの Hot Rod プロトコルバージョンのダウングレード

以下のコード例は、protocolVersion(String version) メソッドを使用してバージョンをダウングレードする方法を示しています。

Configuration config = new ConfigurationBuilder()
    [...]
    .protocolVersion("2.2")
    .build();
注記

Red Hat サポートの指示を受けずにこの方法を使用することは推奨されません。

以下の表は、異なる Hot Rod クライアントとサーバーのバージョン間の互換性についての詳細情報です。

表16.78 Hot Rod プロトコルとサーバーの互換性

Red Hat JBoss Data Grid サーバーのバージョンHot Rod プロトコルのバージョン

Red Hat JBoss Data Grid 7.2.0

Hot Rod 2.5 以上

Red Hat JBoss Data Grid 7.1.0

Hot Rod 2.5 以上

Red Hat JBoss Data Grid 7.0.0

Hot Rod 2.5 以上