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é.
|
Aucun résultat clair de la transaction - indique que quelque s’est mal passé |
|
La transaction a été effectuée avec succès |
|
La transaction a échoué pour des raisons connues (ex. données incompatibles) |
|
La transaction a échoué pour des raison inconnues |
|
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.
|
contient toutes les données qui ont été correctement définies |
|
contient toutes les données qui ont été remplacées par des données assignées avec succès |
|
contient toutes les données qui n’ont pas pu être définies |
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 retournerSUCCESS
getRejectedData()
devrait donner une liste videgetReplacedData()
devrait retourner un conteneur de valeur pourKeys.HEALTH
avec une valeur de 1.0getSuccessfulData()
devrait contenir un conteneur de valeur pourKeys.HEALTH
avec une valeur de 20.0
Maintenant qu’est-ce qui serait différent si nous utilisions l’exemple de healing de la page Manipulateurs de données à la place ? Puisque que le manipulateur de données HealthData contient des valeurs pour le niveau de vie actuel et la vie maximale, en plus du résultat ci-dessus, la liste getReplacedData()
et la liste getSuccessfulData()
devraient contenir un élément de plus: Un conteneur de valeurs pour Keys.MAX_HEALTH
avec une valeur de 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()
retourneraitFAILURE
getRejectedData()
retournerait deux conteneurs de valeurs pour les clésHEALTH
etMAX_HEALTH
, avec chacune une valeur de 20.0getReplacedData()
etgetSuccessfulData()
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);
}
}