ConfigurationLoader

Lasst uns anschauen, wie Configurate funktioniert. Wir beginnen beim Ladevorgang. Configurate stellt ConfigurationLoader für einige gängige Konfigurationsformate bereit und ist der Manager der physischen Konfigurationsdatei. Er erlaubt dir das Speichern und Laden aus der angegebenen Ressource. Du kannst außerdem leere Konfigurationen laden, so ist es möglich feste Standardwerte vorzugeben oder aus einer vorgefertigten Datei zu laden.

Einen Loader bekommen

Bemerkung

Der Standard ConfigurationLoader kann verwendet werden, wenn du HOCON verwendest. Siehe dazu auch die Haupt-Konfigurationsseite.

Als erstes erstellen wir uns einen neuen HoconConfigurationLoader, der auf unsere Konfigurationsdatei verweist.

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

Der Loader wird außerdem einen generischen Typen enthalten, der angibt, welche Art von Knoten er erstellt. Diese Konfigurations Knoten werden in einem späteren Abschnitt behandelt.

ConfigurationLoaders haben üblicheriwese einen Builder, der es dir erlaubt auf statische Art und Weise neue Instanzen für die gewünschte Klasse zu erstellen. Für eine grundlegende Konfiguration brauchen wir nicht viel zu machen außer anzugeben, welche Datei wir zum Laden und Speichern verwenden sollen, also tun wir genau das mit der HoconConfigurationLoader.builder().setPath(path) Methode. Anschließend sagen wird dem Builder, dass er unsere Instanz mit build() erstellen soll und speichern diese in eine Variable.

Natürlich ist dies nicht der einzige Weg eine Konfigurationsdatei zu laden. Der Builder hat außerdem die Methode setURL(URL), für den Fall dass du eine Ressource laden möchtest, ohne ein Path Objekt zu verwenden. Bitte beachte, dass ConfigurationLoaders, die mit einer URL erstellt wurden, nur gelesen werden können, da es keine Möglichkeit gibt die Änderungen an die URL zurückzuschreiben.

Diese Funktionalität kann verwendet werden, um die in der Plugin-Jar Datei mitgelieferte Standardkonfiguration zu laden, die dann später von dem Server Administrator (oder deinem Plugin selbst) bearbeitet wird.

Laden und Speichern

Sobald du deinen ConfigurationLoader hast, kannst du diesen Benutzen einen leeren ConfigurationNode mit dem Methode createEmptyNode() zu erstellen.

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

Diese Methode erwartet die ninja.leaping.configurate.ConfigurationOptions als Parameter. Sofern du keine Features wie benutzerdeninierte Typ-Serialisierung verwendest, kannst du einfach ConfigurationOptions#defaults() verwenden, um ein Optionsobjekt mit Standardwerten zu erstellen.

Mithilfe der load() Methode kannst du versuchen, die Konfigurationsinhalte aus der, während der Erstellung angegebenen, Quelle zu laden. Diese erwartet ebenfalls eine ConfigurationOptions Instanz, aber es gibt eine eine Abkürzung ohne Parameter, die load(ConfigurationOptions.defaults()) aufruft.

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
}

Wenn der angegebene Path nicht existiert, dann wird die load() Methode eine leeren ConfigurationNode erstellen. Jede andere Art von Fehler wird zu einer IOException führen, die du entsprechend behandeln musst.

Wenn du die eingefügten Standard-Loader verwendest, ist es eine gute Idee deren ConfigurationNode zu holen, da diese die Fähigkeit besitzen, eine große Reihe von Sponge Objekten zu serialisieren bzw. zu deserialisieren.

Sobald du den ConfigurationNode bearbeitet hast, der deine Daten enthält, die du speichern möchtest, kannst du den ConfigurationLoader verwenden, um diese in die, bei der Erstellung des Loaders angegebene, Datei zu speichern. Wenn die Datei nicht existiert, wird sie erstellt. Wenn die Datei bereits existiert, wird ihr Inhalt überschrieben.

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

Auch hier können Fehler auftreten, die in Form von IOException behandelt werden müssen.

Beispiel: Laden der Standard Konfiguration aus der Plugin Jar Datei

import java.net.URL;

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

Für dieses Beispiel ist es wichtig zu verstehen, dass die AssetManager#getAsset(String) Methode relativ zu dem Anlageordner deines Plugins arbeitet. Also, wenn die in dem Beispiel oben das Plugin die ID myplugin hat, dann muss die defaultConfig.conf Datei nicht im auf der obersten Ebene der Jar-Datei liegen, sondern im Unterverzeichnis assets/myplugin. Für mehr Informationen hierzu schau dir die Asset API Seite an.