新しいConfigurationの使い方

Configuration APIは、人が読み書き可能な形式のコンフィグファイルの解析と出力を素早く行う機能のセットです。

～APIという名前によらず、簡単にプラグインのデータを、コンフィグファイルへ保管する事が出来ます。
YAML 形式のファイルのみに対応しています。
APIは、いかに独自の拡張に対応しやすくするかを考えて設計されています。

Configuration APIは、org.bukkit.configurationとorg.bukkit.configuration.file パッケージの配下にあります。
Bukkit1.1-R5以前に作られたプラグインは、org.bukkit.util.configurationパッケージ配下に存在した、
古いライブラリを利用した実装を採用しているかもしれません。
新旧の実装方法には互換性がありませんので、古いパッケージを使う処理は除去して下さい。

このページの解説は、オブジェクト指向とJava、Bukkitプラグインの基本的な設計に関する知識が、
いくらかある読者に読まれる事を想定しています。
このページは、BukkitのJavadoc内のFileConfiguration Classに取って代わる内容ではありません。

基礎

コンフィグファイルのオブジェクト

あなたのプラグインがJavaPluginをextendsし、フィールドとメソッドを継承しているものとして話を進めます。

継承メソッドgetConfig()は、 org.bukkit.configuration.file.FileConfiguration型のオブジェクトをreturnしますが、 このオブジェクトは、プラグインのデータフォルダ配下のconfig.ymlに相当します。

初めてgetConfig()が呼び出されたタイミングでは、ディスク上のconfig.ymlの内容と、プラグインのJarファイル中に定義されたデフォルト値が、メモリ上にロードされ、その内容が戻り値として返されます。2回目以降のgetConfig()の呼び出しでは、メモリ上に存在するFileConfigurationオブジェクトが戻り値として返されます。

このオブジェクトは、明示的に保存しない限りディスクへ保持されません。同様に、config.ymlファイルに加えられた変更も、メモリ上にロード済みのオブジェクトには反映されません。

config.ymlがデータフォルダ配下に存在しない場合は、空のconfig.ymlファイルを読み込んだ事と等しい結果となり、FileConfigurationオブジェクトも空の状態でロードされます。

Warning: getConfig()の戻り値は、staticなフィールドに割り当てないで下さい。

Warning: このような割り当てを行うと、getConfig()はreloadConfigの後でも再び割り当て処理を繰り返してしまいます。

Note:getConfig()の戻り値は一旦適切なフィールドに割り当ててから利用する事をお勧めします

キー

コンフィグファイルは、すべての設定内容が、Stringのkeyと、valueのペアで構成されています。 valueは、ConfigurationSection または、単一値の型になります。

FileConfigurationSection の getKeys(boolean) メソッドは、指定されたセクション以下のkeyを返します。

falseが指定された場合は、セクション直下にあるkeyが返されます。 trueが指定された場合は、セクション直下だけでなく、その子セクションや孫セクションも含めて全てのkeyが返されます。 ある特定のセクションを取得したい場合は、getKeys(boolean) で探して取得する方法もありますが、getConfigurationSection(String) を使って直接取得することもできます。

Warning: getKeys(boolean) メソッドは、Set<String> を返します。

パス

コンフィグAPIは、キーと値を階層的に持つことができます。 ピリオド（.）で区切ることで、階層をそのまま指定して、セクションやvalueを取得することができます。 実例を見てみましょう。

key: 'value'
one:
  two: 'value'
  three:
    - 1
    - 2
    - 3
  four: 
    five: 'value'
  '*':
    six: 'value'
    seven: 'value'

上記の例では、次のようにkeyを指定することで、valueを取得できます。

• getString("key") → value というStringが取得されます
• getConfigurationSection("one") → one の部分がConfigurationSectionで取得されます
• getString("one.two") → value というStringが取得されます
• getIntegerList("one.three") → [1, 2, 3] というIntegerの配列が取得されます
• getConfigurationSection("one.four") → four の部分がConfigurationSectionで取得されます
• getString("one.four.five") → value というStringが取得されます
• getConfigurationSection("one.*") → four の部分がConfigurationSectionで取得されます
• getString("one.*.six") → value というStringが取得されます
• getString("one.*.seven") → value というStringが取得されます

デフォルト値

config.ymlのデフォルト値は、プラグインのユーザに提供されます。 設定ファイルが、プラグインのデータディレクトリ配下に存在しない, 空である, キーが無い・・・といった状態である場合には、プラグインのJarファイル内に定義された値が、デフォルト値としてロードされます。

デフォルト値は、データフォルダ配下に存在するconfig.ymlが提供しようと意図していた内容と、まったく同一な内容のYAML形式ファイルによって提供されるべきで、そのファイル名はconfig.ymlであり、plugin.ymlと同一の場所に配置されている必要があります。

プラグインのデータフォルダ配下のconfig.ymlをデフォルト値で上書きしたい場合は、JavaPluginクラスのsaveDefaultConfig()メソッドを呼び出す必要があります。既存のファイルを上書きしたくない場合は、copyDefaultsオプションにtrueを設定します。

動的な値をデフォルト値とする場合、addDefaults(Map<String,Object>)やaddDefault(String, Object)のようにコーディングする事で実現できます。

特殊なケースとして、新規のデフォルト値を既存のconfig.ymlに追加したい場合は、copyDefaultsにtrueをセットします。

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

Warning: 訳者註：とても重要 デフォルトのconfig.ymlには、日本語のようなマルチバイトを含めないようにしてください！

config.ymlに ShiftJISで日本語を含めたプラグインは、Windowsでしか正常に起動しなくなります。
逆に、UTF-8N(BOM無し) で日本語を含めたプラグインは、MacintoshとLinuxでしか正常に起動しなくなります。

コンフィグ値の取得

コンフィグ値の読み込み処理は、複数のgetterメソッドの呼び出し処理から成ります。全てのgetterメソッドの一覧はこちらです。一般的な用途のgetterメソッドは下記です。

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

コンフィグ値のセット

コンフィグ値をセットするには、設定ファイルのインスタンスのset(String, Object)メソッドを利用します。FileConfigurationのgetメソッドとは異なり、setメソッドは1種類しか存在しません。setメソッドであらゆる型のオブジェクトがセット出来る訳ではく、下記のデータ型のオブジェクトだけがセット可能です。

• プリミティブ
• String
• List
• VectorやItemStackのようなConfigurationSerializableインタフェースを実装した型

コンフィグ値を削除するにはnullをセットします。セット処理は、メモリ上に展開されたコンフィグ値に対してのみ行われ、コンフィグ値をファイルにセーブしなければ、サーバを再起動したタイミング（正確にはプラグインがdisabledされたタイミング）で失われます。

利用例:

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

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

// Setting a List of Strings
// The List of Strings is first defined in this array
String[] listOfStrings = {"Hello World", "Welcome to Bukkit", "Have a Good Day!"};
this.getConfig().set("path.to.list", Arrays.asList(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);

HashMapの活用

HashMapをコンフィグ値としてセーブする場合は、ConfigurationSectionを利用して下さい。 また、HashMapはキーがString型、値がConfigurationSerializableを実装したデータ型でなければなりません。

createSection (String path, Map< String, Object > map)

コンフィグファイルのセーブ

setメソッドを利用してFileConfigurationに多くの変更を加えるか、Lists（設定値インスタンスの内部値がList派生型になっている領域を指している）の内容を変更した場合、プラグインの無効化後も残したい設定値であればディスクに書き出すべきです。saveConfigメソッドを呼び出して、既存の（ディスク上の）コンフィグファイルに上書き保存しましょう。

this.saveConfig();

ディスクからのリロード

プラグインのデータフォルダ上のconfig.ymlが、ユーザによって変更されている可能性を疑って下さい。この変更点はメモリ上の設定値に反映されていません。reloadConfig()メソッドを呼び出して、ディスク上の設定値をプラグインにロードする事ができます。ただしメモリ上の設定値が、ロード内容で上書きされる事にも留意して下さい。

this.reloadConfig();

利用例

以下は、新しい Configuration API を使ってプラグインを実装した例です。
プレイヤー参加時に config.yml から message を取得して MOTD としてメッセージを表示したり、 rulesコマンド実行時に config.yml から rules を取得して表示したりします。
なるべく手短な例を示したので、最適な実装例になっていないことをご了承ください。

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() {
        // もしconfig.ymlが存在しないなら、既定のconfig.ymlをコピーします。
        this.saveDefaultConfig();
        
        // 新しいリスナーを登録します。
        getServer().getPluginManager().registerEvents(new Listener() {
            
            @EventHandler
            public playerJoin(PlayerJoinEvent event) {
                // プレイヤーがサーバーに参加したときに、config.ymlに書かれたメッセージを送ります。
                event.getPlayer().sendMessage(SimpleMOTD.this.getConfig().getString("message"));
            }
        }, this);

        // rulesコマンドのCommandExecutorを登録します。
        this.getCommand("rules").setExecutor(new CommandExecutor() {
            
            public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
                // コマンド実行時にコマンド実行者へ、config.ymlのrulesの内容を送ります。
                List<String> rules = SimpleMOTD.this.getConfig().getStringList("rules");
                for (String s : rules)
                    sender.sendMessage(s);
                }
                return true;
            }
        });
    }
}

デフォルトのconfig.ymlの内容は、下記のとおりです。

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