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.

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.