Konfigurasi Node

Peringatan

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!

In memory, the configuration is represented using ConfigurationNodes. A ConfigurationNode either holds a value (like a number, a string or a list) or has child nodes, a tree-like configuration structure. When using a ConfigurationLoader to load or create new configurations, it will return the root node. We recommend that you always keep a reference to that root node stored somewhere, to prevent loading the configuration every time you need to access it. As a side effect, this will keep the comments that were present in the file. As an alternative, you could store a reference to a serializable config instance that holds the entire configuration of your plugin.

Catatan

Tergantung pada ConfigurationLoader bekas, anda bahkan mungkin mendapatkan CommentedConfigurationNode, yang selain normal ConfigurationNode perilaku ini dapat mempertahankan komentar yang akan bertahan disimpan pada file konfigurasi.

Navigasi Node

Setiap anak simpul diidentifikasi oleh key, paling sering string. Ketika pergi dari satu node (misalnya simpul akar) untuk spesifik node anak, mungkin perlu untuk bergerak melalui beberapa lapisan node anak. Kunci dari anak node melewati membuat jalan dari node target. Dalam contoh berikut, ada node memegang nilai false di jalan modules blockCheats enabled (dari simpul akar) berikut HOCON representasi dari config.

Catatan

Ketika menuliskan, jalur yang sering diwakili dengan bergabung tombol bersama-sama dengan separator arang, biasanya .. Yang disebutkan di atas jalan yang akan ditulis modules.blockCheats.enabled.

modules {
    blockCheats {
        enabled=true
    }
}

Di Java, anda bisa mendapatkan node anak untuk jalan menggunakan getNode(...) metode. Metode menerima sejumlah argumen, di mana masing-masing argumen adalah salah satu kunci dalam jalur. Jalan modules.blockCheats.enabled dari simpul akar adalah diperoleh sebagai berikut.

import org.spongepowered.configurate.ConfigurationNode;

ConfigurationNode rootNode = ...;
ConfigurationNode targetNode = rootNode.getNode("modules", "blockCheats", "enabled");

Catatan

Fungsi panggilan node.getNode("foo", "bar") dan node.getNode("foo").getNode("bar") setara.

Nilai

Nilai dasar

Nilai dasar jenis seperti int, double, boolean atau String masing-masing memiliki kenyamanan mereka sendiri getter method yang akan mengembalikan nilai default jika node tidak berisi nilai dari tipe tersebut. Mari kita cek apakah administrator server kami ingin plugin untuk mengaktifkan nya blockCheats modul dengan memeriksa nilai pada modules.blockCheats.enabled jalan.

boolean shouldEnable = rootNode.getNode("modules", "blockCheats", "enabled").getBoolean();

Ya, ini benar-benar sesederhana itu. Serupa dengan contoh di atas, metode seperti ConfigurationNode#getInt(), ConfigurationNode#getDouble() atau ConfigurationNode#getString() ada yang memungkinkan anda untuk dengan mudah mengambil nilai dari jenis itu.

To set a basic value to a node, just use the ConfigurationNode#setValue(Object) method. Don't be confused that it accepts an Object - this means that it can take anything and will determine how to proceed from there by itself.

Bayangkan modul blok Cheast tidak diaktifkan oleh perintah pengguna. Perubahan ini perlu tercermin dalam konfigurasi dan bisa dilakukan sebagai berikut:

rootNode.getNode("modules", "blockCheats", "enabled").setValue(false);

Peringatan

Anything other than basic value types cannot be handled by those basic functions, and must instead be read and written using the (de)serializing Methods described below. Basic types are those that are natively handled by the underlying implementation of the file format used by the ConfigurationLoader, but generally include the primitive data types, Strings as well as Lists and Maps of basic types.

(De)Serialisasi

If you attempt to read or write an object that is not one of the basic types mentioned above, you will need to pass it through deserialization first. In the ConfigurationOptions used to create your root ConfigurationNode, there is a collection of TypeSerializers that Configurate uses to convert your objects to a ConfigurationNode and vice versa.

In order to tell Configurate what type it is dealing with, we have to provide a guava TypeToken. Imagine we want to read a player UUID from the config node towns.aFLARDia.mayor. To do so, we need to call the getValue(...) method while providing a TypeToken representing the UUID class.

import java.util.UUID;

UUID mayor = rootNode.getNode("towns", "aFLARDia", "mayor").getValue(TypeToken.of(UUID.class));

This prompts Configurate to locate the proper TypeSerializer for UUIDs and then use it to convert the stored value into a UUID. The TypeSerializer (and by extension the above method) may throw an ObjectMappingException if it encounters incomplete or invalid data.

Now if we want to write a new UUID to that config node, the syntax is very similar. Use the setValue(...) method with a TypeToken and the object you want to serialize.

rootNode.getNode("towns","aFLARDia", "mayor").setValue(TypeToken.of(UUID.class), newUuid);

Catatan

Serialisasi nilai akan membuang ObjectMappingException jika tidak ada TypeSerializer untuk mengingat TypeToken dapat ditemukan.

For simple classes like UUID, you can just create a TypeToken using the static TypeToken#of(Class) method. However, UUIDs and some other types already have a constant for it, such as TypeTokens#UUID_TOKEN, which you should use instead. If the class you want to use has type parameters (like Map<String,UUID>) and no constant yet exists for it, the syntax gets a bit more complicated. In most cases you will know exactly what the type parameters will be at compile time, so you can just create the TypeToken as an anonymous class: new TypeToken<Map<String,UUID>>() {}. That way, even generic types can conveniently be written and read.

Lihat juga

For more information about TypeTokens, refer to the guava documentation

Tip

The SpongeAPI provides a class with many pre-defined type tokens that you can use. If plugin developers need many different or complex TypeTokens, or use them frequently, we recommend creating a similar class for themselves to improve code readability. (Beware, it is not guaranteed that all of those entries have registered TypeSerializers).

You can find a non-exhaustive list of supported types, and ways to add support for new types on the the config serialization page.

Bawaan

Unlike SpongeAPI, the Configurate library does not use Optional for values that might not be present but null. While the getters for primitive methods (like getBoolean() or getInt()) might return false or 0, those that would return an object (like getString()) will return null if no value is present. If you do not want to manually handle those special cases, you can use default values. Every getXXX() method discussed above has an overloaded form accepting an additional parameter as a default value.

Mari kita lihat contoh untuk membaca nilai boolean lagi.

boolean shouldEnable = rootNode.getNode("modules", "blockCheats", "enabled").getBoolean();

Panggilan ini akan kembali palsu jika salah satu nilai palsu disimpan di config atau nilai yang tidak hadir dalam konfigurasi. Sejak dua kasus yang bisa dibedakan kami tidak memiliki cara sederhana untuk menetapkan variabel yang menjadi palsu hanya jika itu adalah nilai yang ditentukan pada konfigurasi. Kecuali kita menentukan benar sebagai nilai default.

boolean shouldEnable = rootNode.getNode("modules", "blockCheats", "enabled").getBoolean(true);

Demikian pula, anda dapat menentukan default pada setiap nilai yang anda dapatkan dari config, sehingga menghindari null kembali atau ObjectMappingException yang disebabkan oleh tidak adanya seluruh nilai. Ia juga bekerja pada deserialisasi getValue() metode. Beberapa contoh:

String greeting = rootNode.getNode("messages", "greeting")
        .getString("FLARD be with you good man!");

UUID mayor = rootNode.getNode("towns", "aFLARDia", "mayor")
        .getValue(TypeTokens.UUID_TOKEN, somePlayer.getUniqueId());

Another useful application of those defaults is that they can be copied to your configuration if needed. Upon creation of your root configuration node, you can create your ConfigurationOptions with setShouldCopyDefaults(true). Subsequently, whenever you provide a default value, Configurate will first check if the value you're trying to get is present, and if it is not, it will first write your default value to the node before returning the default value.

Mari kita asumsi kan plugin anda menjalankan untuk pertama kalinya dan config file belum ada. Anda mencoba untuk memuat dengan ConfigurationOptions yang memungkinkan menyalin nilai-nilai default dan mendapatkan kosong config node. Sekarang anda jalankan garis rootNode.getNode("modul", "blockCheats", "enabled").getBoolean(yang benar). Sebagai node belum ada, configurate menciptakan dan menulis nilai true untuk itu sebagai per ConfigurationOptions sebelum kembali itu. Ketika config kemudian selesai, nilai benar akan bertahan pada node tanpa pernah secara eksplisit diatur.