「新しいConfigurationの使い方」の版間の差分

2016年10月1日 (土) 14:35時点における最新版

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.*") → '*' の部分がConfigurationSectionで取得されます
getString("one.*.six") → value というStringが取得されます
getString("one.*.seven") → value というStringが取得されます

デフォルト値[編集]

あなたのプラグインの設定ファイルconfig.ymlは、プラグイン利用者のために、デフォルト値を設定するようにしてください。

もしconfig.ymlが、プラグインのデータフォルダ配下に存在しない, 空である, キーが無い・・・といった状態である場合には、プラグインのJarファイル内に含まれるconfig.ymlに定義された値が、デフォルト値として使用されます。

デフォルト値として使用するconfig.ymlは、Jarファイルのトップに配置されるようにしてください。 plugin.ymlと同一の場所になります。

プラグインのデータフォルダ配下のconfig.ymlをデフォルト値で上書きしたい場合は、JavaPluginクラスのsaveDefaultConfig()メソッドを呼び出してください。

this.saveDefaultConfig()

データフォルダにあるconfig.ymlの既存の設定値を上書きしたくないが、Jarファイル内にあるconfig.ymlに定義されている新しいキーと値のペアを追加したい場合は、copyDefaults(true) を実行してください。

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

~~config.ymlに ShiftJISで日本語を含めたプラグインは、Windowsでしか正常に起動しなくなります。~~
~~逆に、UTF-8N(BOM無し) で日本語を含めたプラグインは、MacintoshとLinuxでしか正常に起動しなくなります。~~
Bukkit 1.9 以降のバージョンでは、config.yml に日本語などのマルチバイト文字を含めたい場合は、常に UTF-8N(BOM無し) のエンコードで作成してください。

コンフィグ値の取得[編集]

コンフィグ値の読み込み処理は、複数の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されたタイミング）で失われます。

利用例:

// boolean値をセットします。
this.getConfig().set("path.to.boolean", true);

// String値をセットします。
this.getConfig().set("path.to.string", "みなさんこんにちは！");

// StringのListをセットします。
// 配列はセットできないので、List<String>型に変換してセットします。
String[] listOfStrings = {"こんにちは！", "いらっしゃいませ！", "楽しんでね！"};
this.getConfig().set("path.to.list", Arrays.asList(listOfStrings));

// Vector(Bukkitのクラス)の値をセットします。
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// 値を削除します。
this.getConfig().set("path.to.boolean", 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();

別の設定ファイルを利用する[編集]

もしあなたが、config.ymlではなく、別のYamlファイルを利用したい場合は、YamlConfiguration クラスを使って読み込むことができます。

FileConfiguration data = YamlConfiguration.loadConfiguration(new File(getDataFolder(), "data.yml"));

上記のサンプルコードは、データフォルダにあるdata.ymlファイルを読み込んで、FileConfiguration を返します。
もし、データフォルダにdata.ymlが存在しない場合は、空っぽの FileConfiguration が返されます。

利用例[編集]

以下は、新しい 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 void playerJoin(PlayerJoinEvent event) {
                // プレイヤーがサーバーに参加したときに、config.ymlに書かれたメッセージを送ります。
                event.getPlayer().sendMessage(SimpleMOTD.this.getConfig().getString("message"));

                // 特定のプレイヤーだった場合は、追加メッセージを送ります。
                if ( SimpleMOTD.this.getConfig().contains("additional." + event.getPlayer().getName()) ) {
                    event.getPlayer().sendMessage(SimpleMOTD.this.getConfig().getString(
                            "additional." + event.getPlayer().getName()));
                }
            }
        }, 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
additional:
  Anna: Hi Anna!
  Billy: Hey Billy!

@@ 122行目: / 122行目: @@
 利用例: <blockquote><source lang="java">
-// setting a boolean value
+// boolean値をセットします。
 this.getConfig().set("path.to.boolean", true);
-// setting a String
+// String値をセットします。
-String string = "Hello World!";
+this.getConfig().set("path.to.string", "みなさんこんにちは！");
-this.getConfig().set("path.to.string", stringValue);
-// Setting a List of Strings
+// StringのListをセットします。
-// The List of Strings is first defined in this array
+// 配列はセットできないので、List<String>型に変換してセットします。
-String[] listOfStrings = {"Hello World", "Welcome to Bukkit", "Have a Good Day!"};
+String[] listOfStrings = {"こんにちは！", "いらっしゃいませ！", "楽しんでね！"};
-this.getConfig().set("path.to.list", Arrays.asList(listOfStrings);
+this.getConfig().set("path.to.list", Arrays.asList(listOfStrings));
-// Setting a vector
+// Vector(Bukkitのクラス)の値をセットします。
-// 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>
+this.getConfig().set("path.to.boolean", null);
+</source></blockquote>
 ==== HashMapの活用 ====
@@ 147行目: / 145行目: @@
 また、HashMapはキーがString型、値が''ConfigurationSerializable''を実装したデータ型でなければなりません。
 <blockquote><source lang="java">createSection (String path, Map< String, Object > map)</source></blockquote>
 === コンフィグファイルのセーブ ===
@@ 157行目: / 154行目: @@
 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
-<!--
+=== 別の設定ファイルを利用する ===
+もしあなたが、''config.yml''ではなく、別のYamlファイルを利用したい場合は、YamlConfiguration クラスを使って読み込むことができます。
+<blockquote><source lang="java">
+FileConfiguration data = YamlConfiguration.loadConfiguration(new File(getDataFolder(), "data.yml"));
+</source></blockquote>
+上記のサンプルコードは、データフォルダにある''data.yml''ファイルを読み込んで、FileConfiguration を返します。<br/>
+もし、データフォルダに''data.yml''が存在しない場合は、空っぽの FileConfiguration が返されます。<br/>
+<!-- なんか微妙。この説明、要るかなあ？
+もしあなたが、Jarファイル内の''data.yml''を読み出したいなら、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.
+-->
+<!-- 下記の内容は、内容が難しくて、かえって混乱を生むので、いまのところ非表示にしています。
 == 応用 ==
@@ 343行目: / 361行目: @@
          // もしconfig.ymlが存在しないなら、既定のconfig.ymlをコピーします。
          this.saveDefaultConfig();
          // 新しいリスナーを登録します。
          getServer().getPluginManager().registerEvents(new Listener() {
              @EventHandler
-             public playerJoin(PlayerJoinEvent event) {
+             public void playerJoin(PlayerJoinEvent event) {
                  // プレイヤーがサーバーに参加したときに、config.ymlに書かれたメッセージを送ります。
                  event.getPlayer().sendMessage(SimpleMOTD.this.getConfig().getString("message"));
+                // 特定のプレイヤーだった場合は、追加メッセージを送ります。
+                if ( SimpleMOTD.this.getConfig().contains("additional." + event.getPlayer().getName()) ) {
+                    event.getPlayer().sendMessage(SimpleMOTD.this.getConfig().getString(
+                            "additional." + event.getPlayer().getName()));
+                }
              }
          }, this);
@@ 356行目: / 380行目: @@
          // 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)
+                 for (String s : rules) {
                      sender.sendMessage(s);
                  }
@@ 378行目: / 402行目: @@
    - Respect others
    - Have Fun
+additional:
+  Anna: Hi Anna!
+  Billy: Hey Billy!
 </source>