配置加载器

让我们分解 Configurate 的整个工作流程，从加载开始。 Configurate 提供了 ConfigurationLoader 用于常见的配置格式，并用于管理物理上的配置文件，允许你通过给定资源读取或存储数据。它们还允许你加载空配置，并给予你权利去指定硬编码的默认值，或者从一个已经写好的文件指定默认值。

获取配置加载器

注解

默认的 ConfigurationLoader 用于 HOCON 格式的配置。请参见 插件配置 页面的相关内容。

首先，让我们新建一个 HoconConfigurationLoader 并指向我们的配置文件。

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

配置加载器同时会存有一个泛型以决定其会构建什么样的节点类型。关于节点，也就是 Configuration Nodes 的内容，会在 稍后的章节 中加以阐述。

ConfigurationLoader 通常持有一个生成器（ Builder ）用于静态地访问和创建一个你想要的类型的新加载器。对于基本的配置，我们并不需要指定除了我们想要加载和保存的文件之外的其他东西。因此，我们需要做的全部事情就是使用 HoconConfigurationLoader.builder().setPath(path) 。然后我们通过生成器生成（ build() ）了一个实例并将其存储在了一个变量里。

当然，这并不是加载文件的唯一方法。生成器还有一个名为 setURL(URL) 的方法，在万一你想要加载的资源不使用 Path 的情况下。铭记从 URL 中创建的配置加载器是只读的，因为它们没有办法把数据写回 URL 。

这一功能可以用于把你的插件 JAR 中的一个文件绑定到默认的配置上，然后将其作为初始化时的配置文件以供服务器管理员（或者插件本身）修改。

加载和保存

当你获取到了 ConfigurationLoader ，就可以通过 createEmptyNode() 方法来获取一个空的 ConfigurationNode 。

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

这个方法期望一个 ninja.leaping.configurate.ConfigurationOptions 作为参数。除非你有想要使用的特性，如自定义类型的序列化方式，否则你直接使用 ConfigurationOptions#defaults() 来创建这个参数作为默认值就可以了。

可以通过使用 load() 方法在 ConfigurationLoader 创建时从指定的源加载配置内容。当然它也需要一个 ConfigurationOptions 的实例，而且同时提供一个等价于 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
}

如果给定的 Path 不存在，那么 load() 方法将会创建一个空的 ConfigurationNode 。任何可能的错误都将会抛出一个 IOException ，因此你需要对其进行妥善处理。

如果你使用了默认的配置加载器，我们建议你获取相应的 ConfigurationOptions 对象，因为你可以通过它序列化 Sponge 中出现的绝大部分对象。

一旦你修改了你的 ConfigurationNode 并想要保存修改过的数据，你可以通过 ConfigurationLoader 保存你的节点至你初始化时设置的文件中。如果这么一个文件不存在，那么它将被创建，如果存在，那么它将被覆盖。

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

再一次地，所有的错误都会抛出一个 IOException ，同时你必须处理它。

示例：从插件的 JAR 中加载默认配置

import java.net.URL;

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

在这一示例中需要着重注意的一点是，方法 AssetManager#getAsset(String) 的返回值取决于插件的 Asset 文件夹位置。因此，如果上面的示例中的插件 ID 为 myplugin ，那么相应的 defaultConfig.conf 可能会位于 JAR 的根目录位置，而不是位于 assets/myplugin 目录下。更多信息可以参见 Asset API 的相关页面。