局部事务

简单场景：读-写场景

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

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

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

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

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

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

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

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

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

复杂场景：邮箱场景

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

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

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

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

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

String tableName = "local_tx_demo";

// 1. 为指定分区键值创建局部事务，获取事务 ID
PrimaryKeyBuilder pkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
PrimaryKey partitionKey = pkBuilder.build();

StartLocalTransactionRequest startRequest =
        new StartLocalTransactionRequest(tableName, partitionKey);
String txnId = client.startLocalTransaction(startRequest).getTransactionID();

// 2. 在事务内写入一行数据，需指定完整主键并携带事务 ID
PrimaryKeyBuilder rowKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
rowKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
rowKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
PrimaryKey rowKey = rowKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, rowKey);
rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("colvalue")));
rowPutChange.addColumn(new Column("col2", ColumnValue.fromLong(10)));

PutRowRequest putRequest = new PutRowRequest(rowPutChange);
putRequest.setTransactionId(txnId);
client.putRow(putRequest);

// 3. 提交事务使所有写入生效；如需放弃修改，调用 abortTransaction()
CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
client.commitTransaction(commitRequest);

使用局部事务读取一行数据

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

String tableName = "local_tx_demo";

// 1. 为指定分区键值创建局部事务
PrimaryKeyBuilder pkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
PrimaryKey partitionKey = pkBuilder.build();

StartLocalTransactionRequest startRequest =
        new StartLocalTransactionRequest(tableName, partitionKey);
String txnId = client.startLocalTransaction(startRequest).getTransactionID();

// 2. 在事务内读取一行数据，需指定完整主键并携带事务 ID
PrimaryKeyBuilder rowKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
rowKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
rowKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
PrimaryKey rowKey = rowKeyBuilder.build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, rowKey);
criteria.setMaxVersions(1);

GetRowRequest getRequest = new GetRowRequest(criteria);
getRequest.setTransactionId(txnId);
GetRowResponse getResponse = client.getRow(getRequest);

// 3. 提交或丢弃事务。对于只读事务，两者效果相同，均会释放事务
CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
client.commitTransaction(commitRequest);

Row row = getResponse.getRow();
System.out.println(row);