Serialisasi Data Umum

Tanpa sebuah metode untuk menserialisasi dan mendeserialisasi, data anda tidak akan bertahan saat di restarts. Sponge memiliki beberapa cara yang berbeda untuk menserialisasi/deserialisasi data berdasarkan jenis data:

DataSerializables melakukan sebuah antarmuka untuk menjalanan proses serialisasi, dan menggunakan DataBuilder untuk mendeserialisasi dan penciptaan
DataManipulators juga melakukan DataSerializable, tetapi malahan menggunakan DataManipulatorBuilder untuk deserialisasi dan penciptaan
Objek yang tidak bisa atau tidak dapat melakukan DataSerializable menggunakan DataTranslator untuk melakukan serialisasi dan deserialisasi

Ini berarti bahwa hampir semua objek di java dapat disimpan ke disk jika sudah terdaftar!

Membaca DataViews

Kapan pun Anda membaca objek serial, Anda tergoda untuk membaca semua nilai individual Anda agar bisa membuat semua objek yang dibutuhkan secara manual (dan parameternya) untuk data Anda. Namun, tergantung pada data yang tersimpan dalam wadah ada beberapa cara yang jauh lebih mudah:

Jenis-jenis java yang umum seperti int, String, double, List dan Map bisa diakses menggunakan metode built-in getint(DataQuery), getString(DataQuery), dan lin sebagainya. Daftar dari jenis-jenis tersebut jug bisa didapatkan kembali dengan cara yang sama, seperti getStringList(DataQuery).
objek dari DataSerializable bisa diakses menggunakan getSerializable(DataQuery),Class atau getSerializableList(DataQuery,Class). Bersamaan dengan path, anda juga harus menentukan Class dari jenis yang dapat diserialisasi, seperti Home.Class.
Objet yang terdaftar dengan DataTranslator bisa diakses menggunakan getObject(DataQuery, Class) atau getObjectList(DataQuery, Class). Daftar semua class-class yang didukung oleh default bisa didapatkan di DataTranslators.

Pada semua kasus anda harus menentukan path menggunakan DataQuery. Jika data anda memiliki kesesuai Key hal ini semudah memanggil key.getQuery(). Ataupun, cara yang paling mudah untuk melakukan hal tersebut dengan DataQuery.of(''nama'').

Tip

DataQuery bisa digunakan untuk merujuk kepada beberapa pohon node data kebawah, sebagai contoh, DataQuery.of(''my'', ''custom'', ''data'').

DataBuilders

Untuk membuat sebuah object menjadi bisa diserialisasi, pertama pastikan bahwa objek menjalankan DataSerializable. Anda hanya harus melakukan dua metode:

getContentVersion() - ini menentukan versi data anda saat itu.
toContainer() - ini apa yang akan diberikan oleh builder anda saat mencoba untuk mendeserialisasi dan objek. Anda bisa menyimpan apapun yang anda inginkan saat kembali ke DataContainer, selama objek tersebut juga di serialisasi menggunakan salah satu metode diatas. Cukup gunakan metode set(DataQuery, Object) untuk menyimpan data anda pada path yang telah diberikan.

Tip

Sangat direkomendasikan bahwa anda menyimpan versi dari data anda di container dan juga gunakan Queries.CONTENT_VERSION sebagai query. Ini akan mengizinkan peng-upgrade-and versi dengan :ref:`content-updaters'.

Contoh Kode: Melaksanakan toContainer

import org.spongepowered.api.data.DataContainer;
import org.spongepowered.api.data.DataQuery;
import org.spongepowered.api.data.Queries;
import org.spongepowered.api.data.MemoryDataContainer;

String name = "Spongie";

@Override
public DataContainer toContainer() {
    return new MemoryDataContainer()
            .set(DataQuery.of("Name"), this.name)
            .set(Queries.CONTENT_VERSION, getContentVersion());
}

Bagian selanjutnya adalah menjalankan DataBuilder. Direkomendasikan untuk memperpanjang AbstractDataBuilder karena dia akan mencoba meng-upgrade data anda jika versinya lebih rendah dari versi sekarang. Hanya ada satu metode yang perlu anda lakukan- build(DataView), atau buildContent(DataView jika anda menggunakan AbstractDataBuilder.

Ada baiknya anda memeriksa bahwa semua pertanyaan yang ingin anda ambil tersedia menggunakan DataView.contains(Key...). Jika tidak ada kemungkinan data tidak lengkap dan anda harus kembali ke Optional.empty().

Jika terlihat semuanya ada disana, gunakan metode getX untuk menyusun nilai-nila dan kembalikan objek yang baru disusun sebagai Optional.

Akhirnya, anda perlu mendaftarkan builder ini sehingga bisa ditemukan oleh plugins. Untuk melakukan ini, cukup panggil DataManager#registerDataBuilder(Class, DataBuilder) dengan rujukan data class dan sebuah contoh dari builder.

DataContentUpdaters

Apa yang terjadi jika anda mengubah tata letak dari data dalam versi terbaru yang dikeluarkan? DataContentUpdaters akan menyelesaikan masalah tersebut. Jika objek yang sudah diserialkan lebih rendah dari versi sekarang, AbstractDataBuilder akan mencoba dan meng-update data sebelum diserahkan ke builder.

Setiap pembaruan memiliki versi input dan versi output. Anda harus mengambil data lama dan mengubah apapun yang diperlukan untuk memperbarui ke layout yang lebih baru. Jika tidak mungkin berkonversi karna data yang hilang, mungkin saja untuk memberikan nilai default yang di jelaskan di tempat lain - seperti oleh pembangun utama atau objek itu sendiri.

Akhirnya, anda harus memastikan bahwa semua DataContentUpdaters terdaftar dengan DataManager#registerContentUpdater() dengan rujukan class data utama - hal ini akan membuat mereka bisa ditemukan oleh builder.

Contoh Kode: Menjalankan DataContentUpdater

org.spongepowered.api.data.persistence.DataContentUpdater
org.spongepowered.api.text.Text

public class NameUpdater implements DataContentUpdater {

    @Override
    public int getInputVersion() {
        return 1;
    }

    @Override
    public int getOutputVersion() {
        return 2;
    }

    @Override
    public DataView update(DataView content) {
        String name = content.getString(DataQuery.of("Name")).get();

        // For example, version 2 uses a text for the name
        return content.set(DataQuery.of("Name"), Text.of(name));
    }
}

DataManipuatorBuilders

DataManipulatorBuilder sangat serupa dengan DataBuilder, namun DataManipualatorBuilder menambahkan beberapa metode yang berhubungan dengan deserialisasi manipulators:

creat() akan mengembalikan manipulator baru dengan nilai-nilai default
CreateFrom(DataHolder) serupa dengan metode build, tetapi sebaliknya nilai-nilai harus diambil dari DataHolder. Jika disana tidak ada data untuk diambil dari pemegang, cukup kembali ke output dari create(). Jika data tidak sesuai dengan DataHolder, anda harus kembali ke Optional.empty().

Sama seperti DataBuilder, anda harus membaca dan mengembalikan manipulator anda ke metode build yang sesuai.

DataManipulatorBuilders juga bisa menggunakan DataContentUpdaters, selama anda menjalankan AbstractDataBuilder.

Mendaftarkan DataManipulatorBuilder juga sama dengan DataBuilder tetapi menggunakan metode register(). Anda harus merujuk kapada kedua class mutable dan immutable anda dalam metode, sebagai tambahan untuk contoh builder anda.

Catatan

Anda harus merujuk pada class pelaksana jika anda sudah membagi API dari pelaksana.

DataTranslators

Sering objek yang ingin anda serialisasi bukan objek yang dijalankan DataSerializable, seperti Vector3d atau Tanggal. Untuk mengizinkan objek tersebut anda menjalankan DataTranslator yang mengurus kedua proses serialisasi dan deserialisasi objek tersebut.

Menjalankan translate identik dengan toContainer() dan build(DataView) untuk DataSerializable sebagaimana ditunjukkan diatas, kecuali InvalidDataException dilakukan jika data menghilang di tempat kembalinya Optional.

Sementara dengan data yang lain, pastikan bahwa anda mendaftar translator dengan DataManager#registerTranslator(Class, DataTranslator).