13.6. Hot Rod 操作
以下に、Hot Rod プロトコル 1.3 を使用して Red Hat JBoss Data Grid と対話する場合に有効な操作を示します。
- BulkGetKeys
- BulkGet
- Clear
- ContainsKey
- Get
- GetWithMetadata
- Ping
- PutIfAbsent
- Put
- Query
- RemoveIfUnmodified
- Remove
- ReplaceIfUnmodified
- 次の箇所を探します。
- Stats
重要
RemoteCache API を使用して Hot Rod クライアントの
Put 操作、PutIfAbsent 操作、Replace 操作、および ReplaceWithVersion 操作を呼び出す場合に、ライフスパンが 30 日よりも大きい値に設定されると、値は UNIX 時間として処理され、1970 年 1 月 1 日以降の秒数を表します。
13.6.1. Hot Rod BulkGet 操作
Hot Rod
BulkGet 操作は、以下の要求形式を使用します。
表13.7 BulkGet 操作要求形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| エントリー数 | vInt | サーバーにより返される Red Hat JBoss Data Grid エントリーの最大数が含まれます。エントリーはキーと値のペアです。 |
この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。
表13.8 BulkGet 操作応答形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| 詳細 | vInt | ストリームからエントリーをさらに読み取る必要があるかどうかを示します。More は 1 に設定される一方で、More の値が 0 (ストリームの最後を示します) に設定されるまで追加のエントリーが続きます。 |
| キーサイズ | - | キーのサイズを含みます。 |
| キー | - | キーの値を含みます。 |
| 値サイズ | - | 値のサイズを含みます。 |
| 値 | - | 値を含みます。 |
要求された各エントリーに対して、
More、Key Size、Key、Value Size、および Value エントリーが応答に追加されます。
13.6.2. Hot Rod BulkGetKeys 操作
Hot Rod
BulkGetKeys 操作は、以下の要求形式を使用します。
表13.9 BulkGetKeys 操作の要求形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | 変数 | 要求ヘッダー |
| Scope | vInt |
|
この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。
表13.10 BulkGetKeys 操作の応答形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | 変数 | 応答ヘッダー |
| Response status | 1 バイト | 0x00 = 成功 (データが続きます)。 |
| More | 1 バイト | ストリームからより多くのキーを読み取る必要があるかを表す 1 つのバイト。1 に設定されている場合はエントリーが続き、0 に設定されている場合はストリームの最後であり、読み取るエントリーが残っていません。 |
| Key 1 Length | vInt | キーの長さ |
| Key 1 | バイトアレイ | 取得されたキー |
| More | 1 バイト | - |
| Key 2 Length | vInt | - |
| Key 2 | バイトアレイ | - |
| ...etc |
13.6.3. Hot Rod clear 操作
clear 操作形式には、ヘッダーのみ含まれます。
この操作に有効な応答ステータスは以下のとおりです。
表13.11 clear 操作応答
| 応答ステータス | 説明 |
|---|---|
| 0x00 | Red Hat JBoss Data Grid が正常に消去されました。 |
13.6.4. Hot Rod ContainsKey 操作
Hot Rod
ContainsKey 操作は、以下の要求形式を使用します。
表13.12 ContainsKey 操作要求形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| キーの長さ | vInt | キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) のため、vInt データタイプが使用されます。ただし、Java では、単一アレイサイズを Integer.MAX_VALUE のサイズよりも大きくすることはできません。結果として、この vInt は Integer.MAX_VALUE の最大サイズに限定されます。 |
| キー | バイトアレイ | キーを含みます (このキーの対応する値が要求されます)。 |
この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。
表13.13 ContainsKey 操作応答形式
| 応答ステータス | 説明 |
|---|---|
| 0x00 | 操作が成功。 |
| 0x02 | キーが存在しない。 |
この操作の応答は空白です。
13.6.5. Hot Rod Get 操作
Hot Rod
Get 操作は、以下の要求形式を使用します。
表13.14 Get 操作要求形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Key Length | vInt | キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) のため、vInt データタイプが使用されます。ただし、Java では、単一アレイサイズを Integer.MAX_VALUE のサイズよりも大きくすることはできません。結果として、この vInt は Integer.MAX_VALUE の最大サイズに限定されます。 |
| Key | バイトアレイ | キーを含みます (このキーの対応する値が要求されます)。 |
この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。
表13.15 Get 操作応答形式
| 応答ステータス | 説明 |
|---|---|
| 0x00 | 操作が成功。 |
| 0x02 | キーが存在しない。 |
キーが見つかった場合の
get 操作の応答の形式は以下のとおりです。
表13.16 Get 操作応答形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Value Length | vInt | 値の長さを含みます。 |
| Value | バイトアレイ | 要求された値を含みます。 |
13.6.6. Hot Rod GetWithMetadata 操作
Hot Rod
GetWithMetadata 操作は以下の要求形式を使用します。
表13.17 GetWithMetadata 操作の要求形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | 変数 | 要求ヘッダー。 |
| Key Length | vInt | キーの長さ。vInt のサイズは最大 5 バイトであり、理論的には Integer.MAX_VALUE よりも大きい数を生成できます。ただし、Java では Integer.MAX_VALUE よりも大きい単一アレイを作成できず、プロトコルにより vInt アレイの長さが Integer.MAX_VALUE に制限されます。 |
| Key | バイトアレイ | 値が要求されるキーを含むバイトアレイ。 |
この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。
表13.18 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 | バイトアレイ | 成功した場合は、要求された値。 |
13.6.7. Hot Rod ping 操作
ping は、サーバーの可用性を確認するアプリケーションレベルの要求です。
この操作に有効な応答ステータスは以下のとおりです。
表13.19 ping 操作応答
| 応答ステータス | 説明 |
|---|---|
| 0x00 | エラーなしの正常な ping。 |
13.6.8. Hot Rod Put 操作
put 操作要求形式には、以下のものが含まれます。
表13.20
| フィールド | データタイプ | 詳細 |
|---|---|---|
| Header | - | - |
| Key Length | - | キーの長さを含みます。 |
| Key | バイトアレイ | キーの値を含みます。 |
| Lifespan | vInt | エントリーが期限切れになるまでの秒数を含みます。秒数が 30 日を超える場合、その値はエントリーライフスパンの UNIX 時間 (つまり、日付 1/1/1970 以降の秒数) として処理されます。値が 0 に設定された場合、エントリーは期限切れになりません。 |
| Max Idle | vInt | キャッシュからエビクトされるまでエントリーがアイドル状態のままになることが許可される秒数を含みます。このエントリーが 0 に設定された場合、エントリーは無期限でアイドル状態のままになることが許可され、max idle 値のため、エビクトされません。 |
| Value Length | vInt | 値の長さを含みます。 |
| 値 | バイトアレイ | 要求された値。 |
以下は、この操作から返される応答値です。
表13.21
| 応答ステータス | 詳細 |
|---|---|
| 0x00 | 値が正常に格納されました。 |
この操作では空の応答がデフォルト応答になります。ただし、
ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。
重要
RemoteCache API を使用して Hot Rod クライアントの
Put 操作、PutIfAbsent 操作、Replace 操作、および ReplaceWithVersion 操作を呼び出す場合に、ライフスパンが 30 日よりも大きい値に設定されると、値は UNIX 時間として処理され、1970 年 1 月 1 日以降の秒数を表します。
13.6.9. Hot Rod PutIfAbsent 操作
putIfAbsent 操作要求形式には、以下のものが含まれます。
表13.22 PutIfAbsent 操作要求フィールド
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Key Length | vInt | キーの長さを含みます。 |
| Key | バイトアレイ | キーの値を含みます。 |
| Lifespan | vInt | エントリーが期限切れになるまでの秒数を含みます。秒数が 30 日を超える場合、その値はエントリーライフスパンの UNIX 時間 (つまり、日付 1/1/1970 以降の秒数) として処理されます。値が 0 に設定された場合、エントリーは期限切れになりません。 |
| Max Idle | vInt | キャッシュからエビクトされるまでエントリーがアイドル状態のままになることが許可される秒数を含みます。このエントリーが 0 に設定された場合、エントリーは無期限でアイドル状態のままになることが許可され、max idle 値のため、エビクトされません。 |
| Value Length | vInt | 値の長さを含みます。 |
| Value | バイトアレイ | 要求された値を含みます。 |
以下は、この操作から返される応答値です。
表13.23
| 応答ステータス | 説明 |
|---|---|
| 0x00 | 値が正常に格納されました。 |
| 0x01 | キーが存在しないため、値が格納されませんでした。キーの現在の値が返されました。 |
この操作では空の応答がデフォルト応答になります。ただし、
ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。
重要
RemoteCache API を使用して Hot Rod クライアントの
Put 操作、PutIfAbsent 操作、Replace 操作、および ReplaceWithVersion 操作を呼び出す場合に、ライフスパンが 30 日よりも大きい値に設定されると、値は UNIX 時間として処理され、1970 年 1 月 1 日以降の秒数を表します。
13.6.10. Hot Rod クエリー操作
Query 操作要求形式には、以下のものが含まれます。
表13.24 クエリー操作要求フィールド
| フィールド | データタイプ | 詳細 |
|---|---|---|
| Header | 変数 | 要求ヘッダー。 |
| Query Length | vInt | Protobuf エンコードされたクエリーオブジェクトの長さ。 |
| Query | バイトアレイ | Protobuf エンコードされたクエリーオブジェクトを含むバイトアレイ。長さは前のフィールドにより指定されます。 |
以下は、この操作から返される応答値です。
表13.25 クエリー操作応答
| 応答ステータス | データ | 詳細 |
|---|---|---|
| Header | 変数 | 応答ヘッダー。 |
| Response payload Length | vInt | Protobuf エンコードされた応答オブジェクトの長さ。 |
| Response payload | バイトアレイ | Protobuf エンコードされた応答オブジェクトを含むバイトアレイ。長さは前のフィールドにより指定されます。 |
13.6.11. Hot Rod Remove 操作
Hot Rod Remove 操作は、以下の要求形式を使用します。
表13.26 Remove 操作要求形式
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Key Length | vInt | キーの長さを含みます。Integer.MAX_VALUE のサイズよりも大きいサイズ (最大 5 バイト) のため、vInt データタイプが使用されます。ただし、Java では、単一アレイサイズを Integer.MAX_VALUE のサイズよりも大きくすることはできません。結果として、この vInt は Integer.MAX_VALUE の最大サイズに限定されます。 |
| Key | バイトアレイ | キーを含みます (このキーの対応する値が要求されます)。 |
この操作の応答ヘッダーには、以下のいずれかの応答ステータスが含まれます。
表13.27 Remove 操作応答形式
| 応答ステータス | 説明 |
|---|---|
| 0x00 | 操作が成功。 |
| 0x02 | キーが存在しない。 |
通常、この操作の応答ヘッダーは空白です。ただし、
ForceReturnPreviousValue が渡された場合は、応答ヘッダーに以下のいずれかが含まれます。
- 以前のキーの値および長さ。
- キーが存在しないことを示す、値の長さ
0と応答ステータス0x02。
remove 操作の応答ヘッダーには、提供されたキーの以前の値と、以前の値の長さが含まれます (
ForceReturnPreviousValue が渡された場合)。キーが存在しない場合、または以前の値が null の場合、値の長さは 0 です。
13.6.12. Hot Rod RemoveIfUnmodified 操作
RemoveIfUnmodified 操作要求形式には、以下のものが含まれます。
表13.28 RemoveIfUnmodified 操作要求フィールド
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Key Length | vInt | キーの長さを含みます。 |
| Key | バイトアレイ | キーの値を含みます。 |
| Entry Version | 8 バイト | エントリーのバージョン番号。 |
以下は、この操作から返される応答値です。
表13.29 RemoveIfUnmodified 操作応答
| 応答ステータス | 説明 |
|---|---|
| 0x00 | エントリーが置換または削除された場合に返されたステータス。 |
| 0x01 | キーが変更されたため、エントリーの置換または削除が失敗した場合に、ステータスを返します。 |
| 0x02 | キーが存在しない場合に、ステータスを返します。 |
この操作では空の応答がデフォルト応答になります。ただし、
ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。
13.6.13. Hot Rod replace 操作
replace 操作要求形式には、以下のものが含まれます。
表13.30 replace 操作要求フィールド
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Key Length | vInt | キーの長さを含みます。 |
| キー | バイトアレイ | キーの値を含みます。 |
| Lifespan | vInt | エントリーが期限切れになるまでの秒数を含みます。秒数が 30 日を超える場合、その値はエントリーライフスパンの UNIX 時間 (つまり、日付 1/1/1970 以降の秒数) として処理されます。値が 0 に設定された場合、エントリーは期限切れになりません。 |
| Max Idle | vInt | キャッシュからエビクトされるまでエントリーがアイドル状態のままになることが許可される秒数を含みます。このエントリーが 0 に設定された場合、エントリーは無期限でアイドル状態のままになることが許可され、max idle 値のため、エビクトされません。 |
| Value Length | vInt | 値の長さを含みます。 |
| 値 | バイトアレイ | 要求された値を含みます。 |
以下は、この操作から返される応答値です。
表13.31 replace 操作応答
| 応答ステータス | 説明 |
|---|---|
| 0x00 | 値が正常に格納されました。 |
| 0x01 | キーが存在しないため、値が格納されませんでした。 |
この操作では空の応答がデフォルト応答になります。ただし、
ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。
重要
RemoteCache API を使用して Hot Rod クライアントの
Put 操作、PutIfAbsent 操作、Replace 操作、および ReplaceWithVersion 操作を呼び出す場合に、ライフスパンが 30 日よりも大きい値に設定されると、値は UNIX 時間として処理され、1970 年 1 月 1 日以降の秒数を表します。
13.6.14. Hot Rod ReplaceWithVersion 操作
ReplaceWithVersion 操作要求形式には、以下のものが含まれます。
注記
RemoteCache API では、Hot Rod
ReplaceWithVersion 操作は ReplaceIfUnmodified 操作を使用します。結果として、これらの 2 つの操作は JBoss Data Grid でまったく同じになります。
表13.32 ReplaceWithVersion 操作要求フィールド
| フィールド | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| キー長 | vInt | キーの長さを含みます。 |
| Key | バイトアレイ | キーの値を含みます。 |
| Lifespan | vInt | エントリーが期限切れになるまでの秒数を含みます。秒数が 30 日を超える場合、その値はエントリーライフスパンの UNIX 時間 (つまり、日付 1/1/1970 以降の秒数) として処理されます。値が 0 に設定された場合、エントリーは期限切れになりません。 |
| Max Idle | vInt | キャッシュからエビクトされるまでエントリーがアイドル状態のままになることが許可される秒数を含みます。このエントリーが 0 に設定された場合、エントリーは無期限でアイドル状態のままになることが許可され、max idle 値のため、エビクトされません。 |
| Entry Version | 8 バイト | エントリーのバージョン番号。 |
| Value Length | vInt | 値の長さを含みます。 |
| 値 | バイトアレイ | 要求された値を含みます。 |
以下は、この操作から返される応答値です
表13.33 ReplaceWithVersion 操作応答
| 応答ステータス | 説明 |
|---|---|
| 0x00 | エントリーが置換または削除された場合に返されたステータス。 |
| 0x01 | キーが変更されたため、エントリーの置換または削除が失敗した場合に、ステータスを返します。 |
| 0x02 | キーが存在しない場合に、ステータスを返します。 |
この操作では空の応答がデフォルトの応答になります。ただし、
ForceReturnPreviousValue が渡された場合は、以前の値とキーが返されます。以前のキーと値が存在しない場合は、値の長さに値 0 が含まれます。
13.6.15. Hot Rod 統計操作
この操作は、利用可能なすべての統計の概要を返します。返された各統計に対して、名前と値が文字列形式と UTF-8 形式の両方で返されます。
この操作では、以下の統計がサポートされます。
表13.34 統計操作要求フィールド
| 名前 | 説明 |
|---|---|
| timeSinceStart | Hot Rod が起動した以降の秒数を含みます。 |
| currentNumberOfEntries | Hot Rod サーバーに現在存在するエントリーの数を含みます。 |
| totalNumberOfEntries | Hot Rod サーバーに格納されたエントリーの合計数を含みます。 |
| stores | put 操作の試行回数を含みます。 |
| retrievals | get 操作の試行回数を含みます。 |
| hits | get ヒット数を含みます。 |
| misses | get 失敗数を含みます。 |
| removeHits | remove ヒット数を含みます。 |
| removeMisses | removal 失敗数を含みます。 |
この操作の応答ヘッダーには以下のものが含まれます。
表13.35 統計操作応答
| 名前 | データタイプ | 説明 |
|---|---|---|
| Header | - | - |
| Number of Stats | vInt | 返された個別統計の数を含みます。 |
| Name Length | vInt | 名前付き統計の長さを含みます。 |
| 名前 | 文字列 | 統計の名前を含みます。 |
| Value Length | vInt | 値の長さを含みます。 |
| 値 | 文字列 | 統計値を含みます。 |
要求された各統計に対して、値
Name Length、Name、Value Length、および Value が繰り返されます。