Check-and-Set メソッドはクライアントがチェック(CAS)の値を知っている場合のみ情報を更新できるメカニズムを提供します。これはクライアントが値を取得してから書き換えられている可能性のあるデータベース内の値を上書きしてしまうことを防止するために利用します。情報の保存や更新用メソッドでCASをサポートしているものは、クライアントが取得した際のデータを更新することを確実にすることができます。
チェック用の値は64ビットの整数形式で、その値が変更されるたびに更新されます。更新操作によってデータのバイナリ表現が変わらない場合でもチェック用の値は更新されます。サーバ側と異なるCAS値を指定した場合、key/valueペアに対する更新は失敗します。
cas()
メソッドは
「Set 操作」
メソッドと似ており、明示的にサーバ側のCASとクライアントが渡したCASが一致する場合のみ値をセットする際に利用します。
全てのCAS操作では、 CASResponse
の戻り値がその操作が成功したかどうかを示します。CASResponse
は 次の3つの値を持つEnum
です:
EXISTS
アイテムは存在しますが、データベース上のCAS値がCAS操作時に指定されたものと一致しません。
NOT_FOUND
指定されたキーがデータベースに存在しません。add()
メソッドを利用しキーをデータベースに追加するべきです。
OK
CAS操作が成功し、更新後の値がCouchbaseに保存されています。
API Call | client.cas(key, casunique, value) | ||
Asynchronous | no | ||
Description | Compare and set a value providing the supplied CAS key matches | ||
Returns | CASResponse (
Check and set object
) | ||
Arguments | |||
String key | Document ID used to identify the value | ||
long casunique | Unique value used to verify a key/value combination | ||
Object value | Value to be stored |
cas()
メソッドの一つ目の形式は指定のCAS値がサーバに保存された値と等しい場合のみ、アイテムがデータベースにセットされるようにします。
例:
CASResponse casr = client.cas("caskey", casvalue, "new string value"); if (casr.equals(CASResponse.OK)) { System.out.println("Value was updated"); } else if (casr.equals(CASResponse.NOT_FOUND)) { System.out.println("Value is not found"); } else if (casr.equals(CASResponse.EXISTS)) { System.out.println("Value exists, but CAS didn't match"); }
API Call | client.cas(key, casunique, value, transcoder) | ||
Asynchronous | no | ||
Description | Compare and set a value providing the supplied CAS key matches | ||
Returns | CASResponse (
Check and set object
) | ||
Arguments | |||
String key | Document ID used to identify the value | ||
long casunique | Unique value used to verify a key/value combination | ||
Object value | Value to be stored | ||
Transcoder<T> transcoder | Transcoder class to be used to serialize value |
メソッドの二つ目の形式は値を保存するためのカスタムトランスコーダを利用できます。
API Call | client.cas(key, casunique, expiry, value, transcoder) | ||
Asynchronous | no | ||
Description | Compare and set a value providing the supplied CAS key matches | ||
Returns | CASResponse (
Check and set object
) | ||
Arguments | |||
String key | Document ID used to identify the value | ||
long casunique | Unique value used to verify a key/value combination | ||
int expiry | Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
Object value | Value to be stored | ||
Transcoder<T> transcoder | Transcoder class to be used to serialize value |
この形式の cas()
メソッドはキーと値に加え、値の有効期限も更新します。期限付きの値については次を参照してください。「有効期限」
例えば次のコードは、更新後の値と有効期限3600秒(1時間)でキー"caskey
"の更新を試みます。
Transcoder<Integer> tc = new IntegerTranscoder(); CASResponse casr = client.cas("caskey", casvalue, 3600, 1200, tc);
API Call | client.asyncCAS(key, casunique, value) | ||
Asynchronous | yes | ||
Description | Compare and set a value providing the supplied CAS key matches | ||
Returns | Future<CASResponse> (
Asynchronous request value, as CASResponse
) | ||
Arguments | |||
String key | Document ID used to identify the value | ||
long casunique | Unique value used to verify a key/value combination | ||
Object value | Value to be stored |
与えられた key/value の非同期CAS操作を実行します。このメソッドを利用すれば、応答を待たずに、CASを利用した値の設定ができます。次の例ではキーのアップデートをリクエストし、操作が成功しなかった場合、5秒後にタイムアウトします。
Future<CASResponse> future = client.asyncCAS("someKey", casvalue, "updatedvalue"); CASResponse casr; try { casr = future.get(5, TimeUnit.SECONDS); } catch(TimeoutException e) { future.cancel(false); }
API Call | client.asyncCAS(key, casunique, value, transcoder) | ||
Asynchronous | yes | ||
Description | Compare and set a value providing the supplied CAS key matches | ||
Returns | Future<CASResponse> (
Asynchronous request value, as CASResponse
) | ||
Arguments | |||
String key | Document ID used to identify the value | ||
long casunique | Unique value used to verify a key/value combination | ||
Object value | Value to be stored | ||
Transcoder<T> transcoder | Transcoder class to be used to serialize value |
カスタムトランスコーダを使用して、指定した key/value の非同期CAS操作を実行します。 以下の例は、カスタム整数トランスコーダを使用した既存の値の更新を示しています。
Transcoder<Integer> tc = new IntegerTranscoder(); Future<CASResponse> future = client.asyncCAS("someKey", casvalue, 1200, tc); CASResponse casr; try { casr = future.get(5, TimeUnit.SECONDS); } catch(TimeoutException e) { future.cancel(false); }
API Call | client.asyncCAS(key, casunique, expiry, value, transcoder) | ||
Asynchronous | yes | ||
Description | Compare and set a value providing the supplied CAS key matches | ||
Returns | Future<CASResponse> (
Asynchronous request value, as CASResponse
) | ||
Arguments | |||
String key | Document ID used to identify the value | ||
long casunique | Unique value used to verify a key/value combination | ||
int expiry | Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
Object value | Value to be stored | ||
Transcoder<T> transcoder | Transcoder class to be used to serialize value |
asyncCAS()
メソッドのもう一つの形式ではカスタムトランスコーダおよび有効期限の設定をサポートしています。次の例では、値を更新し60秒間の有効期限を設定します:
Transcoder<Integer> tc = new IntegerTranscoder(); Future<CASResponse> future = client.asyncCAS("someKey", casvalue, 60, 1200, tc); CASResponse casr; try { casr = future.get(5, TimeUnit.SECONDS); } catch(TimeoutException e) { future.cancel(false); }