checkAndSet

单HashKey数据的原子CAS操作（可以理解为单行原子操作）。详细说明参见单行原子操作。

该操作先对某个SortKey（称之为CheckSortKey）的value做条件检查：

  • 如果检查的条件满足，则将另一个SortKey（称之为SetSortKey）的value设置为新值。
  • 如果检查的条件不满足，则不执行set操作。CheckSortKey和SetSortKey可以相同也可以不同。

用户还可以设置CheckAndSetOptions.returnCheckValue来获取CheckSortKey对应的value。如果CheckSortKey和SetSortKey相同并且set成功，则获取set之前的旧值。

  1. public enum CheckType {
  2.     CT_NO_CHECK(0),
  3.  
  4.     // appearance
  5.     CT_VALUE_NOT_EXIST(1),          // value is not exist
  6.     CT_VALUE_NOT_EXIST_OR_EMPTY(2), // value is not exist or value is empty
  7.     CT_VALUE_EXIST(3),              // value is exist
  8.     CT_VALUE_NOT_EMPTY(4),          // value is exist and not empty
  9.  
  10.     // match
  11.     CT_VALUE_MATCH_ANYWHERE(5), // operand matches anywhere in value
  12.     CT_VALUE_MATCH_PREFIX(6),   // operand matches prefix in value
  13.     CT_VALUE_MATCH_POSTFIX(7),  // operand matches postfix in value
  14.  
  15.     // bytes compare
  16.     CT_VALUE_BYTES_LESS(8),              // bytes compare: value < operand
  17.     CT_VALUE_BYTES_LESS_OR_EQUAL(9),     // bytes compare: value <= operand
  18.     CT_VALUE_BYTES_EQUAL(10),            // bytes compare: value == operand
  19.     CT_VALUE_BYTES_GREATER_OR_EQUAL(11), // bytes compare: value >= operand
  20.     CT_VALUE_BYTES_GREATER(12),          // bytes compare: value > operand
  21.  
  22.     // int compare: first transfer bytes to int64; then compare by int value
  23.     CT_VALUE_INT_LESS(13),             // int compare: value < operand
  24.     CT_VALUE_INT_LESS_OR_EQUAL(14),    // int compare: value <= operand
  25.     CT_VALUE_INT_EQUAL(15),            // int compare: value == operand
  26.     CT_VALUE_INT_GREATER_OR_EQUAL(16), // int compare: value >= operand
  27.     CT_VALUE_INT_GREATER(17);          // int compare: value > operand
  28. }
  29.  
  30. public class CheckAndSetOptions {
  31.     public int setValueTTLSeconds = 0; // time to live in seconds of the set value, 0 means no ttl.
  32.     public boolean returnCheckValue = false; // if return the check value in results.
  33. }
  34.  
  35. public class CheckAndSetResult {
  36.     /**
  37.      * return value for checkAndSet
  38.      *
  39.      * @param setSucceed true if set value succeed.
  40.      * @param checkValueReturned true if the check value is returned.
  41.      * @param checkValueExist true if the check value is exist; can be used only when checkValueReturned is true.
  42.      * @param checkValue return the check value if exist; can be used only when checkValueExist is true.
  43.      */
  44.     boolean setSucceed;
  45.     boolean checkValueReturned;
  46.     boolean checkValueExist;
  47.     byte[] checkValue;
  48. }
  49.  
  50. /**
  51.  * Atomically check and set value by key.
  52.  * If the check condition is satisfied, then apply to set value.
  53.  *
  54.  * @param tableName    the table name.
  55.  * @param hashKey      the hash key to check and set.
  56.  * @param checkSortKey the sort key to check.
  57.  * @param checkType    the check type.
  58.  * @param checkOperand the check operand.
  59.  * @param setSortKey   the sort key to set value if check condition is satisfied.
  60.  * @param setValue     the value to set if check condition is satisfied.
  61.  * @param options      the check-and-set options.
  62.  * @return CheckAndSetResult
  63.  * @throws PException throws exception if any error occurs.
  64.  */
  65. public PegasusTableInterface.CheckAndSetResult checkAndSet(String tableName, byte[] hashKey, byte[] checkSortKey,
  66.                                                            CheckType checkType, byte[] checkOperand,
  67.                                                            byte[] setSortKey, byte[] setValue,
  68.                                                            CheckAndSetOptions options) throws PException;

注：

  • 参数：需传入TableName、HashKey、CheckSortKey、CheckType、CheckOperand、SetSortKey、SetValue、Options。
    • checkSortKey、checkType、checkOperand：用于指定检查的条件。
    • setSortKey、setValue：用于指定条件检查成功后要set的新值。
    • options：其他选项，包括：
      • setValueTTLSeconds：新值的TTL时间；0表示不设置TTL限制。
      • returnCheckValue：是否需要返回CheckSortKey对应的value。
  • 返回值：CheckAndSetResult，包括：
    • setSucceed：是否set成功。
    • checkValueReturned：是否返回了CheckSortKey对应的value。
    • checkValueExist：CheckSortKey对应的value是否存在；该域只有在checkValueReturned=true时有意义。
    • checkValue：CheckSortKey对应的value值；该域只有在checkValueExist=true时有意义。
  • 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，会抛出 PException。另外以下情况也会抛出异常：
    • 如果CheckType为int compare类型的操作，且CheckOperand或者CheckValue转换为int64时出错，譬如不是合法的数字或者超出int64范围。