查看“Config.yml”的源代码

{{DocsInclude}}
The Configuration API is a set of tools to help developers quickly parse and emit configuration files that are human readable and editable. Despite the name, the API can easily be used to store plugin data in addition to plugin configuration. Presently only [http://en.wikipedia.org/wiki/YAML YAML] configurations can be used. The API however was designed to be extensible and allow for other implementations.

The Configuration API can be found in the org.bukkit.configuration and org.bukkit.configuration.file packages. Plugins that were created before version 1.1-R5 may have used an older and different implementation that resided in org.bukkit.util.configuration. These implementations are not compatible and the old package has since been removed.

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 [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== Basic Topics  ==

=== The Configuration Object  ===

Your plugin extends [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin], and in doing so, you inherited methods and fields from JavaPlugin. The inherited method, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' returns an object of type [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]. This is the object that represents ''config.yml'' inside your plugin's data folder.

The first time ''getConfig()'' is invoked on your plugin, ''config.yml'' is loaded from disk, and default values are loaded from the jar. Subsequent invocations of ''getConfig()'' will return the existing ''FileConfiguration'' object that is in memory. Operations performed on this object will not be written to disk unless explicitly saved. Likewise, any modifications done after the file has been loaded will not be reflected in the object. If ''config.yml'' does not exist in your data folder, it is equivalent to an empty ''config.yml'', and will load an empty ''FileConfiguration''. 

{{warning}} if you assign the returned object from ''getConfig()'' DO NOT assign it to a static field<br> {{warning}} if you do the above, assign ''getConfig()'' to the variable AGAIN after a reloadConfig 
{{note|it is better to just use ''getConfig()'' instead of assigning it to an instance variable}}

=== Keys  ===

A configuration file is organized into key value pairs where all keys are Strings. The value for the other keys may be a ConfigurationSection or a single piece of data. The ''getKeys(boolean)'' method returns the set of keys for the current ''FileConfigurationSection''. The boolean value determines if the returned set is recursive, if true it will return the keys of the given section and their children keys, if false will only return keys of the given section. To get the keys of a particular section, the ''getKeys(boolean)'' method must be invoked on that particular section. To get the section you will have to invoke ''getConfigurationSection(String)''.

{{note|The getKeys method returns a [http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html Set] of Strings}} 

=== Paths ===

The Configuration API uses Paths to form a unique key to value pairs. A path is the set of keys used to associate a value. Each level is separated by the path separator, which is by default the '.' (period). For example the following YAML file has the following set of paths.
<blockquote><source lang="yaml">key: value
one:
  two: value
  three:
    - values
    - values
    - values
  four: 
    five: value
  *:
    six: value
    seven: value
</source></blockquote>

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

=== Default Values ===

A default ''config.yml'' should be provided in your jar for users. In the case that a config.yml is missing or incomplete, values will be loaded from included ''config.yml''. The provided file must be named ''config.yml'' and be placed in the same directory as your [[Plugin YAML|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.
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

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&lt;String,Object&gt;)'' 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. 
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== Creating a copy of config.yml ====
You can create a copy of config.yml from the jar into the plugin's data folder by invoking JavaPlugin's saveDefaultConfig() method. saveDefaultConfig() will not overwrite an existing file.

=== Getting Values ===

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 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.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== Setting Values  ===

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: 
<blockquote><source lang="java">// 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);</source></blockquote> 
<br> 

==== 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 [[#HashMaps|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 
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== Saving the File  ===
If any changes are made to the ''FileConfiguration'' with the set methods, or any ''Lists'' are mutated, 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.<blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== Reloading from Disk  ===

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. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>

=== Using an alternate configuration file ===

If for whatever reason you need another configuration file, you can use YamlConfiguration to make a new one.
<blockquote><source lang="java">FileConfiguration data = YamlConfiguration.loadConfiguration(new File(getDataFolder(), "data.yml"));</source></blockquote>
This reads the file data.yml from your data folder, and returns a FileConfiguration. If the file does not exist, the FileConfiguration is empty. If you need a pre-made FileConfiguration to be used, you can instead use an InputStream.
<blockquote><source lang="java">FileConfiguration data = YamlConfiguration.loadConfiguration(getResource("data.yml"));</source></blockquote>
This takes the InputStream from getResource, which gets a file embedded in the jar, and retreives a FileConfiguration from that.

== 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 [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html 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 [https://gist.github.com/3174347 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. 
<blockquote><source lang="java">private FileConfiguration customConfig = null;
private File customConfigFile = null;</source></blockquote>

===== 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. <blockquote><source lang="java">
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);
    }
}</source></blockquote>

===== Implementation for Getting =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk. <blockquote><source lang="java">
public FileConfiguration getCustomConfig() {
    if (customConfig == null) {
        reloadCustomConfig();
    }
    return customConfig;
}</source></blockquote>

===== Implementation for Saving =====
Finally, write the save method, which saves changes and overwrites the file on disk. <blockquote><source lang="java">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);
    }
}</source></blockquote>

===== Implementation for Defaults =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.  <blockquote><source lang="java">public void saveDefaultConfig() {
    if (customConfigFile == null) {
        customConfigFile = new File(getDataFolder(), "customConfig.yml");
    }
    if (!customConfigFile.exists()) {            
         plugin.saveResource("customConfig.yml", false);
     }
}</source></blockquote>

=== 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 ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''.<br>

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:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> 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''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 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.

<blockquote><source lang="java">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;
            }
        });
    }
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
  - Play Nice
  - Respect others
  - Have Fun
  - Dont swear</source>
{{Languages|Introduction_to_the_New_Configuration}}