設定ファイルの更新

更新を有効にする

ショートカットでは autoUpdate = true、ビルダーでは autoUpdateIfOutdated(true) を指定します。自動更新はオブジェクトの構築前に行われ、新しい必須項目をデフォルトのリソースから補えます。

両方のドキュメントのルートに version を含めてください。YAML は大文字・小文字を区別せず、JSON は正確に version を探します。バージョンがない場合、組み込み戦略は比較用に 1.0.0 を使います。

バージョンはドット区切りの整数として比較します。足りない桁は 0、整数でない要素も 0 として扱います。完全な SemVer のプレリリース比較ではないため、1.2.0 のような数値だけのバージョンを使ってください。

マージの動作

現在のファイルが次の場合:

version: "1.0.0"
server:
  port: 9000
custom: true

同梱のデフォルト設定を次のように更新します。

version: "1.1.0"
server:
  port: 8080
  host: localhost

更新後は次のようになります。

version: "1.1.0"
server:
  port: 9000
  host: localhost
custom: true

マッピングは再帰的にマージし、ユーザーの既存値と追加キーを残します。リストや単一の値は要素単位でマージせず、ユーザーの値を保持します。置き換えるのはルートのバージョンだけで、ネストした version は通常のユーザー値です。マージ時のキー比較は、YAML のルートバージョン処理を除き、大文字・小文字を区別します。

YAML の戦略はコメントを扱うパースと出力を使用します。更新により書式が変わることがあり、元のテキストと完全に同じ形式は保証しません。出力は対象ファイルと同じディレクトリの一時ファイルに書き、対応環境ではアトミックに置換し、未対応の場合は通常の置換を使います。

手動更新

if (loader.updateConfig()) {
    loader.reload()
}

手動更新もバージョンを比較します。現在のバージョンが同じか新しい場合はマージしません。リソースに項目を追加しても、バージョンを上げなければ既存ファイルは更新されません。

更新戦略の選択

各パーサーがデフォルトの戦略を提供します。ビルダーの updateStrategy(...) は共通設定とパーサーのデフォルトより優先します。

設定	効果
autoUpdateIfOutdated(false)	初回の自動チェックを無効にする。手動更新は可能
ビルダーの updateStrategy(null)	そのローダーの自動・手動更新を無効にする
共通設定の LoaderSettings(updateStrategy = null, ...)	選択したパーサーのデフォルト戦略を使う

組み込みパーサーは要求ごとに新しい戦略を提供し、ローダーは選んだ戦略を手動更新にも使用します。グローバルな戦略レジストリーはありません。