Loaders de Configuration

Décomposons la manière dont Configurate fonctionne, en commençant par le processus de chargement. Configurate fournit des ConfigurationLoaders pour les formats courants de configuration, comme le gestionnaire de fichiers physiques de votre configuration, vous permettant de sauvegarder et de charger les données d’une ressource donnée. Ils permettent aussi de charger des configurations vides, vous permettant de hard-coder des valeurs par défaut ou de les charger depuis un fichier pré-écrit.

Obtenir votre Loader

Note

Le ConfigurationLoader par défaut peut être utilisé à la place, si vous utilisez HOCON; voir la page de configuration principale.

Tout d’abord, prenons un nouveau HoconConfigurationLoader qui pointe vers notre fichier de configuration.

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

Le Loader va également gérer un type générique dépendant de quel type de note il va construire. Ces Configuration Nodes seront expliqués dans une section par la suite.

Les ConfigurationLoaders contiennent habituellement un builder pour vous afin d’accéder et de créer statiquement une nouvelle instance du Loader du type souhaité. Pour une configuration basique, nous n’avons pas vraiment besoin de spécifier autre chose que le fichier que nous voulons charger et/out sauvegarder, donc tout ce que nous allons faire est de lui dire exactement cela, en utilisant HoconConfigurationLoader.build().setPath(path). Nous allons ensuite utiliser le builder afin de construire l’instance (build()) pour lui et le stocker dans une variable.

Bien sûr, ce n’est pas le seul moyen de charger un fichier. Le builder possède également une méthode setURL(URL), au cas où vous voulez charger une ressource sans utiliser d’objet Path. Gardez à l’esprit que les Loaders de Configuration créés depuis une URL ne peuvent être que lus puisqu’il n’y a aucun moyen d’écrire des données en passant par une URL.

Cette fonctionnalité peut servir à regrouper les configurations par défaut avec le fichier jar de votre plugin et les charger dans la configuration initiale pour être éditées par l’administrateur du serveur (ou par votre plugin lui-même).

Charger et Sauvegarder

Une fois que vous avez obtenu votre ConfigurationLoader, vous pouvez l’utiliser pour obtenir un ConfigurationNode vide en utilisant la méthode 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());

Cette méthode attend un paramètre ninja.leaping.configuration.ConfigurationOptions. Sauf si vous voulez utilisez des fonctionnalités comme la sérialisation de type customisés, vous pouvez seulement utiliser ConfigurationOptions#defaults() pour créer un objet d’options avec les valeurs par défaut.

En utilisant la méthode load() vous pouvez essayer de charger les contenus de la configuration à partir de la source spécifié à la création du ConfigurationLoader. Il attend aussi une instance de ConfigurationOptions, mais fournit aussi une forme sans argument qui est un raccourci pour ``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 le Path donné n’existe pas, la méthode load() va créer un ConfigurationNode vide. Toute autre erreur va mener à une IOException étant levée dont vous aurez besoin pour gérer correctement le problème.

Si vous avez injecté le loader par défaut, c’est une bonne idée de récupérer son ConfigurationOptions, puisque qu’il contient l’abilité de sérialiser et de désérialiser un grand nombre d’objets de Sponge.

Une fois que vous avez modifié votre ConfigurationNode pour garder les données que vous aimeriez sauvegarder, vous pouvez utiliser le ConfigurationLoader pour sauvegarder la node au fichier spécifié à la création du loader. Si ce fichier n’existe pas, il sera créé. Si il existe, tout son contenu sera écrasé.

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

Encore une fois, les erreurs seront propagés en tant qu”IOException et doivent être gérées.

Exemple: Charger une configuration par défaut depuis le fichier jar de votre plugin

import java.net.URL;

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

Pour cet exemple, il est important de préciser que la méthode AssetManager#getAsset(String) dépend du dossier de ressources du plugin. Donc si dans l’exemple ci-dessus l’ID du plugin est myplugin, le fichier defaultConfig.conf ne doit pas être dans la racine du fichier jar, mais plutôt dans le dossier assets/myplugin. Pour plus d’informations, voir la page Ressource API.