Configuration API Reference

本页面已存在其他语言的内容，请协助翻译为本地化的中文。

• 点击此处开始翻译。
• 如本模板出现在原文存档页面，请注意更新主页面后，仍需要去除此处该模板。
• 如当前页面已经没有需要翻译的内容，请删去待翻译模板。
• 有标题的大篇幅文章，如果短时间内无法全部翻译，请先把所有的标题翻译出来，以便之后的贡献者选择与翻译章节内容。

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 YAML configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太OUT了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the FileConfiguration Class

基本论述

Configuration对象

<ref>key 键 value 值</ref> 你的插件继承了 JavaPlugin, 由此,你也继承了JavaPlugin这个父类的的方法和属性. 继承的方法中, getConfig() 返回的是一个 FileConfiguration类的对象.这个对象就代表你插件数据文件夹里的config.yml .

插件初次使用getConfig()时会把config.yml 从磁盘中载入, 同时从jar中加载默认值. 但getConfig()的后续调用这时只会返回现存的FileConfiguration 对象. 除了显式保存，对此对象执行的操作不会写入到磁盘. 同样，在文件被加载之后的任何修改将不会被反映在对象中. 如果在你的数据文件夹中不存在 config.yml ,此时在程序中等价于存在一个空的config.yml, 也会加载一个空的FileConfiguration.

如果你分配了利用getConfig()返回的对象，请不要将其分配给一个全局属性
若要如此，记住在重载配置文件之后再把 getConfig() 分配给一个变量
最好直接用getConfig()而不是将其分配给一个实例变量

键

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个FileConfigurationSection或是独立的数据. getKeys(boolean) 方法会返回现有FileConfigurationSection集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, getKeys(boolean) 方法必须加载在特定节点. 你可以通过getConfigurationSection(String)方法来获取这个部分.

getKeys(boolean)方法返回的是这里的字符串集合

路径

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.

key: value
one:
  two: value
  three:
    - values
    - values
    - values
  four: 
    five: value
  *:
    six: value
    seven: value

• key
• one
• one.two
• one.three
• one.four
• one.four.five
• one.*
• one.*.six
• one.*.seven

默认值

你的jar中应该为用户准备一个默认的config.yml.当出现config.yml丢失或是不完整的情况时,程序将会访问jar内的 config.yml来获取值.准备好的文件必须被命名为 config.yml ，且应当放在与 plugin.yml相同的目录. The file should have the intended structure of your config.yml. This file can be copied as is into the datafolder by invoking saveDefaultConfig() on the Appropriate instance of JavaPlugin.

this.saveDefaultConfig()

If dynamic key-value pairs are required as default values, they can added as defaults to the configuration with invocations of addDefault(String, Object) and addDefaults(Map<String,Object>) methods.

In certain cases if you wish to append new key-value pairs to an existing config.yml you can set the copyDefaults to true for the ConfigurationOptions object.

this.getConfig().options().copyDefaults(true)

创建一份config.yml的拷贝

你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/YourPlugin/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

获得值

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found here. Every getter method takes a configuration path detailed above. Some of the commonly used getter methods are as follows

• getBoolean(String)
• getInt(String)
• getString(String)
• getList(String)
• getStringList(String)

HashMaps

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a HashMap, a ConfigurationSection must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.

this.getConfig().getConfigurationSection("path.to.map").getValues(false)

设定值

Writing values involves invoking the set(String, Object) method on an instance of Configuration. Unlike the different get methods that FileConfiguration has, there is only one set method. Not all objects can be set, only primitive types, String, Lists, and types that implement ConfigurationSerializable, such as Vector and ItemStack, can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:

// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);

HashMaps

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The context above is to minimize unpredictability.

To set a HashMap, a ConfigurationSection must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod

this.getConfig().createSection(String path, Map< String, Object > map)

保存文件

If make any changes to theFileConfiguration with set methods, or mutate any Lists, you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there.

this.saveConfig();

从磁盘中重载配置文件

If you suspect that users have made changes to the config.yml in the data folder, those changes are not reflected in memory. Invoke the reloadConfig() method of your plugin to load from the disk again. It will destroy all changes in memory.

this.reloadConfig();

<references />

Advanced Topics

The following are some more advanced topics, meant for more advanced plugins. If you only require the default config.yml, creating custom methods for reading, and saving, you will not need to go this far.

Options

Every FileConfiguration instance is associated with a FileConfigurationOptions object. The FileConfigurationOptions object controls the behavior of the FileConfiguration it is associated with. FileConfiguration's options() method returns the FileConfigurationOption's responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example copyDefaults() which returns a boolean and copyDefaults(boolean) which returns it self, but has a side effect which changes the state.

CopyDefaults

The copyDefaults option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

PathSeperator

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

Header

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

copyHeader

If copyHeader() returns true then the header will be copied on save, from the default source.

Arbitrary Configurations

If you require additional YAML files, for storing configuration information or persisting additional game information you will need to write your own methods for accessing the additional configuration files. Modeled after JavaPlugin getConfig, reloadConfig, saveConfig methods, the following is an example how to write your own methods to read and save to custom configuration files. Since these config files belong to your plugin, you can put this method in your main class so that you can have the same access as you have with config.yml. You will have to write a set of these methods for each YAML file. The advantage here, is that you can use each set in the same manner as the provided methods for the default config.yml. Alternately, adding additional methods can keep the method count lower and allow access to multiple files.

Mirroring the JavaPlugin implementation

JavaPlugin implements methods for config.yml. A plugin needs to implement its own methods to access configuration files unique to the plugin. After implementing the methods for the plugin, they can be invoked in the same context as the inherited getConfig(), reloadConfig(), saveConfig(), and saveDefaultConfig() methods from JavaPlugin. The following can be made into a single class which allows access to any yaml file. Such a class can be found here

First you will need to declare two fields and initialize them to null for each of the custom configuration files. One to hold the FileConfiguration object and one to hold the File object. The File object represents the file on the disk, and the FileConfiguration represents the contents of the configuration.

private FileConfiguration customConfig = null;
private File customConfigFile = null;

Implementation for Reloading

Then, write the method that is responsible for loading the config from disk. It will load the file, and search the jar for a default customConfig.yml.

public void reloadCustomConfig() {
    if (customConfigFile == null) {
    customConfigFile = new File(getDataFolder(), "customConfig.yml");
    }
    customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

    // Look for defaults in the jar
    Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
    if (defConfigStream != null) {
        YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
        customConfig.setDefaults(defConfig);
    }
}

Implementation for Getting

Next, you need to write the getter method. Check if customConfig is null, if it is load from disk.

public FileConfiguration getCustomConfig() {
    if (customConfig == null) {
        reloadCustomConfig();
    }
    return customConfig;
}

Implementation for Saving

Finally, write the save method, which saves changes and overwrites the file on disk.

public void saveCustomConfig() {
    if (customConfig == null || customConfigFile == null) {
        return;
    }
    try {
        getCustomConfig().save(customConfigFile);
    } catch (IOException ex) {
        getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
    }
}

Implementation for Defaults

Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.

public void saveDefaultConfig() {
    if (customConfigFile == null) {
        customConfigFile = new File(getDataFolder(), "customConfig.yml");
    }
    if (!customConfigFile.exists()) {            
         plugin.saveResource("customConfig.yml", false);
     }
}

Serializing and Deserializing Objects

The Configuration API, as mentioned above can store Java objects that implement the ConfigurationSerializable Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a Location in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a Location.

Classes, in addition to implementing the ConfigurationSerializable interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

• A constructor that accepts a single Map.
• A static method "deserialize" that accepts a single Map and returns the class.
• A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:

ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)

{{{1}}} Do not use a static block to execute the above; if you do so, it will not be called a second time when /reload is used and you will encounter errors due to it not being registered!

Aliases

When classes are serialized they are marked with their fully qualified name.

You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the SerializableAs annotation to the class implementing ConfigurationSerializable.

@SerializableAs(String)

When registering a class with an alias, the alias must be provided on registration.

ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)

Example Use

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;


public class SimpleMOTD extends JavaPlugin {

    @Override
    public void onEnable() {
        // Save a copy of the default config.yml if one is not there
        this.saveDefaultConfig();
        
        // Register a new listener
        getServer().getPluginManager().registerEvents(new Listener() {
            
            @EventHandler
            public void playerJoin(PlayerJoinEvent event) {
                // On player join send them the message from config.yml
                event.getPlayer().sendMessage(this.getConfig().getString("message"));
            }
        }, this);

        // Set the command executor for the rules command
        this.getCommand("rules").setExecutor(new CommandExecutor() {
            
            public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
                // On command send the rules from config.yml to the sender of the command
                List<String> rules = this.getConfig().getStringList("rules");
                for (String s : rules)
                    sender.sendMessage(s);
                }
                return true;
            }
        });
    }
}

The default config.yml that is in the plugin's jar

# default config.yml
message: Hello World and Welcome! :)
rules:
  - Play Nice
  - Respect others
  - Have Fun