局部事务

简单场景：读-写场景

当需要进行读取-修改-写回（Read-Modify-Write）操作时，您可以选择如下两种方式，但这两种方式有一些限制。

• 条件更新：只能处理单行单次请求，不能处理数据分布在多行或者需要多次写入的情况。更多信息，请参见条件更新。

• 原子计数器：只能处理单行单次请求，且只能进行列值的累加操作。更多信息，请参见原子计数器。

为了解决上述问题，您可以使用局部事务功能实现一个分区键值范围内的通用读取-修改-写回流程。

1. 使用StartLocalTransaction接口为分区键值创建一个局部事务，并获取局部事务ID。

2. 使用GetRow或GetRange接口获取数据，且在请求中需要带上局部事务ID。

3. 在客户端本地修改数据。

4. 使用PutRow、UpdateRow、DeleteRow或BatchWriteRow接口将修改后的数据写回，且在请求中需要带上事务ID。

5. 使用CommitTransaction提交局部事务。

复杂场景：邮箱场景

使用局部事务功能，您可以实现对同一个用户邮件的原子操作。

为了能正常使用局部事务功能，在一张数据表上创建两张索引表，其主键列请参见下表。下表中使用Type列区分数据表和不同的索引表，不同的索引行使用IndexField列保存不同含义的字段，而数据表无IndexField列。

在邮箱场景中，使用局部事务功能可以完成如下使用场景。

使用局部事务写入一行数据

以下示例用于为表的指定分区键创建一个局部事务后，在局部事务内写入一行数据。

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);
}