Transacciones

Leyendo el resultado

For everything you offer to a data holder, the offer method will yield a DataTransactionResult. This object will contain the following:

Tipo

El :javadoc: DataTransactionResult.Type indica si la transacción se completó con éxito y, de no ser así, cómo falló.

“” INDEFINIDO “”	Ningún resultado claro para la transacción - indica que algo salió mal
“” ÉXITO “”	La transacción se completó exitosamente
`` FALLO``	Transacción fallida por motivos esperados (por ejemplo, datos incompatibles)
“” ERROR””	Transacción fallida por razones inesperadas
“” CANCELADO “”	Un evento para esta transacción fue cancelado

Los datos afectados

El resultado también provee un par de listas inmutables con contenedores de valor inmutables que representan los datos que estuvieron involucrados en la transacción.

“” getSuccessfulData()””	contiene todos los datos que se establecieron con éxito
“” getReplacedData()””	contiene todos los datos que fueron reemplazados por datos configurados exitosamente
“” getRejectedData()””	contiene todos los datos que no se pudieron establecer

Ejemplos

Sanando a un jugador

Seguramente recuerdas el ejemplo de curación en la página :doc: keys. Imagina que un jugador que tiene menos de la mitad de un corazón (lo que equivale a 1 salud) se cura de esa manera. El DataTransactionResult en ese caso se vería así:

• `` getType () `` devolvería `` SUCCESS``

• `` getRejectedData () `` sería una lista vacía

• `` getReplacedData () `` contendría un contenedor de valores para la clave `` Keys.HEALTH`` con un valor de 1.0

• getSuccessfulData () contendría un contenedor de valor para la clave Keys.HEALTH` con un valor de 20.0

Ahora, ¿qué sería diferente si usáramos el ejemplo de curación de la página :doc: datamanipulators en su lugar? Como el manipulador de datos :javadoc: HealthData contiene valores para la salud actual y la máxima, además del resultado anterior, tanto la lista` getReplacedData () como la lista getSuccessfulData () contendrían un elemento más: un contenedor de valor para la clave ` Keys.MAX_HEALTH`` con un valor de 20.0.

Ofreciendo HealthData a un bloque de piedra

Ahora nuestros ejemplos mencionados anteriormente están codificados de tal manera que fallarán en lugar de tratar de ofrecer los datos incompatibles. Pero imagina que tomamos un `` HealthData`` de un jugador (completamente sanado) e intentamos ofrecerlo al :javadoc: Location del bloque de piedra en el que se encuentra actualmente. Podemos hacer esto, ya que `` Location`` también es un soporte de datos. Y si lo hacemos, nos recompensaría con un `` DataTransactionResult`` como este:

• `` getType () `` devolvería `` FAILURE``

• `` getRejectedData () `` contendría dos contenedores de valores para las claves `` HEALTH`` y `` MAX_HEALTH``, cada una con un valor de 20.0

• `` getReplacedData () `` y `` getSuccessfulData () `` serían listas vacías

Revertir transacciones

Como todo sobre un resultado de transacción es inmutable, puede servir para la documentación de cambios de datos. Y también permite deshacer esos cambios en los documentos. Para eso, simplemente pase el resultado de la transacción por el método `` undo () `` del titular de los datos. Esto es particularmente útil desde que algunas ofertas de datos pueden ser parcialmente exitosas, por ello uno o más valores se escriben exitosamente en el titular de los datos, sin embargo, no se puede aceptar un valor más. Dado que es posible que desee deshacer los éxitos parciales.

** Ejemplo de código: revertir una transacción **

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);
    }
}