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()の戻り値は一旦適切なフィールドに割り当ててから利用する事をお勧めします
デフォルト値
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)
コンフィグ値の取得
コンフィグ値の読み込み処理は、複数のgetterメソッドの呼び出し処理から成ります。全てのgetterメソッドの一覧はこちらです。一般的な用途のgetterメソッドは下記です。
- getBoolean(String)
- getInt(String)
- getString(String)
- getList(String)
- getStringList(String)
Keyの活用
キーを用いたコンフィグ値の取得処理には、FileConfigurationSection（コンフィグファイルの階層構造を表すオブジェクト）と、それにアクセスするためのキーと呼ばれる値を利用して行います。キー値の取得にはgetKeys(boolean)メソッドを用い、セクションの取得にはgetConfigurationSection(String)メソッドを用います。キーに先立って、コンフィグファイルのセクションが必要です。
getKeys(boolean)メソッドのboolean型パラメタは、キーを再帰的に取得するかどうかを指定します。trueであれば、子階層のキーも含めて取得します。falseであれば、対象階層のみのキーを返します。
- getKeys(boolean)
- Note: このメソッドは、String型のSet を返します。
コンフィグ値のセット
コンフィグ値をセットするには、設定ファイルのインスタンスの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();
応用
以下は、より高度なプラグインを製作するための、応用のトピックです。
あなたは既定のconfig.ymlを作成するだけでよく、保存したり、移動したりする必要は今後ありません。
コンフィグのオプション
全てのFileConfigurationインスタンスは、FileConfigurationOptions オブジェクトに紐付いています。
FileConfigurationOptionsオブジェクトは、FileConfigurationの動作を制御することができます。
FileConfigurationのoptions()メソッドは、対応したFileConfigurationOptionsを返します。
これを使って、オプションの現在内容の確認をしたり、設定を行うことができます。
現在、4つのオプションがあります。
メソッドはオーバーロードされているものがあり、例えば、copyDefaults()はブール値を返しますが、copyDefaults(boolean)は自分自身を返します。これらには、状態を変更する場合があることに注意してください。
CopyDefaults
CopyDefaultsオプションはConfigurationクラスのsaveメソッドを変更しています。
既定では、デフォルトのコンフィグを保存先ファイルに上書きしません。
もし引数にtrueが設定された場合、ファイルの上書きをします。
しかし、1度書き込みが行われるのみで、あなたがデフォルト値を変更したとしてもその値が反映されるわけではありません。
PathSeparator
PathSeparatorは、コンフィグの階層を示すセパレータ文字の変更を行うことができます。
既定では「.」(ピリオド)ですが、好きな文字へ変更することが可能です。
Header
HeaderはYAMLファイルの上部のコメントブロックの変更を行うことができます。
HeaderはコンフィグAPIの中で、唯一、コメントをコピーすることができる手段です。
copyHeader()
もしcopyHeader()がtrueを返したら、既定のconfig.ymlから保存先にヘッダーを保存したことを示します。