在全球分散式交易中包含 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 文件中的 Interface 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 交易中執行的區塊鏈交易。

若要將 XA 程式庫與 Oracle Blockchain Platform 搭配使用，應用程式必須提供認證和授權要求之作業的證明資料。此程式庫支援基本認證 (使用者 / 密碼) 和 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 是全域交易識別碼，而 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 和 Marble 範例。然後，每個實例對應到一個 XA 資料來源：

XA 資源 OBP-1，其中大理石鏈碼已安裝在商品通道上
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