| 最新版 |
編集中の文章 |
| 1行目: |
1行目: |
| − | Configuration APIは、人が読み書き可能な形式のコンフィグファイルの解析と出力を素早く行う機能のセットです。<br/> | + | Configuration APIは、人が読み書き可能な形式のコンフィグファイルの、<br/> |
| | + | 解析と出力を素早く行う機能のセットです。<br/> |
| | | | |
| | ～APIという名前によらず、簡単にプラグインのデータを、コンフィグファイルへ保管する事が出来ます。<br/> | | ～APIという名前によらず、簡単にプラグインのデータを、コンフィグファイルへ保管する事が出来ます。<br/> |
| − | [http://ja.wikipedia.org/wiki/YAML YAML] 形式のファイルのみに対応しています。<br/> | + | [http://en.wikipedia.org/wiki/YAML YAML] 形式のファイルのみに対応しています。<br/> |
| | APIは、いかに独自の拡張に対応しやすくするかを考えて設計されています。<br/> | | APIは、いかに独自の拡張に対応しやすくするかを考えて設計されています。<br/> |
| | | | |
| 21行目: |
22行目: |
| | このオブジェクトは、プラグインのデータフォルダ配下の''config.yml''に相当します。 | | このオブジェクトは、プラグインのデータフォルダ配下の''config.yml''に相当します。 |
| | | | |
| − | 初めて''getConfig()''が呼び出されたタイミングでは、ディスク上の''config.yml''の内容と、プラグインのJarファイル中に定義されたデフォルト値が、メモリ上にロードされ、その内容が戻り値として返されます。2回目以降の''getConfig()''の呼び出しでは、メモリ上に存在する''FileConfiguration''オブジェクトが戻り値として返されます。 | + | 初めて''getConfig()''が呼び出されたタイミングで、''config.yml''はディスクからロードされ、プラグインのJarファイル中に定義されたデフォルト値もロードされます。 |
| | + | その後の''getConfig()''の呼び出しでは、メモリ上に存在する''FileConfiguration''オブジェクトがreturnされます。 |
| | | | |
| | このオブジェクトは、明示的に保存しない限りディスクへ保持されません。同様に、''config.yml''ファイルに加えられた変更も、メモリ上にロード済みのオブジェクトには反映されません。 | | このオブジェクトは、明示的に保存しない限りディスクへ保持されません。同様に、''config.yml''ファイルに加えられた変更も、メモリ上にロード済みのオブジェクトには反映されません。 |
| | | | |
| | ''config.yml''がデータフォルダ配下に存在しない場合は、空の''config.yml''ファイルを読み込んだ事と等しい結果となり、''FileConfiguration''オブジェクトも空の状態でロードされます。 | | ''config.yml''がデータフォルダ配下に存在しない場合は、空の''config.yml''ファイルを読み込んだ事と等しい結果となり、''FileConfiguration''オブジェクトも空の状態でロードされます。 |
| − |
| |
| | {{warning}} ''getConfig()''の戻り値は、staticなフィールドに割り当てないで下さい。 | | {{warning}} ''getConfig()''の戻り値は、staticなフィールドに割り当てないで下さい。 |
| − | | + | {{warning}} このような割り当てを行うと、''getConfig()''はreloadConfigの後でも再び割り当て処理を繰り返してしまいます。{{note}}''getConfig()''の戻り値は一旦適切なフィールドに割り当ててから利用する事をお勧めします |
| − | {{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を取得することができます。
| |
| − | 実例を見てみましょう。
| |
| − | | |
| − | <blockquote><source lang="yaml">
| |
| − | key: 'value'
| |
| − | one:
| |
| − | two: 'value'
| |
| − | three:
| |
| − | - 1
| |
| − | - 2
| |
| − | - 3
| |
| − | four:
| |
| − | five: 'value'
| |
| − | '*':
| |
| − | six: 'value'
| |
| − | seven: 'value'
| |
| − | </source></blockquote>
| |
| − | | |
| − | 上記の例では、次のように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''のデフォルト値は、プラグインのユーザに提供されます。 |
| | + | 設定ファイルが、プラグインのデータディレクトリ配下に存在しない、空である、キーが無い・・・といった状態である場合には、プラグインのJarファイル内に定義された値が、デフォルト値としてロードされます。 |
| | | | |
| − | あなたのプラグインの設定ファイル''config.yml''は、プラグイン利用者のために、デフォルト値を設定するようにしてください。
| + | デフォルト値は、データフォルダ配下に存在する''config.yml''が提供しようと意図していた内容と、まったく同一な内容のYAML形式ファイルによって提供されるべきで、そのファイル名は''config.yml''であり、[[Plugin YAML|plugin.yml]]と同一の場所に配置されている必要があります。 |
| − | | |
| − | もし''config.yml''が、プラグインのデータフォルダ配下に存在しない, 空である, キーが無い・・・といった状態である場合には、プラグインのJarファイル内に含まれる''config.yml''に定義された値が、デフォルト値として使用されます。
| |
| − | | |
| − | デフォルト値として使用する''config.yml''は、Jarファイルのトップに配置されるようにしてください。
| |
| − | [[Plugin YAML|plugin.yml]]と同一の場所になります。 | |
| | | | |
| − | プラグインのデータフォルダ配下の''config.yml''をデフォルト値で上書きしたい場合は、JavaPluginクラスの''saveDefaultConfig()''メソッドを呼び出してください。 | + | プラグインのデータフォルダ配下の''config.yml''をデフォルト値で上書きしたい場合は、JavaPluginクラスの''saveDefaultConfig()''メソッドを呼び出す必要があります。既存のファイルを上書きしたくない場合は、copyDefaultsオプションにtrueを設定します。 |
| | | | |
| − | <blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>
| + | 動的な値をデフォルト値とする場合、addDefaults(Map<String,Object>)や'''addDefault(String, Object)'''のようにコーディングする事で実現できます。 |
| | | | |
| − | データフォルダにある''config.yml''の既存の設定値を上書きしたくないが、Jarファイル内にある''config.yml''に定義されている新しいキーと値のペアを追加したい場合は、copyDefaults(true) を実行してください。
| + | 特殊なケースとして、新規のデフォルト値を既存の''config.yml'' に追加したい場合は、copyDefaultsにtrueをセットします。 <blockquote><source lang="java">getConfig().options().copyDefaults(true)</source></blockquote> |
| − | | |
| − | <blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote> | |
| − | | |
| − | <strike>config.ymlに ShiftJISで日本語を含めたプラグインは、Windowsでしか正常に起動しなくなります。</strike><br>
| |
| − | <strike>逆に、UTF-8N(BOM無し) で日本語を含めたプラグインは、MacintoshとLinuxでしか正常に起動しなくなります。</strike><br>
| |
| − | Bukkit 1.9 以降のバージョンでは、config.yml に日本語などのマルチバイト文字を含めたい場合は、常に UTF-8N(BOM無し) のエンコードで作成してください。
| |
| | | | |
| | === コンフィグ値の取得 === | | === コンフィグ値の取得 === |
| − | | + | 設定値の読み込み処理は、多くのgetterメソッドの呼び出し処理から成り立ちます。全てのgetterメソッドの一覧は[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html こちら]です。一般的な用途のgetterメソッドは下記です。 |
| − | コンフィグ値の読み込み処理は、複数のgetterメソッドの呼び出し処理から成ります。全てのgetterメソッドの一覧は[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html こちら]です。一般的な用途のgetterメソッドは下記です。
| |
| | *getBoolean(String) | | *getBoolean(String) |
| | *getInt(String) | | *getInt(String) |
| 111行目: |
51行目: |
| | *getStringList(String) | | *getStringList(String) |
| | | | |
| | + | ==== Keys ==== |
| | + | キーを用いた値の取得処理には、'''FileConfigurationSection'''（設定ファイルの階層構造を表すオブジェクト）と、セクションにアクセスするための'''キー'''と呼ばれる値を利用して行います。キー値の取得には''getKeys(boolean)''メソッドを用い、セクションの取得には''getConfigurationSection(String)''メソッドを用います。キーに先立って、設定ファイルのセクションが必要です。 |
| | | | |
| − | === コンフィグ値のセット === | + | ''getKeys(boolean)''メソッドのboolean型パラメタは、キーを再帰的に取得するかどうかを指定します。trueであれば、子階層のキーも含めて取得します。falseであれば、対象階層のみのキーを返します。 |
| − | コンフィグ値をセットするには、設定ファイルのインスタンスの''set(String, Object)''メソッドを利用します。''FileConfiguration''のgetメソッドとは異なり、setメソッドは1種類しか存在しません。setメソッドであらゆる型のオブジェクトがセット出来る訳ではく、下記のデータ型のオブジェクトだけがセット可能です。
| + | |
| | + | *getKeys(boolean) |
| | + | {{note}} このメソッドは、String型の[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html Set] を返します。 |
| | + | |
| | + | === 設定値のセット === |
| | + | 設定値をセットするには、設定ファイルのインスタンスの''set(String, Object)''メソッドを利用します。''FileConfiguration''のgetメソッドとは異なり、setメソッドは1種類しか存在しません。setメソッドであらゆる型のオブジェクトがセット出来る訳ではく、下記のデータ型のオブジェクトだけがセット可能です。 |
| | *プリミティブ | | *プリミティブ |
| | *''String'' | | *''String'' |
| − | *''List'' | + | *''Lists'' |
| | *''Vector''や''ItemStack''のような''ConfigurationSerializable''インタフェースを実装した型 | | *''Vector''や''ItemStack''のような''ConfigurationSerializable''インタフェースを実装した型 |
| | | | |
| − | コンフィグ値を削除するにはnullをセットします。セット処理は、メモリ上に展開されたコンフィグ値に対してのみ行われ、コンフィグ値をファイルにセーブしなければ、サーバを再起動したタイミング（正確にはプラグインがdisabledされたタイミング）で失われます。
| + | 設定値を削除するには、nullをセットします。値のセット処理は、メモリ上に展開された設定値に大してのみ行われ、設定値をファイルにセーブしなければ、サーバを再起動したタイミングで失われます。 |
| | | | |
| | 利用例: <blockquote><source lang="java"> | | 利用例: <blockquote><source lang="java"> |
| − | // boolean値をセットします。 | + | // setting a boolean value |
| | this.getConfig().set("path.to.boolean", true); | | this.getConfig().set("path.to.boolean", true); |
| | | | |
| − | // String値をセットします。 | + | // setting a String |
| − | this.getConfig().set("path.to.string", "みなさんこんにちは！"); | + | String string = "Hello World!"; |
| | + | this.getConfig().set("path.to.string", stringValue); |
| | | | |
| − | // StringのListをセットします。 | + | // Setting a List of Strings |
| − | // 配列はセットできないので、List<String>型に変換してセットします。 | + | // The List of Strings is first defined in this array |
| − | String[] listOfStrings = {"こんにちは！", "いらっしゃいませ！", "楽しんでね！"}; | + | String[] listOfStrings = {"Hello World", "Welcome to Bukkit", "Have a Good Day!"}; |
| − | this.getConfig().set("path.to.list", Arrays.asList(listOfStrings)); | + | this.getConfig().set("path.to.list", Arrays.asList(listOfStrings); |
| | | | |
| − | // Vector(Bukkitのクラス)の値をセットします。 | + | // Setting a vector |
| | + | // event is assumed to be an existing event inside an "onEvent" method. |
| | Vector vector = event.getPlayer().getLocation().toVector(); | | Vector vector = event.getPlayer().getLocation().toVector(); |
| | this.getConfig().set("path.to.vector", vector); | | this.getConfig().set("path.to.vector", vector); |
| | | | |
| − | // 値を削除します。 | + | // Erasing a value |
| − | this.getConfig().set("path.to.boolean", null); | + | this.getConfig().set("path.to.value", null);</source></blockquote><br> |
| − | </source></blockquote> | |
| | | | |
| − | ==== HashMapの活用 ==== | + | ==== HashMaps ==== |
| − | ''HashMap''をコンフィグ値としてセーブする場合は、''ConfigurationSection''を利用して下さい。 | + | ''HashMap''を設定値としてセーブする場合は、''ConfigurationSection''を利用して下さい。 |
| | また、HashMapはキーがString型、値が''ConfigurationSerializable''を実装したデータ型でなければなりません。 | | また、HashMapはキーがString型、値が''ConfigurationSerializable''を実装したデータ型でなければなりません。 |
| | <blockquote><source lang="java">createSection (String path, Map< String, Object > map)</source></blockquote> | | <blockquote><source lang="java">createSection (String path, Map< String, Object > map)</source></blockquote> |
| 148行目: |
96行目: |
| | === コンフィグファイルのセーブ === | | === コンフィグファイルのセーブ === |
| | setメソッドを利用して''FileConfiguration''に多くの変更を加えるか、''Lists''（設定値インスタンスの内部値がList派生型になっている領域を指している）の内容を変更した場合、プラグインの無効化後も残したい設定値であればディスクに書き出すべきです。'''saveConfig'''メソッドを呼び出して、既存の（ディスク上の）コンフィグファイルに上書き保存しましょう。<blockquote><source lang="java">this.saveConfig();</source></blockquote> | | setメソッドを利用して''FileConfiguration''に多くの変更を加えるか、''Lists''（設定値インスタンスの内部値がList派生型になっている領域を指している）の内容を変更した場合、プラグインの無効化後も残したい設定値であればディスクに書き出すべきです。'''saveConfig'''メソッドを呼び出して、既存の（ディスク上の）コンフィグファイルに上書き保存しましょう。<blockquote><source lang="java">this.saveConfig();</source></blockquote> |
| − |
| |
| | | | |
| | === ディスクからのリロード === | | === ディスクからのリロード === |
| − | プラグインのデータフォルダ上の''config.yml''が、ユーザによって変更されている可能性を疑って下さい。この変更点はメモリ上の設定値に反映されていません。''reloadConfig()''メソッドを呼び出して、ディスク上の設定値をプラグインにロードする事ができます。ただしメモリ上の設定値が、ロード内容で上書きされる事にも留意して下さい。 | + | プラグインのデータフォルダ上の''config.yml''が、ユーザによって変更されている可能性を疑って下さい。この変更点はメモリ上の設定値に反映されていません。''reloadConfig()''メソッドを呼び出して、ディスク上の設定値をプラグインにロードする事ができます。ただし、メモリ上の設定値がロードされる内容で上書きされる事にも留意して下さい。<source lang="java">this.reloadConfig();</source> |
| − | <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.
| |
| − | -->
| |
| − |
| |
| − | <!-- 下記の内容は、内容が難しくて、かえって混乱を生むので、いまのところ非表示にしています。
| |
| | == 応用 == | | == 応用 == |
| − |
| |
| − | 以下は、より高度なプラグインを製作するための、応用のトピックです。<br>
| |
| − | あなたが既定の''config.yml''を作成したり読み込んだり保存したいだけであれば、下記を読む必要はありません。
| |
| − |
| |
| | === コンフィグのオプション === | | === コンフィグのオプション === |
| − | | + | ==== デフォルト値のコピー ==== |
| − | 全ての''FileConfiguration''インスタンスは、[http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] オブジェクトに紐付いています。<br>
| + | ==== パスのセパレータ ==== |
| − | ''FileConfigurationOptions''オブジェクトは、''FileConfiguration''の動作を制御することができます。<br>
| + | ==== ヘッダ ==== |
| − | ''FileConfiguration''の''options()''メソッドは、対応した''FileConfigurationOptions''を返します。<br>
| |
| − | これを使って、オプションの現在内容の確認をしたり、設定を行うことができます。<br>
| |
| − | 現在、4つのオプションがあります。<br>
| |
| − | メソッドはオーバーロードされているものがあり、例えば、''copyDefaults()''はブール値を返しますが、''copyDefaults(boolean)''は自分自身を返します。<br>
| |
| − | '''訳者注''' 引数を指定しないメソッドは現在のオプション値を返し、引数を指定するメソッドはオプション値を設定するメソッドです。
| |
| − | | |
| − | ==== CopyDefaults ==== | |
| − | | |
| − | ''CopyDefaults''オプションは''Configuration''クラスのsaveメソッドの動作を変更します。<br>
| |
| − | 既定はfalseで、デフォルトのコンフィグを保存先ファイルに上書きしません。<br>
| |
| − | 引数にtrueを設定した場合、ファイルの上書きをするようになります。<br>
| |
| − | しかし、1度書き込みが行われるのみで、あなたがデフォルト値を変更したとしてもその値が即座に反映されるわけではありません。
| |
| − | | |
| − | ==== PathSeparator ==== | |
| − | | |
| − | PathSeparatorは、コンフィグの階層を示すセパレータ文字の変更を行うことができます。<br>
| |
| − | 既定では「.」(ピリオド)ですが、好きな文字へ変更することが可能です。
| |
| − | | |
| − | ==== Header ==== | |
| − | | |
| − | HeaderはYAMLファイルの上部のコメントブロックの変更を行うことができます。<br>
| |
| − | HeaderはコンフィグAPIの中で、唯一、コメントをコピーすることができる手段です。
| |
| − | | |
| | ==== copyHeader() ==== | | ==== copyHeader() ==== |
| − | | + | === 取得・リロード・セーブとカスタマイズ === |
| − | もし''copyHeader()''がtrueを返したら、既定のconfig.ymlから保存先にヘッダーを保存したことを示します。
| + | === シリアライズとデ・シリアライズ === |
| − | | |
| − | === 任意の設定 ===
| |
| − | | |
| − | 構成情報の格納やゲームの追加情報を保存する追加の YAML ファイルが必要な場合は、追加のコンフィグファイルにアクセスするための独自のメソッドを記述する必要があります。<br>
| |
| − | JavaPlugin クラスの getConfig、reloadConfig、saveConfig メソッドをモデルとして、カスタムコンフィグファイルを保存する独自のメソッドを記述する方法を示します。<br>
| |
| − | これらの config ファイルはプラグインに属しているため、config.yml が配置されるパッケージにおいて、アクセス権をもったメソッドからアクセスされる必要があります。<br>
| |
| − | これらのメソッドの各 YAML ファイルのセットを記述する必要があります。<br>
| |
| − | ここでは、利点はであるデフォルトの config.yml を提供されているメソッドと同じ方法で各セットを使用することができます。<br>
| |
| − | 代わりに、追加メソッドは少なくすみ、複数ファイルへのアクセスをすることもできます。
| |
| − | | |
| − | ==== JavaPlugin 実装をミラーリング ====
| |
| − | | |
| − | JavaPlugin メソッドの config.yml を実装します。<br>
| |
| − | プラグインはプラグインに固有のコンフィグファイルにアクセスする独自のメソッドを実装する必要があります。<br>
| |
| − | プラグインのメソッドを実装した後、それと同じコンテキストで継承された''getConfig()''、 ''reloadConfig()''、 ''saveConfig()''、および ''saveDefaultConfig()''メソッドで呼び出すことができます。<br>
| |
| − | 下記のコード例では、1つのクラスで複数の yaml ファイルにアクセスすることができます。<br>
| |
| − | このようなクラス実装例を、 [https://gist.github.com/3174347 ここに] 示します。
| |
| − | | |
| − | まず、2つのフィールドを宣言し、カスタム構成ファイルごとに null に初期化する必要があります。<br>
| |
| − | 1つは''FileConfiguration''オブジェクトを保持し、1つは''File''オブジェクトを保持します。<br>
| |
| − | Fileオブジェクトはディスク上のファイル、FileConfiguration は設定の内容を表します。
| |
| − | | |
| − | <blockquote><source lang="java">
| |
| − | private FileConfiguration customConfig = null;
| |
| − | private File customConfigFile = null;
| |
| − | </source></blockquote>
| |
| − | | |
| − | ===== リロードの実装 ===== | |
| − | | |
| − | 次に、ディスクからコンフィグを読み込むメソッドを記述します。<br>
| |
| − | ファイルをロードし、デフォルトの customConfig.yml の jar を検索します。
| |
| − | | |
| − | <blockquote><source lang="java">
| |
| − | public void reloadCustomConfig() {
| |
| − | if (customConfigFile == null) {
| |
| − | customConfigFile = new File(getDataFolder(), "customConfig.yml");
| |
| − | }
| |
| − | customConfig = YamlConfiguration.loadConfiguration(customConfigFile);
| |
| − | | |
| − | // jarファイルの中からデフォルトを探します。
| |
| − | InputStream defConfigStream = this.getResource("customConfig.yml");
| |
| − | if (defConfigStream != null) {
| |
| − | YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
| |
| − | customConfig.setDefaults(defConfig);
| |
| − | }
| |
| − | }
| |
| − | </source></blockquote>
| |
| − | | |
| − | ===== 取得処理の実装 =====
| |
| − | | |
| − | 次に、取得処理メソッドを記述する必要があります。<br>
| |
| − | CustomConfigをディスクから読み込む場合、nullであるかを確認します。
| |
| − | | |
| − | <blockquote><source lang="java">
| |
| − | public FileConfiguration getCustomConfig() {
| |
| − | if (customConfig == null) {
| |
| − | this.reloadCustomConfig();
| |
| − | }
| |
| − | return customConfig;
| |
| − | }
| |
| − | </source></blockquote>
| |
| − | | |
| − | ===== 保存の実装 =====
| |
| − | | |
| − | 最後に、変更を保存しディスク上のファイルを上書きする、保存メソッドを記述します。
| |
| − | | |
| − | <blockquote><source lang="java">
| |
| − | public void saveCustomConfig() {
| |
| − | if (customConfig == null || customConfigFile == null) {
| |
| − | return;
| |
| − | }
| |
| − | try {
| |
| − | getCustomConfig().save(customConfigFile);
| |
| − | } catch (IOException ex) {
| |
| − | this.getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
| |
| − | }
| |
| − | }
| |
| − | </source></blockquote>
| |
| − | | |
| − | ===== 規定値の実装 =====
| |
| − | | |
| − | 必要に応じて、JavaPlugin の saveDefaultConfig() メソッドを模倣するメソッドを記述することができます。
| |
| − | | |
| − | <blockquote><source lang="java">
| |
| − | public void saveDefaultConfig() {
| |
| − | if (customConfigFile == null) {
| |
| − | customConfigFile = new File(getDataFolder(), "customConfig.yml");
| |
| − | }
| |
| − | if (!configFile.exists()) {
| |
| − | this.plugin.saveResource(fileName, false);
| |
| − | }
| |
| − | }
| |
| − | </source></blockquote>
| |
| − | | |
| − | === シリアライズとデシリアライズ ===
| |
| − | | |
| − | コンフィグAPI は、前述のように''ConfigurationSerializable''インターフェイスを実装する Java オブジェクトを格納することができます。<br>
| |
| − | オブジェクトのシリアル化では、各種オブジェクトを簡単に保存したり読み込んだりする仕組みを、実装者に提供してくれています。<br>
| |
| − | 例えば開発者は、''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]''を取得できるシリアライズラッパークラスを使うことで、YAMLに''Location''を保存するような処理がとても簡単に使用することができます。
| |
| − | | |
| − | API でシリアル化することができるクラスを実装するには、''ConfigurationSerializable''インターフェイスを実装するだけでなく、以下のいずれかを実装する必要があります。<br>
| |
| − | * '''1つの''Map''を受け入れるコンストラクター''' <source lang="java">public PlayerData(Map data) {</source>
| |
| − | * '''1つの''Map''を受け入れてクラスを返す、"deserialize" という名前のstaticメソッド''' <source lang="java">public static PlayerData deserialize(Map data) {</source>
| |
| − | * '''1つの''Map''を受け入れてクラスを返す、"valueOf" という名前のstaticメソッド''' <source lang="java">public static PlayerData valueOf(Map data) {</source>
| |
| − | | |
| − | シリアライズされたオブジェクトをデシリアライズするには、ConfigurationSerialization に登録されている必要があります。<br>
| |
| − | registerClass メソッドは、シリアル化されたクラスごとに1回ずつ実行してください。
| |
| − | | |
| − | このステートメントは、メインクラスの初期化ブロックに記述することができます。
| |
| − | | |
| − | <blockquote><source lang="java">
| |
| − | ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)
| |
| − | </source></blockquote>
| |
| − | | |
| | ==== エイリアス ==== | | ==== エイリアス ==== |
| − |
| |
| − | クラスがシリアル化されるとき、完全修飾名でマークされています。
| |
| − |
| |
| − | エイリアスをクラスに設定しておくと、完全修飾名の代わりにエイリアスでマークされます。<br>
| |
| − | ''SerializeAs''アノテーションを、ConfigurationSerializableを実装するクラスに指定します。
| |
| − | <source lang="java">@SerilizeAs(String)</source>
| |
| − |
| |
| − | エイリアスをクラス登録と共に行いたい場合は、登録時に引数に一緒に指定します。
| |
| − |
| |
| − | <blockquote><source lang="java">
| |
| − | ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)
| |
| − | </source></blockquote>
| |
| − |
| |
| − | -->
| |
| | | | |
| | == 利用例 == | | == 利用例 == |
| − |
| |
| − | 以下は、新しい Configuration API を使ってプラグインを実装した例です。<br>
| |
| − | プレイヤー参加時に config.yml から message を取得して MOTD としてメッセージを表示したり、
| |
| − | rulesコマンド実行時に config.yml から rules を取得して表示したりします。<br>
| |
| − | なるべく手短な例を示したので、最適な実装例になっていないことをご了承ください。
| |
| − |
| |
| − | <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() {
| |
| − | // もし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;
| |
| − | }
| |
| − | });
| |
| − | }
| |
| − | }
| |
| − | </source></blockquote>
| |
| − |
| |
| − | デフォルトのconfig.ymlの内容は、下記のとおりです。
| |
| − | <source lang="yaml">
| |
| − | # default config.yml
| |
| − | message: Hello World and Welcome! :)
| |
| − | rules:
| |
| − | - Play Nice
| |
| − | - Respect others
| |
| − | - Have Fun
| |
| − | additional:
| |
| − | Anna: Hi Anna!
| |
| − | Billy: Hey Billy!
| |
| − | </source>
| |