在全球分散式交易中包含 Oracle Blockchain Platform

您的應用程式可能需要以單元方式對 Oracle Blockchain Platform 分類帳和其他儲存區域 (例如資料庫或其他區塊鏈分類帳) 進行更新，所有更新都成功或完全不執行。

為了跨多個資料庫啟用單元更新，開發人員使用由分散式交易協調器協調的全域交易，例如 Oracle WebLogic Server、Oracle Tuxedo、Oracle Transaction Manager for Microservices、JBoss Enterprise Application Platform、IBM WebSphere 及其他系統。所有這些系統都仰賴 X/Open XA 協定，使用 XA 資源管理程式 (RM) 針對每個資料庫或其他資源提供的標準 API，協調兩階段確認處理作業。Oracle Blockchain Platform 支援兩階段確認，並提供自己的 XA RM 程式庫，外部交易協調器可用來呼叫 XA 相容 API。這些全球交易也可以使用上次的資源確認最佳化，包含單一非 XA 資源 (例如，非 Oracle 區塊鏈分類帳或非 XA 相容資料庫)。

XA 規格是「X/Open 分散式交易處理」架構的一部分，其定義了標準架構，可讓多個應用程式共用由多個資源管理程式提供的資源。Java XA 介面本身定義為 Java 平台的一部分。如需有關 Java XA 介面的詳細資訊，請參閱 Java 文件中的介面 XAResource 。

Oracle Blockchain Platform 提供符合 XA 規格的程式庫，並導入 XA 資源管理程式的標準 Java 介面。此程式庫可讓從屬端交易管理程式協調全域交易。全球交易是單一工作單位，其中可能包括資料庫更新和區塊鏈交易等作業，這些全部都必須以原子方式確認。換句話說，所有作業都必須成功確認。如果任何屬於全域交易的作業失敗，則會倒回所有作業。XA 介面使用兩階段確認協定，類似於單元交易 REST 端點支援的協定。如需有關 Oracle Blockchain Platform 中單元交易的詳細資訊，請參閱跨鏈碼和通道進行單元更新。

Oracle Blockchain Platform 的 XA 實作是以 Java 程式庫的形式提供，可從 Oracle Blockchain Platform 主控台之應用程式開發窗格的開發人員工具頁籤下載。

程式庫的完整詳細資訊包含在可下載檔案中提供的 Javadoc 資訊中。程式庫支援的三個主要物件為 OBPXAResource、OBPXADataSource 和 OBPXAConnection。

物件	目的
`OBPXAResource`	這個類別為交易管理程式實行必要的 API，以與 Oracle Blockchain Platform 協調，作為 XA 交易的資源管理程式。
`OBPXADataSource`	您可以使用此物件取得 `OBPXAConnection` 的執行處理，以及指定認證和授權證明資料。
`OBPXAConnection`	使用此物件取得 `OBPXAResource` 物件的實例，並定義要作為 XA 交易一部分執行的區塊鏈交易。

若要在 Oracle Blockchain Platform 使用 XA 程式庫，應用程式必須提供認證和要求之作業授權的證明資料。此程式庫支援基本認證 (使用者 / 密碼) 和 OAuth 2.0 存取記號，您可以在建立 OBPXADataSource 執行處理時設定此記號。這兩種驗證方法與您搭配 Oracle Blockchain Platform REST 代理主機使用的驗證方法一致。您可以使用基本認證來進行測試和內部開發。請勿在生產環境中使用基本認證。如需詳細資訊，請參閱 REST API 文件中的認證。

建立 OBPXADataSource 執行處理之後，您可以使用 obpxaDataSource.getXAConnection() 方法來取得 xaConnection 執行處理。若要在使用 OAuth 2.0 存取記號時更新認證，您可以使用 getXAConnection 方法，如下列程式碼所示：

OBPXAConnection xaConnection = obpxaDataSource.getXAConnection(accessToken);      // get an XA connection using an OAuth 2.0 access token

您也可以使用 getXAConnection 方法來更新基本認證。

OBPXAConnection xaConnection = obpxaDataSource.getXAConnection(user, password);   // get an XA connection using username and password for basic authentication

若要定義要作為全域 XA 交易一部分執行的區塊鏈交易，請使用下列方法：

public void createXAInvokeTransaction(Xid xid, OBPXAInvokeTxRequest invokeTxRequest)

在此方法中，xid 是全域交易 ID，而 invokeTxRequest 是要在全域 XA 交易中一併執行的區塊鏈交易。如果要建立 XA 呼叫交易要求，您可以使用下列建構子方法：

OBPXAInvokeTxRequest invokeTxRequest = new OBPXAInvokeTxRequest(channel, chaincode, args);

在此建構子方法中，channel 是執行區塊鏈交易的通道，chaincode 是要使用的鏈碼，args 包含鏈碼函數和任何用於交易的引數。

下列程式碼片段示範建立 OBPXADataSource 物件、取得 OBPXAConnection 執行處理，然後建立交易要求並呼叫 createXAInvokeTransaction 方法。

OBPXADataSource obpxaDataSource = OBPXADataSource.builder()
                        .withHost(host)
                        .withPort(port)
                        .withBasicAuth(username, password)
                        .withRole(role)
                        .build();
.
.
.
OBPXAConnection obpxaConnection = obpxaDataSource.getXAConnection();

OBPXAInvokeTxRequest invokeTxRequest = new OBPXAInvokeTxRequest(channel, chaincode, args);
invokeTxRequest.setEndorsers(endorsersArray); // optional blockchain transaction request attributes
invokeTxRequest.setTransientMap(transientMap); // optional blockchain transaction request attributes
invokeTxRequest.setTimeout(60000); // optional blockchain transaction request attributes

obpxaConnection.createXAInvokeTransaction(xid, invokeTxRequest);

案例：使用樣本瀏覽 XA 交易

下列案例與針對單元交易所說明的案例類似：案例：使用範例探索單元交易，此範例使用 Oracle Blockchain Platform 隨附的「餘額轉移」和「大理石」範例。

在此案例中，您可以在 Oracle Blockchain Platform 的兩個不同實例上安裝 Balance Transfer 和 Marbles 範例。每個實例接著會對應至 XA 資料來源：

XA 資源 OBP-1，Marble 鏈碼安裝在貨品通道上
XA 資源 OBP-2，其「餘額移轉」鏈碼已安裝在公事包通道上

在此案例中，您可以使用跨多個資料來源的 XA 交易，確保資金與大理石傳輸的交換是以單元方式進行，所有的作業都成功或完全不成功。下列程式碼說明此方案：

OBPXADataSource obpxaDS1 = ... // create an XA data source, supplying details about the OBP-1 instance
OBPXADataSource obpxaDS2 = ... // create an XA data source, supplying details about the OBP-2 instance

// start a global transaction in the client application
// invoke marble transfer on OBP-1
OBPXAConnection obpxaConn1 = (OBPXAConnection) obpxaDS1.getXAConnection();
OBPXAInvokeTxRequest invokeMarbleTransferReq = new OBPXAInvokeTxRequest("goods", "obcs-marbles", new String[]{"transferMarble", "marble1", "tom"});
obpxaConn1.createXAInvokeTransaction(xid1, invokeMarbleTransferReq);
.
.
.
// invoke fund transfer on OBP-2
OBPXAConnection obpxaConn2 = (OBPXAConnection) obpxaDS2.getXAConnection();
OBPXAInvokeTxRequest invokeBalanceTransferReq = new OBPXAInvokeTxRequest("wallet", "obcs-example02", new String[]{"invoke", "a", "b", "50"});
obpxaConn2.createXAInvokeTransaction(xid2, invokeBalanceTransferReq);
.
.
.
// end the global transaction in the client application