Cargadores de las configuraciones

Vamos a analizar cómo funciona la Configurate, comenzando con el proceso de carga. Configurate proporciona un :javadoc: “ConfigurationLoader” s para formatos de configuración comunes, al ser el administrador del archivo de configuración física, te permite guardar y cargar datos desde el recurso dado. También permite cargar configuraciones vacías, dándote la opción de codificar valores predeterminados o cargar un archivo previamente escrito.

Obteniendo tu Cargador

Nota

El ConfigurationLoader por defecto puede ser utilizado si estas usando HOCON; dale un vistazo a la pagina principal de configuración.

En primer lugar, vamos a tomar un nuevo :javadoc: “HoconConfigurationLoader” que apunta a nuestro archivo de configuración.

import java.nio.file.Path;
import ninja.leaping.configurate.commented.CommentedConfigurationNode;
import ninja.leaping.configurate.hocon.HoconConfigurationLoader;
import ninja.leaping.configurate.loader.ConfigurationLoader;

Path potentialFile = getConfigPath();
ConfigurationLoader<CommentedConfigurationNode> loader =
  HoconConfigurationLoader.builder().setPath(potentialFile).build();

El cargador también llevará a cabo un tipo genérico dependiendo de qué tipo de nodo sea el que va a construir. Estos Nodos de Configuración se discutirán en :doc: “una sección posterior <nodes>”.

“” ConfigurationLoader”” s generalmente mantiene un generador para que estáticamente acceda y cree una nueva instancia del cargador del tipo que desees. Para una configuración básica, no necesitamos especificar ninguna otra cosa ademas del archivo que deseamos cargar desde y/o guardar a, así que todo lo que haremos será decirle exactamente eso, usando HoconConfigurationLoader.builder().setPath(path). Luego le diremos al constructor que construya la instancia (build()) para él y la almacene en una variable.

Por supuesto que esta no es la única manera de cargar un archivo. El constructor también tiene el método setURL(URL), en caso de que quieras cargar un recurso sin usar un objeto Path. Ten en cuenta que los cargadores de configuración creados desde un URL son solo-lectura ya que no tienen forma de escribir datos de vuelta al URL.

Esta funcionalidad se puede utilizar para agrupar configuraciones por defecto con tu archivo jar de complemento y cargarlos como configuración inicial para ser editada por el administrador del servidor (o por tu propia extensión).

Cargando y Guardando

Una vez que obtienes tu ConfigurationLoader puedes usarlo para obtener un ConfigurationNode vació usando el método createEmptyNode().

import ninja.leaping.configurate.ConfigurationNode;
import ninja.leaping.configurate.ConfigurationOptions;

Path potentialFile = getConfigPath();
ConfigurationLoader<CommentedConfigurationNode> loader = HoconConfigurationLoader.builder().setPath(potentialFile).build();
ConfigurationNode rootNode = loader.createEmptyNode(ConfigurationOptions.defaults());

Este metodo espera la ninja.leaping.configurate.ConfigurationOptions para ser usada como un parametro. A menos que desees usar características como la serialización de tipos personalizada, puedes simplemente usar ConfigurationOptions#defaults() para crear un objeto de opciones con valores por defecto.

Usando el método load() puedes tratar de cargar los contenidos de configuración desde la fuente especificada durante la creación del ConfigurationLoader. Se espera una ConfigurationOptions, pero tambien provee una forma sin argumentos que es una abreviación para load(ConfigurationOptions.defaults()).

import java.io.IOException;

Path potentialFile = getConfigPath();
ConfigurationLoader<CommentedConfigurationNode> loader = HoconConfigurationLoader.builder().setPath(potentialFile).build();
ConfigurationNode rootNode;
try {
    rootNode = loader.load();
} catch(IOException e) {
    // error
}

Si el Path dado no existe, el método load() creará un ConfigurationNode vació. Cualquier otro error llevará a una IOException siendo arrojada en cuyo caso tendrás que manejarla apropiadamente.

Si has inyectado el cargador por defecto, es una buena idea obtener sus ConfigurationOptions, ya que contienen la capacidad de serializar y deserializar un gran numero de objetos Sponge.

Una vez que modificaste tu ConfigurationNode para mantener los datos que quieres que esten guardados, puedes usar el ConfigurationLoader para guardar el nodo en el archivo especificado al crear el cargador. Si ese archivo no existe, será creado. Si ese archivo existe, todos los contenidos serán sobrescritos.

try {
    loader.save(rootNode);
} catch(IOException e) {
    // error
}

Una vez mas, los errores serán propagados como una IOException y deben ser manejados.

Ejemplo: Cargando una configuración por defecto del archivo de extensión jar

import java.net.URL;

URL jarConfigFile = Sponge.getAssetManager().getAsset("defaultConfig.conf").get().getUrl();
ConfigurationLoader<CommentedConfigurationNode> loader =
  HoconConfigurationLoader.builder().setURL(jarConfigFile).build();

Para este ejemplo es importante tener en cuenta que el método :javadoc:”AssetManager#getAsset(String)” funciona en relación con la carpeta de activos de la extensión. Así que si en el ejemplo anterior el ID de la extensión es myplugin, el archivo defaultConfig.conf no debe estar en la raíz del archivo jar, sino en el directorio assets/myplugin. Para obtener más información, échale un vistazo a :doc:” la página de la API Asset <… /assets >”.