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

Whenever you're reading a serialized object, it's tempting to read all the individual values yourself in order to manually create all the required objects (and their parameters) for your data. However, depending on the data saved in the container there are a few ways that are far more convenient:

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;

private String name = "Spongie";

@Override
public DataContainer toContainer() {
    return DataContainer.createNew()
            .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.

You'll want to check that all the queries you want to retrieve are present using DataView.contains(Key...). If not, the data is likely incomplete and you should return Optional.empty().

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

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

import org.spongepowered.api.data.persistence.DataContentUpdater
import 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.

As with other data, ensure that you register the translator during GameRegistryEvent.Register<DataTranslator<?>>.