11.6. REST インターフェースの使用

REST インターフェースを Red Hat JBoss Data Grid のリモートクライアントサーバーモードで使用して、以下の操作を実行できます。
  • データの追加
  • データの取得
  • データの削除
バグを報告する

11.6.1. REST を使用したデータの追加

Red Hat JBoss Data Grid の REST インターフェースで、以下のメソッドを使用してキャッシュにデータを追加します。
  • HTTP PUT メソッド
  • HTTP POST メソッド
PUT メソッドと POST メソッドが使用される場合、要求の本文には、ユーザーにより追加された情報を含むこのデータが含まれます。
PUT メソッドと POST メソッドの両方には、Content-Type ヘッダーが必要です。
バグを報告する

11.6.1.1. PUT /{cacheName}/{cacheKey} について

提供された URL フォームからの PUT 要求により、提供されたキーを使用して要求本文からのペイロードがターゲットキャッシュに配置されます。このタスクが正常に完了するには、ターゲットキャッシュがサーバーに存在する必要があります。
例として、以下の URL では、値 hr がキャッシュ名であり、payRoll%2F3 がキーです。値 %2F は、/ がキーで使用されたことを示します。 
http://someserver/rest/hr/payRoll%2F3
既存のデータは置き換えられ、更新が必要な場合は Time-To-Live 値と Last-Modified 値が更新されます。

注記

以下の引数を使用してサーバーが起動された場合は、キーの / を表す値 %2F を含むキャッシュキー (提供された例を参照) を正常に実行できます。 
-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
バグを報告する

11.6.1.2. POST /{cacheName}/{cacheKey} について

提供された URL フォームからの POST メソッドにより、提供されたキーを使用して (要求本文からの) ペイロードがターゲットキャッシュに配置されます。ただし、POST メソッドでは、値がキャッシュ/キーに存在する場合に、HTTP CONFLICT ステータスが返され、内容が更新されません。
バグを報告する

11.6.2. REST を使用したデータの取得

Red Hat JBoss Data Grid の REST インターフェースで、以下のメソッドを使用してキャッシュからデータを取得します。
  • HTTP GET メソッド。
  • HTTP HEAD メソッド。
バグを報告する

11.6.2.1. GET /{cacheName}/{cacheKey} について

GET メソッドは、応答の本文として、提供された cacheName に存在し、関連するキーに一致するデータを返します。Content-Type ヘッダーは、データのタイプを提供します。ブラウザーはキャッシュに直接アクセスできます。
各エントリーに対して、要求された URL でデータの状態を示す Last-Modified ヘッダーとともに一意のエンティティータグ (ETag) が返されます。ETag により、ブラウザー (および他のクライアント) は、(帯域幅を節約するために) データが変更された場合のみデータを要求できます。ETag は、HTTP 標準の一部であり、Red Hat JBoss Data Grid によりサポートされます。
格納されたコンテンツのタイプは、返されたタイプです。例として、文字列が格納された場合は、文字列が返されます。シリアライズされた形式で格納されたオブジェクトは、手動でシリアライズ解除する必要があります。
バグを報告する

11.6.2.2. HEAD /{cacheName}/{cacheKey} について

HEAD メソッドは、GET メソッドと同様に動作しますが、コンテンツを返しません (ヘッダーフィールドが返されます)。
バグを報告する

11.6.3. REST を使用したデータの削除

REST インターフェースを使用して Red Hat JBoss Data Grid からデータを削除するには、HTTP DELETE メソッドを使用してキャッシュからデータを取得します。DELETE メソッドは以下のことを行えます。
  • キャッシュエントリー/値を削除します。(DELETE /{cacheName}/{cacheKey})
  • キャッシュからすべてのエントリーを削除します。(DELETE /{cacheName})
バグを報告する

11.6.3.1. DELETE /{cacheName}/{cacheKey} について

このコンテキスト (DELETE /{cacheName}/{cacheKey}) で使用された場合、DELETE メソッドは提供されたキーのキャッシュからキー/値を削除します。
バグを報告する

11.6.3.2. DELETE /{cacheName} について

このコンテキスト (DELETE /{cacheName}) では、DELETE メソッドが名前付きキャッシュ内のすべてのエントリーを削除します。正常な DELETE 操作後に、HTTP ステータスコード 200 が返されます。
バグを報告する

11.6.3.3. バックグラウンド削除操作

performAsync ヘッダーの値を true に設定して、削除操作がバックグラウンドで続行される状態で値がすぐに返されるようにします。
バグを報告する

11.6.4. REST インターフェース操作ヘッダー

以下の表は、Red Hat JBoss Data Grid REST インターフェースに含まれるヘッダーを示しています。

表11.1 ヘッダータイプ

ヘッダー 必須/オプション 値 デフォルト値 説明
Content-Type 必須 - - Content-Type が application/x-java-serialized-object に設定された場合は、Java オブジェクトとして格納されます。
performAsync 任意 true/false - true に設定された場合は、すぐに返され、独自にクラスターにデータがレプリケートされます。この機能は、大量のデータ挿入と大きいクラスターを取り扱う場合に役に立ちます。
timeToLiveSeconds 任意 数値 (正の値および負の値) -1 (この値により、timeToLiveSeconds の直接的な結果としてエクスパレーションが回避されます。このデフォルト値よりも、他の場所で設定されたエクスパレーションの値が優先されます。) 該当するエントリーが自動的に削除されるまでの秒数を反映します。timeToLiveSeconds に負の値を設定すると、デフォルト値と同じ結果が提供されます。
maxIdleTimeSeconds 任意 数値 (正の値および負の値) -1 (この値により、maxIdleTimeSeconds の直接的な結果としてエクスパレーションが回避されます。このデフォルト値よりも、他の場所で設定されたエクスパレーションの値が優先されます。) エントリーが自動的に削除される場合の、最後の使用時以降の秒数を含みます。負の値を渡すと、デフォルト値と同じ結果が提供されます。
timeToLiveSeconds ヘッダーと maxIdleTimeSeconds ヘッダーには以下の組み合わせを設定できます。
  • timeToLiveSeconds ヘッダーと maxIdleTimeSeconds ヘッダーに値 0 が割り当てられた場合、キャッシュは、 XML を使用するか、またはプログラミングにより設定されたデフォルトの timeToLiveSeconds 値と maxIdleTimeSeconds 値を使用します。
  • maxIdleTimeSeconds ヘッダー値のみが 0 に設定された場合は、timeToLiveSeconds 値をパラメーター (または、デフォルトの -1 (パラメーターが存在しない場合)) として渡す必要があります。また、maxIdleTimeSeconds パラメーター値は、 XML を使用するか、プログラミングにより、設定された値にデフォルトで設定されます。
  • timeToLiveSeconds ヘッダー値のみが 0 に設定された場合は、エクスパレーションが即座に発生し、maxIdleTimeSeconds 値がパラメーターとして渡された値に設定されます (パラメーターが提供されなかった場合はデフォルトの -1)。
ETag ベースのヘッダー

各 REST インターフェースエントリーに対して、提供された URL でデータの状態を示す Last-Modified ヘッダーとともに、ETags (エンティティータグ) が返されます。ETags は、帯域幅を節約するためにデータが変更された場合にのみ、データを要求する HTTP 操作で使用されます。以下のヘッダーは、ETags (エンティティータグ) ベースの楽観的ロックをサポートします。

表11.2 エンティティータグ関連ヘッダー

ヘッダー アルゴリズム 例 説明
If-Match If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) - (リソースから以前に取得された) 指定されたエンティティーが最新であることを確認するために、関連するエンティティータグのリストとともに使用されます。
If-None-Match - (リソースから以前に取得された) 指定されたエンティティーが最新でないことを確認するために、関連するエンティティータグのリストとともに使用されます。この機能により、必要なときに、最小のトランザクションオーバーヘッドで、キャッシュされた情報が効率的に更新されます。
If-Modified-Since If-Modified-Since = "If-Modified-Since" ":" HTTP-date If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたバリアントが変更されなかった場合は、エンティティーの代わりに 304 (未変更) 応答がメッセージ本文なしで返されます。
If-Unmodified-Since If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたリソースが変更されなかった場合は、指定された操作が実行されます。指定された日時以降に要求されたリソースが変更された場合は、操作が実行されず、エンティティーの代わりに 412 (事前条件失敗) 応答が返されます。
バグを報告する