局部事务

前提条件

• 已初始化OTSClient。具体操作，请参见初始化OTSClient。

• 已创建数据表并写入数据。

使用方法

1. 使用StartLocalTransaction在指定的分区键值创建一个局部事务，并获取局部事务ID。

2. 对局部事务范围内的数据进行读写操作。

   支持对局部事务进行操作的接口为GetRow、PutRow、DeleteRow、UpdateRow、BatchWriteRow和GetRange。

3. 使用CommitTransaction提交局部事务或者使用AbortTransaction丢弃局部事务。

注意事项

• 主键自增列功能和局部事务功能不能同时使用。

• 局部事务通过悲观锁（Pessimistic Lock）实现并发控制。

• 每个局部事务从创建开始生命周期最长为60秒。

  如果超过60秒未提交局部事务或丢弃局部事务，则表格存储服务端会认为此局部事务超时，并将局部事务丢弃。

• 如果创建局部事务时超时，则请求可能在表格存储服务端已执行成功，此时请等待该局部事务超时后重新创建。

• 未提交的局部事务可能会失效，如果出现此情况，则需要重试该局部事务内的操作。

• 如果未对局部事务范围内的数据进行写操作，则提交局部事务或丢弃局部事务的操作是等同的。

• 在局部事务中读写数据有如下限制：

  • 不能使用局部事务ID访问局部事务范围（即创建时使用的分区键值）以外的数据。

  • 同一个局部事务中所有写请求的分区键值必须与创建局部事务时的分区键值相同，读请求则无此限制。

  • 一个局部事务同时只能用于一个请求中，在使用局部事务期间，其他使用此局部事务ID的操作均会失败。

  • 每个局部事务中两次读写操作的最大间隔为60秒。

    如果超过60秒未操作局部事务，则表格存储服务端会认为此局部事务超时，并将局部事务丢弃。

  • 每个局部事务中写入的数据量最大为4 MB，按正常的写请求数据量计算规则累加。

  • 如果在局部事务中写入了未指定版本号的Cell，则该Cell的版本号会在写入数据时（而非提交局部事务时）由表格存储服务端自动生成，生成规则与正常写入一个未指定版本号的Cell相同。

  • 如果BatchWriteRow请求中带有局部事务ID，则此请求中所有行只能操作该局部事务ID对应的表。

  • 在使用局部事务期间，对应分区键值的数据会被加上写锁，只有持有局部事务ID在局部事务范围内的写请求才会成功。其他非事务请求或持有其他局部事务ID在局部事务范围内的写请求均会失败。在局部事务提交、丢弃或超时后，对应的锁也会被释放。

  • 带有局部事务ID的读写请求失败不会影响局部事务本身的存活情况，您可以指定重试规则进行重试或者主动丢弃当前局部事务。

参数

示例

private static void transactionPutRow(SyncClient client) {
    //设置数据表名称。
    String tableName="<TABLE_NAME>";
    //使用指定分区键值创建一个局部事务。 
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //设置第一个主键（即分区键）的列名、数据类型和列值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    //构造创建局部事务的请求。
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    //发起创建局部事务的请求并获取局部事务ID。
    String txnId = client.startLocalTransaction(request).getTransactionID();
    
    //在局部事务内写入一行数据。
    //构造行的主键信息。
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //设置主键的列名、数据类型和列值。如果表的主键由多个主键列组成，则多个主键列需要按照顺序依次进行配置。
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    //构造行的属性列。
    RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey1);
    //设置属性列的列名、数据类型和列值，请根据需要添加所需属性列。
    rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("colvalue")));
    rowPutChange.addColumn(new Column("col2", ColumnValue.fromLong(10)));
    PutRowRequest request1 = new PutRowRequest(rowPutChange);
    //设置局部事务ID到请求中。
    request1.setTransactionId(txnId);
    client.putRow(request1);
    
    //提交或丢弃局部事务。 
    //提交局部事务，使局部事务中的所有数据修改生效。
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    //丢弃局部事务，局部事务中的所有数据修改均不会应用到原有数据。
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
}

private static void transactionGetRow(SyncClient client) {
    //设置数据表名称。
    String tableName="exampletabled";
    //使用指定分区键值创建一个局部事务。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //设置第一个主键（即分区键）的列名、数据类型和列值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    //构造创建局部事务的请求。
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    //发起创建局部事务的请求并获取局部事务ID。
    String txnId = client.startLocalTransaction(request).getTransactionID();

    //在局部事务内读取一行数据。
    //构造行的主键信息。
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //设置主键的列名、数据类型和列值。如果表的主键由多个主键列组成，则多个主键列需要按照顺序依次进行配置。
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey1);
    //设置读取最新版本的数据。
    criteria.setMaxVersions(1);
    GetRowRequest request1 = new GetRowRequest(criteria);
    //设置局部事务ID到请求中。
    request1.setTransactionId(txnId);
    GetRowResponse getRowResponse = client.getRow(request1);
  
    //提交或丢弃局部事务。对于读操作来说，提交局部事务或丢弃局部事务的操作是等同的。
    //提交局部事务，使局部事务中的所有数据修改生效。
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    //丢弃局部事务，局部事务中的所有数据修改均不会应用到原有数据。
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
    
    //获取并打印行数据。
    Row row = getRowResponse.getRow();
    System.out.println("读取完毕，结果为：");
    System.out.println(row);
}

相关文档

如果要在局部事务内进行批量写入、范围读取等操作，请在创建局部事务后，使用写入数据或者读取数据文档中的相应操作示例以及在请求中带上局部事务ID实现。