Sérialisation de données

Avertissement

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

While an DataManipulator#Immutable is a good way to store data while the server is running, it will not persist over a restart. However, every DataManipulator implements the DataSerializable interface and thus can be serialized to a DataContainer and deserialized by a DataBuilder.

Après cette conversion initiale depuis le DataManipulator spécialisé vers une structure plus générale, le DataContainer peut être traité ultérieurement.

DataContainer et DataView

Un DataView est une structure polyvalente pour tenir tout type de données. Il supporte plusieurs valeurs et même imbriquer DataViews comme valeur, ce qui permet une structure arborescente. Chaque valeur est identifée par un DataQuery. Un DataContainer est un DataView racine.

DataFormat

DataFormat allows you to store a DataContainer in HOCON, JSON or NBT format. You can also recreate DataContainers using DataFormats. Sponge provided DataFormat implementations are available in the DataFormats class.

Par exemple, nous pouvons utiliser le DataFormat DataFormats#JSON qui nous permet de créer une représentation JSON d’un DataContainer. Le JSON en sortie peut ensuite être facilemeent stocké dans une base de données. Nous pouvons alors utiliser le même DataFormat pour recréer le DataContainer original à partir de ce JSON lorsque c’est nécessaire.

Imports pour les exemples de code

import org.spongepowered.api.Sponge;
import org.spongepowered.api.data.DataContainer;
import org.spongepowered.api.data.persistence.DataFormats;
import org.spongepowered.api.item.inventory.ItemStackSnapshot;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Optional;

Exemple de Code : Sérialiser un ItemStackSnapshot au format JSON

String json = DataFormats.JSON.write(itemStack.toContainer());

Exemple de Code : Désérialiser un ItemStackSnapshot depuis le format JSON

DataContainer container = DataFormats.JSON.read(json);

Exemple de Code : Écrire un ItemStackSnapshot dans un fichier en utilisant NBT

public void writeItemStackSnapshotToFile(ItemStackSnapshot itemStackSnapshot, Path path) {
    DataContainer dataContainer = itemStackSnapshot.toContainer();
    try (OutputStream outputStream = Files.newOutputStream(path)) {
        DataFormats.NBT.writeTo(outputStream, dataContainer);
    } catch (IOException e) {
        // For the purposes of this example, we just print the error to the console. However,
        // as this exception indicates the file didn't save, you should handle this in a way
        // more suitable for your plugin.
        e.printStackTrace();
    }
}

Exemple de Code : Lire un ItemStackSnapshot depuis un fichier en utilisant NBT

public Optional<ItemStackSnapshot> readItemStackSnapshotFromFile(Path path) {
    try (InputStream inputStream = Files.newInputStream(path)) {
        DataContainer dataContainer = DataFormats.NBT.readFrom(inputStream);
        return Sponge.getDataManager().deserialize(ItemStackSnapshot.class, dataContainer);
    } catch (IOException e) {
        e.printStackTrace();
    }

    return Optional.empty();
}