checkAndMutate

checkAndMutate是checkAndSet的扩展版本：checkAndSet只允许set一个值，而checkAndMutate允许在单个原子操作中set或者del多个值。该接口从1.11.0版本开始提供。

为此，我们提供了一个包装类Mutations，用户可以预先设置需要实施的set或者del操作。

  1. class CheckAndMutateResult {
  2. /**
  3.  * return value for checkAndMutate
  4.  *
  5.  * @param mutateSucceed true if mutate succeed.
  6.  * @param checkValueReturned true if the check value is returned.
  7.  * @param checkValueExist true if the check value is exist; can be used only when
  8.  *     checkValueReturned is true.
  9.  * @param checkValue return the check value if exist; can be used only when checkValueExist is
  10.  *     true.
  11.  */
  12. public boolean mutateSucceed;
  13.  
  14. public boolean checkValueReturned;
  15. public boolean checkValueExist;
  16. public byte[] checkValue;
  17. }
  18.  
  19. /**
  20. * atomically check and mutate by key, async version. if the check condition is satisfied, then
  21. * apply to mutate.
  22. *
  23. * @param hashKey the hash key to check and mutate.
  24. * @param checkSortKey the sort key to check.
  25. * @param checkType the check type.
  26. * @param checkOperand the check operand.
  27. * @param mutations the list of mutations to perform if check condition is satisfied.
  28. * @param options the check-and-mutate options.
  29. * @param timeout how long will the operation timeout in milliseconds. if timeout > 0, it is a
  30. *     timeout value for current op, else the timeout value in the configuration file will be
  31. *     used.
  32. * @return the future for current op
  33. *     <p>Future return: On success: return CheckAndMutateResult. On failure: a throwable, which
  34. *     is an instance of PException
  35. *     <p>Thread safety: All the listeners for the same table are guaranteed to be dispatched in
  36. *     the same thread, so all the listeners for the same future are guaranteed to be executed as
  37. *     the same order as the listeners added. But listeners for different tables are not
  38. *     guaranteed to be dispatched in the same thread.
  39. */
  40. Future<CheckAndMutateResult> asyncCheckAndMutate(
  41.   byte[] hashKey,
  42.   byte[] checkSortKey,
  43.   CheckType checkType,
  44.   byte[] checkOperand,
  45.   Mutations mutations,
  46.   CheckAndMutateOptions options,
  47.   int timeout /*ms*/);

注：

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