新しい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ファイル中に定義されたデフォルト値もロードされます。 その後のgetConfig()の呼び出しでは、メモリ上に存在するFileConfigurationオブジェクトがreturnされます。

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

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

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

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

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

デフォルト値

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)