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.

The first line checks if our given data holder supports a current health value. Only if it does, it can be healed after all. Since a data holder cannot have current health without having a maximum health and vice versa, a check for one of the keys using the supports() method suffices.

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

Again, we check if our target supports the health key and then obtain the keyed value. A MutableBoundedValue contains a getMinValue() method, so we obtain the minimal value, add 1 and then set it to our data container. Internally, the set() method performs a check if our supplied value is valid and silently fails if it is not. Calling health.set(-2) would not change the value within health since it would fail the validity checks. To finally apply our changes to the target, we need to offer the keyed value back to it. As a keyed value also contains the Key used to identify it, calling target.offer(health) is equivalent to target.offer(health.getKey(), health.get()).