Nodos de configuración

En la memoria, la configuración se representa usando :javadoc: “ConfigurationNode” s. Un “”ConfigurationNode”” alberga ya sea un valor (como un número, o una lista) o tiene nodos secundarios, una estructura de configuración similar a un árbol . Cuando se utiliza un :javadoc: “ConfigurationLoader” para cargar o crear nuevas configuraciones, volverá el root node. Es recomendado que siempre mantenga una referencia a ese root node almacenada en algún lugar.

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.

Para fijar un valor básico a un nodo, sólo utilice el método :javadoc:”ConfigurationNode#setValue(Object)”. No se confunda que acepte un “”Object”” - esto significa que puede tomar cualquier cosa y determinar cómo proceder a partir de ahí por sí mismo.

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

Cualquier cosa excepto tipos de valor básicos no pueden ser manejados por esas funciones básicas, y deben en cambio ser leídas y escritas usando los métodos de (de)serializar descritos a continuación. Los tipos básicos son los que nativamente son manejados por la implementación subyacente del formato dek archivo utilizado por la “” ConfigurationLoader””, pero generalmente incluyen los tipos de datos primitivos, “”string”” s así como tambien “”list”” s y “” map”” s de tipos básicos.

(De)Serialización

Si usted intenta leer o escribir un objeto que no es uno de los tipos básicos anteriormente mencionados, usted necesitará pasar primer a través de la deserialización. En la “”ConfigurationOptions”” utilizada para crear la raíz “”ConfigurationNode””, hay una colección de :javadoc: “TypeSerializer” s que Configurate utiliza para convertir los objetos a un “”ConfigurationNode”” y viceversa.

Para poder decirle a Configurate con cual tipo está tratando, tenemos que proporcionar un`` TypeToken``. Imagina que queremos leer un jugador `` UUID`` del nodo de configuración `` towns.aFLARDia.mayor``. Para hacerlo, necesitamos llamar al método `` getValue () `` mientras que proporcionamos un `` TypeToken`` que representa la clase `` UUID``.

import java.util.UUID;

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

Esto le indica a Configurate que localice el `` TypeSerializer`` apropiado para `` UUID`` s y luego usarlo para convertir el valor almacenado en un`` UUID``. El `` TypeSerializer`` (y por extensión el método anterior) puede arrojar una `` ObjectMappingException`` si encuentra datos incompletos o no válidos.

Ahora si deseamos escribir un nuevo `` UUID`` para ese nodo de configuración, la sintaxis es bastante similar. Utilice el método `` setValue () `` con un `` TypeToken`` y el objeto que desea serializar.

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.

Para clases simples como `` UUID``, usted puede simplemente crear un `` TypeToken`` usando el método estático `` TypeToken.of () . Pero cuando la clase que desea usar tiene parámetros propios (como `` Map <String, UUID> ``), la sintaxis se vuelve un poco más complicada. En la mayoría de los casos usted sabrá exactamente cuáles serán los tipos parámetros cuando sea tiempo dec compilar, por lo que puede simplemente crear el `` TypeToken como una clase anónima: `` new TypeToken <Map <String, UUID >> () {} ` `. De esta manera, incluso los tipos genéricos pueden escribirse y leerse convenientemente.

Ver también

Para obtener más información sobre `` TypeToken`` s, consulte la documentación de guava <https://github.com/google/guava/wiki/ReflectionExplained> _

Los tipos serializables usando esos métodos son:

Cualquer valor básico (vea arriba)
Cualquier `` List`` o `` Map`` de tipos serializables
Los tipos java.util.UUID, java.net.URL, java.net.URI y java.util.regex.Pattern
Cualquier tipo que se haya hecho serializable como se describe en :doc: the config serialization page <serialization>

Predeterminados

A diferencia de la API de Sponge, la biblioteca de Configurate no utiliza `` Optional`` para valores que pueden no estar presentes pero nulos. Mientras que los adquiridores para métodos primitivos (como `` getBoolean () `` o `` getInt () ) podrían devolver `` false o `` 0``, aquellos que devolverían un objeto (como `` getString () ) devolverán `` null si no hay ningún valor presente. Si no desea manejar manualmente esos casos especiales, puede usar default values. Cada `` getXXX () `` método discutido anteriormente tiene una forma sobrecargada que acepta un parámetro adicional como un valor predeterminado.

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(TypeToken.of(UUID.class), somePlayer.getUniqueId());

Otra aplicación útil de esos valores predeterminados es que se pueden copiar a configuración de usted si es necesario. Al crear su nodo de configuración raíz, usted puede crear su `` ConfigurationOptions`` con `` setShouldCopyDefaults(true) ``. Posteriormente, siempre que proporcione un valor prestablecido, Configurate primero comprobará si el valor que está tratando de obtener está presente, y si no lo está, primero escribirá su valor prestablecido en el nodo antes de devolver el valor prestablecido.

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.