Inclure Oracle Blockchain Platform dans les transactions distribuées globales

Votre application peut avoir besoin d'effectuer des mises à jour dans le registre Oracle Blockchain Platform et dans d'autres référentiels tels que des bases de données ou d'autres registres de chaîne de blocs de manière atomique, où toutes les mises à jour réussissent ou aucune.

Pour activer les mises à jour atomiques dans plusieurs bases de données, les développeurs utilisent des transactions globales coordonnées par des coordinateurs de transactions distribuées tels qu'Oracle WebLogic Server, Oracle Tuxedo, Oracle Transaction Manager for Microservices, JBoss Enterprise Application Platform, IBM WebSphere et d'autres systèmes. Tous ces systèmes s'appuient sur le protocole X/Open XA pour orchestrer un processus de validation en deux phases à l'aide d'API standard fournies par les gestionnaires de ressources XA pour chaque base de données ou autre ressource. Oracle Blockchain Platform prend en charge les validations en deux phases et fournit sa propre bibliothèque XA RM, que les coordinateurs de transactions externes peuvent utiliser pour appeler des API conformes à XA. Ces transactions globales peuvent également inclure une seule ressource non XA (par exemple, un registre de chaîne de blocs non Oracle ou une base de données non conforme XA) à l'aide d'une dernière optimisation de validation de ressource.

La spécification XA fait partie de l'architecture X/Open Distributed Transaction Processing, qui définit une architecture standard qui permet à plusieurs programmes d'application de partager les ressources fournies par plusieurs gestionnaires de ressources. L'interface Java XA elle-même est définie comme faisant partie de la plate-forme Java. Pour plus d'informations sur l'interface Java XA, reportez-vous à Interface XAResource dans la documentation Java.

Oracle Blockchain Platform fournit une bibliothèque conforme à la spécification XA et implémente l'interface Java standard pour un gestionnaire de ressources XA. La bibliothèque permet à un gestionnaire de transactions côté client de coordonner les transactions globales. Une transaction globale est une unité de travail unique qui peut inclure des opérations telles que les mises à jour de base de données et les transactions de chaîne de blocs, qui doivent toutes être validées atomiquement. En d'autres termes, toutes les opérations doivent réussir à être engagées. Si une opération qui fait partie de la transaction globale échoue, toutes les opérations sont annulées (rollback). L'interface XA repose sur le protocole de validation en deux phases, similaire au protocole pris en charge par les adresses REST de transactions atomiques. Pour plus d'informations sur les transactions atomiques dans Oracle Blockchain Platform, reportez-vous à Mise à jour atomique entre les codes chaîne et les canaux.

L'implémentation XA pour Oracle Blockchain Platform est fournie en tant que bibliothèque Java, téléchargeable à partir de l'onglet Outils de développement du panneau Développement d'applications de la console Oracle Blockchain Platform.

Les détails complets sur la bibliothèque sont inclus dans les informations Javadoc fournies dans le fichier téléchargeable. Les trois objets clés pris en charge par la bibliothèque sont OBPXAResource, OBPXADataSource et OBPXAConnection.

Objet	Description
`OBPXAResource`	Cette classe implémente les API requises pour qu'un gestionnaire de transactions coordonne les transactions avec Oracle Blockchain Platform en tant que gestionnaire de ressources pour les transactions XA.
`OBPXADataSource`	Utilisez cet objet pour obtenir une instance de `OBPXAConnection` et pour indiquer les informations d'identification d'authentification et d'autorisation.
`OBPXAConnection`	Utilisez cet objet pour obtenir une instance de l'objet `OBPXAResource` et pour définir les transactions de chaîne de blocs à exécuter dans le cadre d'une transaction XA.

Pour utiliser la bibliothèque XA avec Oracle Blockchain Platform, l'application doit fournir des informations d'identification pour l'authentification et l'autorisation des opérations demandées. La bibliothèque prend en charge à la fois l'authentification de base (utilisateur/mot de passe) et les jetons d'accès OAuth 2.0, que vous pouvez configurer lorsque vous créez l'instance OBPXADataSource. Les deux méthodes d'authentification sont cohérentes avec les méthodes d'authentification utilisées avec le proxy REST Oracle Blockchain Platform. Vous pouvez utiliser l'authentification de base à des fins de test et de développement interne. N'utilisez pas l'authentification de base dans les environnements de production. Pour plus d'informations, reportez-vous à Authentification dans la documentation de l'API REST.

Une fois que vous avez créé une instance OBPXADataSource, vous pouvez utiliser la méthode obpxaDataSource.getXAConnection() pour obtenir l'instance xaConnection. Pour mettre à jour l'authentification lors de l'utilisation de jetons d'accès OAuth 2.0, vous pouvez utiliser la méthode getXAConnection, comme indiqué dans le code suivant :

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

Vous pouvez également utiliser la méthode getXAConnection pour mettre à jour l'authentification de base.

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

Pour définir une transaction de chaîne de blocs à exécuter dans le cadre d'une transaction XA globale, utilisez la méthode suivante :

public void createXAInvokeTransaction(Xid xid, OBPXAInvokeTxRequest invokeTxRequest)

Dans cette méthode, xid est un identificateur de transaction global et invokeTxRequest est la transaction de chaîne de blocs à exécuter dans le cadre de la transaction XA globale. Pour créer une demande de transaction d'appel XA, vous utilisez la méthode de constructeur suivante :

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

Dans cette méthode de constructeur, channel est le canal sur lequel la transaction de chaîne de blocs sera exécutée, chaincode est le code chaîne à utiliser et args inclut la fonction de code chaîne et tous les arguments à utiliser pour la transaction.

Le fragment de code suivant montre comment créer un objet OBPXADataSource, obtenir l'instance OBPXAConnection, puis créer la demande de transaction et appeler la méthode 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);

Scénario : Explorer les transactions XA à l'aide d'échantillons

Le scénario suivant est similaire à celui décrit pour les transactions atomiques : Scénario : Explorer les transactions atomiques à l'aide d'échantillons, qui utilise les échantillons Transfert de solde et Marbres inclus dans Oracle Blockchain Platform.

Dans ce scénario, vous installez les exemples Balance Transfer et Marbles sur deux instances différentes d'Oracle Blockchain Platform. Chaque instance correspond alors à une source de données XA :

OBP-1 de ressource XA, avec le code chaîne Marbles installé sur le canal goods
OBP-2 de ressource XA, avec le code chaîne de transfert d'accumulateur installé sur le canal de portefeuille

Dans ce scénario, vous pouvez utiliser une transaction XA qui s'étend sur plusieurs sources de données pour vous assurer que l'échange de fonds et le transfert de marbre ont lieu de manière atomique, où toutes les opérations réussissent ou aucune n'aboutit. Le code suivant illustre ce scénario :

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