Configuration Loaders

Let’s break down how Configurate works, beginning with the loading process. Configurate provides ConfigurationLoaders for common configuration formats, standing as the manager of the physical configuration file, allowing you to save and load data from the given resource. They also allow you to load empty configurations, giving you the option of hard-coding default values or loading from a pre-written file.

Getting your Loader

Примечание

The default ConfigurationLoader can be used instead if you’re using HOCON; see the main configuration page.

First, let’s grab a new HoconConfigurationLoader that points to our configuration file.

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

The loader will also hold a generic type depending what kind of node it will build. These Configuration Nodes will be discussed in a later section.

ConfigurationLoaders usually hold a builder for you to statically access and create a new instance of the loader of your desired type. For a basic configuration, we don’t really need to specify anything other than the file we want to load from and/or save to, so all we’ll do is tell it exactly that, using HoconConfigurationLoader.builder().setPath(path). We then tell the builder to build the instance (build()) for it and store it in a variable.

Of course, this isn’t the only way to load a file. The builder also has the method setURL(URL), in case you want to load a resource without using a Path object. Bear in mind that configuration loaders created from an URL are read-only as they have no way of writing back data to the URL.

This functionality may be used to bundle default configurations with your plugin jar file and load them as initial configuration to be edited by the server administrator (or your plugin itself).

Loading and Saving

Once you obtained your ConfigurationLoader you can use it to obtain an empty ConfigurationNode using the createEmptyNode() method.

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

This method expects the ninja.leaping.configurate.ConfigurationOptions to use as a parameter. Unless you want to use features like custom type serialization, you can just use ConfigurationOptions#defaults() to create an options object with default values.

Using the load() method you can attempt to load the configuration contents from the source specified upon creation of the ConfigurationLoader. It also expects a ConfigurationOptions instance, but also provides a no-args form that is shorthand for 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
}

If the Path given does not exist, the load() method will create an empty ConfigurationNode. Any other error will lead to an IOException being thrown which you will need to handle properly.

If you have injected the default loader, it’s a good idea to get its ConfigurationOptions, since they contain the ability to serialize and deserialize a large number of Sponge objects.

После того как вы модифицировали свой узел «ConfigurationNode» для хранения данных, которые хотите сохранить, вы можете использовать загрузчик «ConfigurationLoader», чтобы сохранить узел в файле, указанном при создании загрузчика. Если этот файл не существует, он будет создан. Если он существует, все содержимое будет перезаписано.

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

Again, errors will be propagated as an IOException and must be handled.

Example: Loading a default config from the plugin jar file

import java.net.URL;

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

For this example it is important to note that the AssetManager#getAsset(String) method works relative to the plugin’s asset folder. So if in the above example the plugin ID is myplugin, the defaultConfig.conf file must not lie in the jar file root, but instead in the directory assets/myplugin. For more information, see the Asset API page.