Nodos de configuración

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.

Nota

Dependiendo de la “”ConfigurationLoader”” utilizada, usted puede incluso recibir un :javadoc: “CommentedConfigurationNode”, que además de tener un comportamiento normal como “”ConfigurationNode”” es capaz de retener un comentario que se mantendrá en el archivo de configuración guardado.

Nodos de navegación

Cada nodo secundario se identifica por una clave, más comúnmente una cadena. Al ir de un nodo (por ejemplo el nodo raíz) a un nodo secundario específico, puede ser necesario moverse a través de múltiples capas de nodos secundarios. Las claves de los nodos secundarios previamente pasados hacen el path del nodo objetivo. En el ejemplo siguiente, hay un nodo con el valor “” false”” en la ruta “”modules”” “”blockCheats”” “”enabled”” (desde el nodo raíz) en la siguiente representación HOCON de una configuración.

Nota

Cuando se escriben, los caminos comúnmente se representan uniendo las llaves junto con un separador, usualmente “”.””. La ruta mencionada anteriormente se escribiría de esta manera “”modules.blockCheats.enabled””.

modules {
    blockCheats {
        enabled=true
    }
}

En Java, se puede obtener el nodo secundario para una ruta usando el método “”getNode(…)””. El método acepta cualquier número de argumentos, donde cada argumento es una clave en la ruta. La ruta de “”modules.blockCheats.enabled”” de un nodo raíz se adquiere como sigue.

import ninja.leaping.configurate.ConfigurationNode;

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

Nota

Las llamadas de funciones «node.getNode («foo»,»bar»)”” y “”node.getNode(«foo»).getNode(«bar»)”” son equivalentes.

Valores

Valores básicos

Tipos de valores básicos como “” int””, “”double””, “” boolean”” o “”string”” cada uno tiene su propio método adquiridor de conveniencia que devolverá el valor o un valor predeterminado si el nodo no contiene un valor de ese tipo. Podemos chequear si el administrador del servidor quiere nuestra extensión para habilitar su módulo blockCheats al comprobar el valor en la ruta “”modules.blockCheats.enabled””.

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

Sí, realmente es tan simple como eso. Similar al ejemplo anterior, los métodos como :javadoc:”ConfigurationNode#getInt()”, :javadoc:”ConfigurationNode#getDouble()” o :javadoc:”ConfigurationNode#getString()” existen para permitir que usted convenientemente pueda tomar un valor de ese tipo.

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.

Imagine que el módulo blockCheats es desactivado por un comando de usuario. Este cambio tendrá que ser reflejado en la configuración y puede hacerse como sigue:

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

Advertencia

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)Serialización

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

Nota

La serialización de un valor arrojará una `` ObjectMappingException`` si no se puede encontrar ningún`` TypeSerializer`` para el `` TypeToken`` dado.

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.

Ver también

For more information about TypeTokens, refer to the guava documentation

Truco

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.

Predeterminados

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.

Miremos al ejemplo para leer un valor booleano nuevamente.

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

Esta llamada devolverá `` false`` si el valor `` false`` se guarda en la configuración o si el valor no está presente en la configuración. Como estos dos casos son indistinguibles, no tenemos una forma simple de configurar nuestra variable a solo `` false`` si ese es el valor especificado en la configuración. A menos que especifiquemos `` true`` como el valor predeterminado.

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

Similarmente, usted puede especificar los valores predeterminados en cualquier valor que ysted obtenga de la configuración, evitando de esta manera los retornos `` null`` o `` ObjectMappingException`` causados ​​por la ausencia de todo el valor. Esto también sirve en el método para deserializar `` getValue () ``. Algunos ejemplos:

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.

Supongamos que su extensión se está ejecutando por primera vez y el archivo de configuración aún no existe. Usted intenta cargarlo con `` ConfigurationOptions`` que permite copiar valores predeterminados y obtener un nodo de configuración vacío. Ahora ejecuta la línea `` rootNode.getNode («modules», «blockCheats», «enabled»). GetBoolean (true) . Debido a que el nodo aún no existe, Configure lo crea y escribe el valor `` true en él según `` ConfigurationOptions`` antes de devolverlo. Luego, cuando la configuración está finalizada, el valor `` true`` persistirá en el nodo sin haber sido fijado explícitamente.