Yapılandırma Düğümleri
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!
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.
Not
Kullanılan ConfigurationLoader` a bağlı olarak, hatta normal ``ConfigurationNode
davranışa ek olarak CommentedConfigurationNode yapılandırma dosyasında kalması sağlanacak açıklama tutabilen bir ConfigurationNode
bile tutabilirsiniz.
Değerler
Temel Özellikler
Int
, doubl
, boolean
veya String
gibi temel değer türlerinin her biri kendi getter yöntemi vardır ve bu düğümler bir değer içermiyorsa öntanımlı değere döndürürler. Sunucu yöneticisi eklentimiz ile``modules.blockCheats.enabled`` yolundaki değere bakarak blockCheats modülü etkinleştirip etkinleştirmeyeceğini kontrol edelim.
boolean shouldEnable = rootNode.getNode("modules", "blockCheats", "enabled").getBoolean();
Evet, aslında bu kadar kolay. Yukarıdaki örneğe benzer, ConfigurationNode#getInt(), ConfigurationNode#getDouble() yada ConfigurationNode#getString() metodlar var olan bu tür bir değeri uygun şekilde almanızı sağlar.
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.
BlockCheats modülünün bir kullanıcı komutu tarafından devre dışı bırakıldığını düşünün. Bu değişikliğin yapılandırmaya yansıması gerekir ve şu şekilde yapılabilir:
rootNode.getNode("modules", "blockCheats", "enabled").setValue(false);
Uyarı
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, String
s as well as List
s and Map
s of basic types.
(De)Serialization
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 UUID
s 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);
Not
Bir değeri seri hale getirmek verilen TypeToken
için TypeSerializer
bulunmuyorsa ObjectMappingException
bulunabilir.
For simple classes like UUID
, you can just create a TypeToken
using the static TypeToken#of(Class)
method. However, UUID
s 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.
Ayrıca bakınız
For more information about TypeToken
s, refer to the guava documentation
Tüyo
The SpongeAPI provides a class with many pre-defined type tokens that you can use.
If plugin developers need many different or complex TypeToken
s, 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 TypeSerializer
s).
You can find a non-exhaustive list of supported types, and ways to add support for new types on the the config serialization page.
Varsayılan
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.
Bir boolean değerini tekrar okuma için örneğine bir göz atalım.
boolean shouldEnable = rootNode.getNode("modules", "blockCheats", "enabled").getBoolean();
Bu çağrı, false
değeri yapılandırmaya kaydedilirse veya değer yapılandırmada mevcut değilse false
döndürülür. Bu iki durum birbirinden ayırt edilemezse değişkenimizi false
olarak ayarlamak kolay değildir, ancak bu sadece yapılandırmada belirtilen değerdir. Varsayılan değer olarak true
belirtilmediği takdirde.
boolean shouldEnable = rootNode.getNode("modules", "blockCheats", "enabled").getBoolean(true);
Benzer şekilde, yapılandırmadan aldığınız herhangi bir değere varsayılan değerler atayabilirsiniz, böylece tüm değerin yokluğundan kaynaklanan `` null`` dönüşlerinden veya ObjectMappingException``dan kaçınırsınız. Ayrıca, kaldırıcı olan ``getValue()
yöntemi üzerinde de çalışır. Bazı örnekler:
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.
Eklentinizin ilk kez çalıştığını ve yapılandırma dosyası henüz mevcut olmadığını varsayalım. Varsayılan değerlerin kopyalanmasına izin veren ve yapılandırma düğümünü ConfigurationOptions
ile yüklemeyi deneyin. Şimdi rootNode.getNode("modules", "blockCheats", "enabled").getBoolean(true)
satırını çalıştırın. Düğüm henüz mevcut olmadığından, yapılandırma bunu oluşturur ve onu döndürmeden önce ConfigurationOptions
uyarınca``true`` değerini yazar. Yapılandırma tamamlandığında, true
değeri açıkça ayarlanmadan düğüm mevcut olarak devam edecektir.