Transactions

Lire les résultats

Pour tout ce que vous offrez à un data holder, la méthode offer donnera un DataTransactionResult. Cet objet contiendra ce qui suit:

Type

Le DataTransactionResult.Type indique si la transaction s’est faite avec succès ou si elle a échoué.

UNDEFINED

Aucun résultat clair de la transaction - indique que quelque s’est mal passé

SUCCESS

La transaction a été effectuée avec succès

FAILURE

La transaction a échoué pour des raisons connues (ex. données incompatibles)

ERROR

La transaction a échoué pour des raison inconnues

CANCELLED

Un event pour cette transaction a été annulé

Les Données affectées

Le résultat fournit aussi quelques listes immuables qui contiennent des valeurs immuables représentant des données qui ont été impliquées dans la transaction.

successfulData() | contains all data that was successfully set

replacedData() | contains all data that got replaced by successfully set data

rejectedData() | contains all data that could not be set

Exemples

Soigner un Joueur

Vous vous souvenez surement de l’exemple du healing de la page Utilisation des Clés. Imaginez qu’un joueur qui est descendu à un demi-cœur (qui équivaut à 1 point de vie) est soigné de cette façon. Le DataTransactionResult dans ce cas là, devrais ressembler à ça:

  • getType() devrait retourner SUCCESS

  • getRejectedData() devrait donner une liste vide

  • getReplacedData() devrait retourner un conteneur de valeur pour Keys.HEALTH avec une valeur de 1.0

  • getSuccessfulData() devrait contenir un conteneur de valeur pour Keys.HEALTH avec une valeur de 20.0

Now what would be different if we used the healing example from the Données Customisées page instead? Since the HealthData data manipulator contains values for both the current and the maximum health, in addition to the above result, both the getReplacedData() list and the getSuccessfulData() list would contain one more element: A value container for the Keys.MAX_HEALTH key with a value of 20.0.

Donner un HealthData à un block de stone

Maintenant nos exemples mentionnés ci-dessus sont codés de telle manière qu’ils vont échouer silencieusement plutôt que d’essayer d’offrir les données incompatibles. Mais imaginez que nous prenons la HealthData d’un joueur (guéri complètement) et essayons de l’offrir à la Location du bloc de pierre sur lequel il se trouve actuellement. Nous pouvons faire ceci, puisque Location est aussi un data holder. Et si nous le faisons, il nous récompenserait avec un DataTransactionResult comme ceci :

  • getType() retournerait FAILURE

  • getRejectedData() retournerait deux conteneurs de valeurs pour les clés HEALTH et MAX_HEALTH, avec chacune une valeur de 20.0

  • getReplacedData() et getSuccessfulData() seraient des listes vides

Rétablir une Transaction

Puisque tout sur le résultat de la transaction est immutable, il peut servir pour la documentation des modications de données. Et il permet également à ces modifications qu’il documente d’être annulées. Pour cela, passez simplement un résultat de transaction à la méthode undo() du data holder. C’est particulièrement utile puisque certaines offres de données peuvent être partiellement réussies, de sorte qu’une ou plusieurs valeurs soient correctement écrites au data holder, mais une valeur ou plus ne peuvent pas être acceptées. Étant donné que vous pouvez annuler les succès partiels.

Exemple de Code : Annuler une transaction

import org.spongepowered.api.data.DataHolder;
import org.spongepowered.api.data.DataTransactionResult;
import org.spongepowered.api.data.manipulator.DataManipulator;

public void safeOffer(DataHolder target, DataManipulator data) {
    DataTransactionResult result = target.offer(data);
    if (result.getType() != DataTransactionResult.Type.SUCCESS) {
        target.undo(result);
    }
}