Anahtarları Kullanma

Uyarı

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!

Bir anahtar kullanarak veri alma ve sunma

Bir veri taşıyıcısı, :javadoc: ‘Key’ ile tanımlanan tek bir veri noktasını geri getirmek veya değiştirmek için yöntemler sağlar. Bir örnekle başlayalım:

Kod Örneği: Mümkünse bir veri taşıyıcıyı iyileştirin

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

Şimdi yukarıdaki işlev ayrıntıları için.

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.

İkinci satır veri tutucuya maksimum sağlığını sormak için get() fonksiyonunu kullanır.``get()`` fonksiyonunun yanında``getOrNull()`` ve getOrElse() fonksiyonları da vardır, hepsi ilk parametre olarak Key fonksiyonunu kabul eder. Genellikle istenen veride bir Optional olarak dönecek olan ya da veri tutucu sağlanan şifreyi desteklemediğinde Optional.empty() olarak dönen get() kullanılmalıdır.``Key`` in desteklendiğini zaten doğruladığımız için,daha fazla kontrol yapmadan sadece opsiyoneldeki``get()``i kullanabiliriz.Ayrıca getOrNull()``u da kullanabiliriz ki bu da basitçe ``get(key).orNull() kısayoludur, böylelikle Optional dan kurtulabiliriz.Üçüncü ihtimal değer veri tutucuda olmayınca dönen ve ikinci parametreyi varsayılan değer olarak kabul eden getOrElse() olabilir.

Üçüncü satırda veri tutucuya veri dönüşü öneriyoruz.Maksimum sağlığı kazanmadan önceki ve güncel sağlığı simgeleyen bir Key sağlıyoruz ve böylelikle veri tutucu maksimum sağlığa ulaşıyor.Farklı parametre serileri kabul eden birçok offer() metodu var , hepsi de öneri kabul edilirse veri içeren bir :javadoc: DataTransactionResult olarak döner.Şimdilik sadece bir tane Key ve uyumlu olan değer kullanacağız,ama ileriki sayfalarda daha fazlasıyla karşılaşacağız.Önerimizin güncel sağlığının kabul edildiğini zaten bildiğimiz için ( çünkü veri tutucu destekliyor) , sessizce sonucu çıkarabiliriz.

Aynı zamanda remove() fonksiyonunu kullanarak bir :javadoc: DataHolder``dan bilgiyi tamamen silmek mümkündür.Basitçe silmek istediğiniz dosyayı simgeleyen bir ``Key oluşturun.Sonraki örnek, verilen veri tutucudan özel bir isim silmeyi deneyecek:

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

Veri dönüştürme

Değer elde etme, değiştirme ve önerme dışında veriyle ilgili bir yol daha var. Veri tutucunun transform() metodunu kullanarak Key ve Function``ı geçebiliriz. Kodun değeri yeniden kazanılır ve verilen fonksiyon ona uygulanır. Sonuç kodun altında kayıtlanır ve``transform() metodu anında ``DataTransactionResult``a döner.

Şimdi, örnek olarak, bir veri tutucuyu maksimum sağlığını iki katına çıkararak güçlendirdiğimizi hayal edin.

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

Veya Java 8’i kullanırsanız, satırı lambda ifadeleri ile kısaltabilirsiniz:

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

İki durumda da geçen fonksiyonun null``u geçtiğinden emin olmalıyız.Ayrıca hedef aslında :javadoc:`Keys#MAX_HEALTH` anahtarını destekliyorsa hiçbir kontrolün gerçekleşmediğini farkedeceksiniz.Eğer hedef desteklemiyorsa, ``transform() fonksiyonu başarısız olacak ve DataTransactionResult olarak geri dönecek.

Anahtarlı Değerler

Bazen sadece anahtarın kesin değerine değil onu kapsayan anahtarlı değere dikkat etmeniz gereken durumlar olabilir.Bu durumda``get(key)``i yerine getValue(key) i kullanın. Orijinal değerinin kopyasını içeren BaseValue den devralan bir obje alacaksınız. Güncel sağlığın MutableBoundedValue olduğunu bildiğimizden, minimum mümkün sağlığı ve hedefin sağlığının birazcık üstünü bulabiliriz.

Örnek Kod: Bir hedefi ölümün eşiğine getir

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()).