Loaders de Configuration

Avertissement

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

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.

Astuce

Le format de configuration par défaut et recommandé pour les plugins Sponge est HOCON.

Obtenir votre Loader

Note

Si vous utilisez un seul fichier de configuration HOCON, le ConfigurationLoader par défaut peut être utilisé à la place; 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 org.spongepowered.configurate.commented.CommentedConfigurationNode;
import org.spongepowered.configurate.hocon.HoconConfigurationLoader;
import org.spongepowered.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 que vous puissiez accéder et 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/ou sauvegarder, donc tout ce que nous allons faire est de lui dire exactement cela, en utilisant HoconConfigurationLoader.builder().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 souhaitez 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).

Note

Cet exemple utilise un HoconConfigurationLoader, qui est l’approche recommandée pour les plugins Sponge, mais vous pouvez également utiliser un YAMLConfigurationLoader ou un GsonConfigurationLoader pour charger des anciennes configurations.

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 org.spongerpowered.configurate.ConfigurationNode;
import org.spongerpowered.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 ConfigurationOptions. Sauf si vous voulez utilisez des fonctionnalités comme la sérialisation de types customisés, vous pouvez juste 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) {
    // handle 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) {
    // handle error
}

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

Astuce

Nous recommandons de sauvegarder la configuration après l’avoir chargé (pour la première fois après une mise à jour) pour s’assurer que les options de configuration nouvellement ajoutées ou migrées soient écrites sur le disque. Si vous avez besoin de sauvegarder la configuration plus tard, il est fortement recommandé de le faire en dehors du thread principal. Voir également les Mauvaises Pratiques que vous devez éviter.

Charger une configuration par défaut à partir d’un fichier du jar de votre plugin

Une méthode répandue pour fournir un fichier de configuration par défaut est de l’inclure dans le jar de votre plugin et le copier s’il n’existe pas déjà. Vous pouvez utiliser l’API Asset pour ça, comme montré dans cet exemple:

PluginContainer plugin = ...;
Path path = ...;

Sponge.getAssetManager().getAsset(plugin, "default.conf").get().copyToFile(path, false, true);
loader = HoconConfigurationLoader.builder().setPath(path).build();
rootNode = loader.load();

Dans cet exemple il est important de savoir que la méthode AssetManager#getAsset(String) prend un chemin relatif au dossier d’assets de votre plugin. Donc si l’ID du plugin est myplugin, le fichier default.conf ne doit pas se situer à la racine du jar, mais dans le dossier assets/myplugin. Cet exemple utilise aussi Asset#copyToFile(Path, boolean, boolean) qui permet également de remplacer le contenu du fichier si voulu.

Note

Si le fichier de configuration ne peut pas être trouvé à l’intérieur du jar de votre plugin, alors vous aurez une NoSuchElementException sur la méthode Optional<Asset>.get(). Assurez-vous que avez configuré votre build system pour l’inclure dans le jar.

Si vous avez une classe de configuration en plus, vous pouvez utiliser une approche bien plus simple qui fonctionne également si seulement une partie de votre configuration est manquante. Voir également des exemples sur la page Sérialisation d’objets.

Mettre à jour la configuration à partir de valeurs par défaut

Il est possible de fusionner de nouveaux nœuds dans le CommentedConfigurationNode d’une configuration existante en chargeant les valeurs d’un asset comme expliqué plus haut. Il placera chaque nœud de l’asset dans le nouveau nœud racine s’il n’existe pas déjà.

PluginContainer plugin = ...;

node.mergeValuesFrom(HoconConfigurationLoader.builder()
                    .setURL(plugin.getAsset("default.conf").get().getUrl())
                    .build()
                    .load(ConfigurationOptions.defaults()));

Note

Ça ne changera pas les nœuds existants, on peut donc l’utiliser sans vérifier si le serveur utilisait une version précédente de votre configuration.