前提條件

• 已初始化OTSClient。具體操作，請(qǐng)參見(jiàn)初始化OTSClient。

• 已創(chuàng)建數(shù)據(jù)表并寫入數(shù)據(jù)。

使用方法

1. 使用StartLocalTransaction在指定的分區(qū)鍵值創(chuàng)建一個(gè)局部事務(wù)，并獲取局部事務(wù)ID。

2. 對(duì)局部事務(wù)范圍內(nèi)的數(shù)據(jù)進(jìn)行讀寫操作。

   支持對(duì)局部事務(wù)進(jìn)行操作的接口為GetRow、PutRow、DeleteRow、UpdateRow、BatchWriteRow和GetRange。

3. 使用CommitTransaction提交局部事務(wù)或者使用AbortTransaction丟棄局部事務(wù)。

注意事項(xiàng)

• 主鍵自增列功能和局部事務(wù)功能不能同時(shí)使用。

• 局部事務(wù)通過(guò)悲觀鎖（Pessimistic Lock）實(shí)現(xiàn)并發(fā)控制。

• 每個(gè)局部事務(wù)從創(chuàng)建開(kāi)始生命周期最長(zhǎng)為60秒。

  如果超過(guò)60秒未提交局部事務(wù)或丟棄局部事務(wù)，則表格存儲(chǔ)服務(wù)端會(huì)認(rèn)為此局部事務(wù)超時(shí)，并將局部事務(wù)丟棄。

• 如果創(chuàng)建局部事務(wù)時(shí)超時(shí)，則請(qǐng)求可能在表格存儲(chǔ)服務(wù)端已執(zhí)行成功，此時(shí)請(qǐng)等待該局部事務(wù)超時(shí)后重新創(chuàng)建。

• 未提交的局部事務(wù)可能會(huì)失效，如果出現(xiàn)此情況，則需要重試該局部事務(wù)內(nèi)的操作。

• 如果未對(duì)局部事務(wù)范圍內(nèi)的數(shù)據(jù)進(jìn)行寫操作，則提交局部事務(wù)或丟棄局部事務(wù)的操作是等同的。

• 在局部事務(wù)中讀寫數(shù)據(jù)有如下限制：

  • 不能使用局部事務(wù)ID訪問(wèn)局部事務(wù)范圍（即創(chuàng)建時(shí)使用的分區(qū)鍵值）以外的數(shù)據(jù)。

  • 同一個(gè)局部事務(wù)中所有寫請(qǐng)求的分區(qū)鍵值必須與創(chuàng)建局部事務(wù)時(shí)的分區(qū)鍵值相同，讀請(qǐng)求則無(wú)此限制。

  • 一個(gè)局部事務(wù)同時(shí)只能用于一個(gè)請(qǐng)求中，在使用局部事務(wù)期間，其他使用此局部事務(wù)ID的操作均會(huì)失敗。

  • 每個(gè)局部事務(wù)中兩次讀寫操作的最大間隔為60秒。

    如果超過(guò)60秒未操作局部事務(wù)，則表格存儲(chǔ)服務(wù)端會(huì)認(rèn)為此局部事務(wù)超時(shí)，并將局部事務(wù)丟棄。

  • 每個(gè)局部事務(wù)中寫入的數(shù)據(jù)量最大為4 MB，按正常的寫請(qǐng)求數(shù)據(jù)量計(jì)算規(guī)則累加。

  • 如果在局部事務(wù)中寫入了未指定版本號(hào)的Cell，則該Cell的版本號(hào)會(huì)在寫入數(shù)據(jù)時(shí)（而非提交局部事務(wù)時(shí)）由表格存儲(chǔ)服務(wù)端自動(dòng)生成，生成規(guī)則與正常寫入一個(gè)未指定版本號(hào)的Cell相同。

  • 如果BatchWriteRow請(qǐng)求中帶有局部事務(wù)ID，則此請(qǐng)求中所有行只能操作該局部事務(wù)ID對(duì)應(yīng)的表。

  • 在使用局部事務(wù)期間，對(duì)應(yīng)分區(qū)鍵值的數(shù)據(jù)會(huì)被加上寫鎖，只有持有局部事務(wù)ID在局部事務(wù)范圍內(nèi)的寫請(qǐng)求才會(huì)成功。其他非事務(wù)請(qǐng)求或持有其他局部事務(wù)ID在局部事務(wù)范圍內(nèi)的寫請(qǐng)求均會(huì)失敗。在局部事務(wù)提交、丟棄或超時(shí)后，對(duì)應(yīng)的鎖也會(huì)被釋放。

  • 帶有局部事務(wù)ID的讀寫請(qǐng)求失敗不會(huì)影響局部事務(wù)本身的存活情況，您可以指定重試規(guī)則進(jìn)行重試或者主動(dòng)丟棄當(dāng)前局部事務(wù)。

參數(shù)

示例

private static void transactionPutRow(SyncClient client) {
    //設(shè)置數(shù)據(jù)表名稱。
    String tableName="<TABLE_NAME>";
    //使用指定分區(qū)鍵值創(chuàng)建一個(gè)局部事務(wù)。 
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設(shè)置第一個(gè)主鍵（即分區(qū)鍵）的列名、數(shù)據(jù)類型和列值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    //構(gòu)造創(chuàng)建局部事務(wù)的請(qǐng)求。
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    //發(fā)起創(chuàng)建局部事務(wù)的請(qǐng)求并獲取局部事務(wù)ID。
    String txnId = client.startLocalTransaction(request).getTransactionID();
    
    //在局部事務(wù)內(nèi)寫入一行數(shù)據(jù)。
    //構(gòu)造行的主鍵信息。
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設(shè)置主鍵的列名、數(shù)據(jù)類型和列值。如果表的主鍵由多個(gè)主鍵列組成，則多個(gè)主鍵列需要按照順序依次進(jìn)行配置。
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    //構(gòu)造行的屬性列。
    RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey1);
    //設(shè)置屬性列的列名、數(shù)據(jù)類型和列值，請(qǐng)根據(jù)需要添加所需屬性列。
    rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("colvalue")));
    rowPutChange.addColumn(new Column("col2", ColumnValue.fromLong(10)));
    PutRowRequest request1 = new PutRowRequest(rowPutChange);
    //設(shè)置局部事務(wù)ID到請(qǐng)求中。
    request1.setTransactionId(txnId);
    client.putRow(request1);
    
    //提交或丟棄局部事務(wù)。 
    //提交局部事務(wù)，使局部事務(wù)中的所有數(shù)據(jù)修改生效。
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    //丟棄局部事務(wù)，局部事務(wù)中的所有數(shù)據(jù)修改均不會(huì)應(yīng)用到原有數(shù)據(jù)。
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
}

private static void transactionGetRow(SyncClient client) {
    //設(shè)置數(shù)據(jù)表名稱。
    String tableName="exampletabled";
    //使用指定分區(qū)鍵值創(chuàng)建一個(gè)局部事務(wù)。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設(shè)置第一個(gè)主鍵（即分區(qū)鍵）的列名、數(shù)據(jù)類型和列值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    //構(gòu)造創(chuàng)建局部事務(wù)的請(qǐng)求。
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    //發(fā)起創(chuàng)建局部事務(wù)的請(qǐng)求并獲取局部事務(wù)ID。
    String txnId = client.startLocalTransaction(request).getTransactionID();

    //在局部事務(wù)內(nèi)讀取一行數(shù)據(jù)。
    //構(gòu)造行的主鍵信息。
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設(shè)置主鍵的列名、數(shù)據(jù)類型和列值。如果表的主鍵由多個(gè)主鍵列組成，則多個(gè)主鍵列需要按照順序依次進(jìn)行配置。
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey1);
    //設(shè)置讀取最新版本的數(shù)據(jù)。
    criteria.setMaxVersions(1);
    GetRowRequest request1 = new GetRowRequest(criteria);
    //設(shè)置局部事務(wù)ID到請(qǐng)求中。
    request1.setTransactionId(txnId);
    GetRowResponse getRowResponse = client.getRow(request1);
  
    //提交或丟棄局部事務(wù)。對(duì)于讀操作來(lái)說(shuō)，提交局部事務(wù)或丟棄局部事務(wù)的操作是等同的。
    //提交局部事務(wù)，使局部事務(wù)中的所有數(shù)據(jù)修改生效。
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    //丟棄局部事務(wù)，局部事務(wù)中的所有數(shù)據(jù)修改均不會(huì)應(yīng)用到原有數(shù)據(jù)。
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
    
    //獲取并打印行數(shù)據(jù)。
    Row row = getRowResponse.getRow();
    System.out.println("讀取完畢，結(jié)果為：");
    System.out.println(row);
}

相關(guān)文檔

如果要在局部事務(wù)內(nèi)進(jìn)行批量寫入、范圍讀取等操作，請(qǐng)?jiān)趧?chuàng)建局部事務(wù)后，使用寫入數(shù)據(jù)或者讀取數(shù)據(jù)文檔中的相應(yīng)操作示例以及在請(qǐng)求中帶上局部事務(wù)ID實(shí)現(xiàn)。