Gunakan Tombol

Menerima dan memberikan data menggunakan kunci

Pemegang data menyediakan metode untuk mengambil atau mengubah satu titik data yang diidentifikasi oleh :javadoc:`Kunci`. Mari kita mulai dengan sebuah contoh:

Contoh Kode: Menyembuhkan pemegang data, jika mungkin

import org.spongepowered.api.data.DataHolder;
import org.spongepowered.api.data.key.Keys;

public void heal(DataHolder target) {
    if (target.supports(Keys.HEALTH)) {
        double maxHealth = target.get(Keys.MAX_HEALTH).get();
        target.offer(Keys.HEALTH, maxHealth);
    }
}

Sekarang untuk rincian fungsi di atas.

Baris pertama memeriksa apakah pemegang data kami yang diberikan mendukung nilai kesehatan terkini. Hanya jika itu terjadi, itu bisa disembuhkan. Karena pemegang data tidak dapat memiliki kesehatan saat ini tanpa kesehatan yang maksimal dan sebaliknya, cek salah satu tombol dengan menggunakan metode dukungan() sudah cukup.

Baris kedua menggunakan fungsi get() untuk meminta pemegang data atas kesehatan maksimalnya. Selain get(), metode getOrNull() dan metode getOrElse() ada, semuanya yang menerima Key sebagai parameter pertamanya. Secara umum, get() seharusnya digunakan, yang akan mengembalikan Optional data yang diminta atau Optional.empty() jika pemegang data tidak mendukung kunci yang disediakan. Karena kita sudah memverifikasi bahwa Key didukung, kita dapat memanggil get() pada Optional tanpa pemeriksaan lebih lanjut. Kita juga dapat menggunakan getOrNull() yang pada dasarnya jalan pintas untuk memanggil get(key).orNull(), sehingga menyingkirkan Optional. Kemungkinan ketiga adalah getOrElse(), yang menerima nilai bawaan sebagai parameter kedua untuk dikembalikan jika nilainya tidak ada pada pemegang data.

Di baris ketiga, kami menawarkan data kembali ke dudukan data. Kami menyediakan Kunci yang menunjukkan kesehatan saat ini dan sebelum memperoleh kesehatan maksimal, sehingga menyembuhkan data pemegang ke kesehatan penuh. Ada berbagai metode penawar() yang menerima pengaturan parameter yang berbeda, yang semuanya mengembalikan :javadoc: DataHasilTransaksi berisi informasi jika tawaran tersebut diterima. Untuk saat ini, kita akan menggunakan yang menerima Kunci dan nilai yang sesuai, tapi kita akan menemukan lebih banyak di halaman berikutnya. Karena kita sudah tahu bahwa tawaran kesehatan saat ini diterima (karena dudukan data mendukungnya), kita dapat membuang hasilnya secara diam-diam.

Hal ini juga memungkinkan untuk benar-benar menghapus data dari :javadoc: DududkanData menggunakan fungsi hapus(). Cukup berikan Kunci yang mewakili data yang ingin dihapus. Contoh berikut akan mencoba menghapus nama khusus dari pemegang data tertentu:

public void removeName(DataHolder target) {
    target.remove(Keys.DISPLAY_NAME);
}

Mengubah data

Selain mendapatkan, memodifikasi dan menawarkan nilai, ada cara lain untuk berinteraksi dengan data. Dengan menggunakan metode mengubah()``datanya, kita bisa melewati ``Kunci dan Fungsi. Secara internal, nilai untuk kunci akan diambil dan fungsi yang diberikan diterapkan padanya. Hasilnya kemudian disimpan di bawah tombol dan metode mengubah() akan mengembalikan DataHasilTransaksi sesuai dengan itu.

Sekarang, sebagai contoh, bayangkan kita ingin menggosok dudukan data dengan melipat gandakan kesehatan maksimalnya.

import java.util.function.Function;

public void buff(DataHolder target) {
    target.transform(Keys.MAX_HEALTH, new Function<Double,Double>() {
        @Override
        public Double apply(Double input) {
            return (input == null) ? 0 : input * 2;
        }
    });
}

Atau, jika anda menggunakan Java 8, anda dapat memperpendek baris ekspresi lambda:

public void buff(DataHolder target) {
    target.transform(Keys.MAX_HEALTH, d -> (d == null) ? 0 : 2*d);
}

Catatan bahwa dalam kedua kasus tersebut kita perlu memastikan fungsi kita yang lolos dapat menangani null. Anda juga akan memperhatikan bahwa tidak ada pemeriksaan yang dilakukan jika sasaran sebenernya mendukung kunci Keys#MAX_HEALTH. Jika sasaran tidak mendukung, fungsi transform() akan gagal dan mengembalikan DataTransactionResult yang menunjukkan demikian.

Nilai kunci

Ada kasus dimana anda boleh mempedulikan bukan hanya nilai langsung untuk Kunci, tetapi nilai kunci yang mengenkapsulasikannya. Dalam kasus tersebut, gunakan metode getValue(key) daripada metode get(key). Anda dapat menerima objek pewarisan dari BaseValue yang berisi salinan nilai aslinya. Karena kita tahu bahwa kesehatan saat ini merupakan MutableBoundedValue, kita dapat mencari tahu nilai kemungkinan minimal dan mengatur sasaran kesehatan kita sedikit di atas itu.

Contoh Kode: Bawa target ke ambang kematian

import org.spongepowered.api.data.value.mutable.MutableBoundedValue;

public void scare(DataHolder target) {
    if (target.supports(Keys.HEALTH)) {
        MutableBoundedValue<Double> health = target.getValue(Keys.HEALTH).get();
        double nearDeath = health.getMinValue() + 1;
        health.set(nearDeath);
        target.offer(health);
    }
}

Lagi-lagi, kita memeriksa jika sasaran kita mendukung kunci kesehatan lalu memperoleh nilai kuncinya. Sebuah MutableBoundedValue berisi metode getMinValue(), jadi kita memperoleh nilai minimal, menambahkan 1 lalu mengaturnya menjadi data container kita. Secara internal, metode set() melakukan pemeriksaan jika nilai yang disediakan kita valid dan secara diam-diam gagal jika tidak valid. Memanggil health.set(-2) tidak mengubah nilai dalam health karena akan gagal memeriksa validitas. untuk menerapkan perubahan kita kepada sasaran pada akhirnya, kita perlu menawarkan kembali nilai kunci tersebut. Sebagai nilai kunci yang juga berisi Key yang telah digunakan untuk mengidentifikasinya, memanggil target.offer(health) sama dengan target.offer(health.getKey(), health.get()).