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.
ConfigurationLoader
s 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.