環境タイプごとの dfprop

環境タイプによってプロパティ切り替え

例えば、開発環境、結合テスト環境など、環境ごとにDBFluteプロパティの内容を変えて Generate や ReplaceSchema なりを実行したい場合に、環境変数でDBFluteの環境タイプ を指定することでDBFluteプロパティを切り替えることができます。

また、DBFluteの環境タイプは、同時に ReplaceSchema のデータ登録の切り替えでも利用されます。

環境タイプの設定(環境変数)

DBFluteタスク実行時に有効になるように、環境変数 DBFLUTE_ENVIRONMENT_TYPE を設定します。例えば、結合テスト環境であれば "it" など、開発プロジェクトにおいてわかりやすい任意の値を設定します。

環境変数
DBFLUTE_ENVIRONMENT_TYPE
e.g. DBFluteの環境タイプ(DBFluteEnvironmentType)を "it" に設定 @sh
export DBFLUTE_ENVIRONMENT_TYPE=it

環境タイプごとにプロパティを配置

指定された環境タイプ用のDBFluteプロパティは、dfprop ディレクトリ配下に DBFLUTE_ENVIRONMENT_TYPE に設定した値と同じ名前のディレクトリ(環境タイプごとのディレクトリ)を作成し、その配下に切り替えたいDBFluteプロパティだけを配置します。

e.g. DBFluteの環境タイプ(DBFluteEnvironmentType)を "it" に設定 @dfprop
dfprop
 |-it
 |  |-databaseInfoMap.dfprop            // 環境タイプ "it" のときに有効
 |  |-replaceSchemaDefinitionMap.dfprop // 環境タイプ "it" のときに有効
 |
 |-basicInfoMap.dfprop                  // 共通("it" 配下に同じファイルが存在しないため)
 |-commonColumnMap.dfprop               // 共通("it" 配下に同じファイルが存在しないため)
 |-databaseInfoMap.dfprop               // 環境タイプが何も設定されなかったときに有効
 |-replaceSchemaDefinitionMap.dfprop    // 環境タイプが何も設定されなかったときに有効
 |-...Map.dfprop

切り替えは、基本は ファイル単位での完全な上書き となります(同じ名前のファイルを配置した場合)。 設定次第でマージ(追加・上書き)も利用可能です。

環境タイプごとのディレクトリ配下に配置されていないDBFluteプロパティは、dfprop ディレクトリ直下のものが有効になります。

プロパティのマージ

ファイル単位での切り替えではなく、メインのDBFluteプロパティを継承し、 差分定義だけしておいて個々のプロパティ単位での追加・上書きをすることも可能です。(map型プロパティに限ります)

環境タイプのディレクトリ配下のDBFluteプロパティのファイル名を [name]+.dfprop とすると、完全切り替えではなく、"+" 側に存在するプロパティでメインに存在しないものは追加、存在するものは上書き、というようになります。

e.g. DBFluteプロパティの環境タイプによるマージ @dfprop
dfprop
 |-it
 |  |-databaseInfoMap+.dfprop            // "+" を付けてるのでマージ(追加・上書き)
 |  |-replaceSchemaDefinitionMap+.dfprop // "+" を付けてるのでマージ(追加・上書き)
 |  |-allClassCopyright.dfprop           // map型プロパティじゃないので "+" は利用不可
 |
 |-basicInfoMap.dfprop
 |-commonColumnMap.dfprop
 |-databaseInfoMap.dfprop               // it の時も基本プロパティとして評価される
 |-replaceSchemaDefinitionMap.dfprop    // it の時も基本プロパティとして評価される
 |-...Map.dfprop

マージの仕様

map型プロパティの中の 最初のレベルのプロパティ単位 でのマージとなります。 例えば、databaseInfoMap.dfprop で言うと、user や password、variousMap などの単位で判定されます。"+" 側で variousMap が指定されている場合は、variousMap の中身を丸ごと差し替えます。

e.g. DBFluteプロパティのマージの単位 @databaseInfoMap+.dfprop
map:{
    # schema = foo       # コメントアウト(定義なし)なのでメインのものが有効
    ; user = foo         # user は上書き
    ; password = foo     # password は上書き
    ; variousMap = map:{ # variousMap を丸ごと上書き
        ; objectTypeTargetList = list:{}
        ; tableExceptList = list:{} # このレベルでの細かい上書きはできない
    }
}

お隣の+dfprop

"+" のないものと付いてるものが、同じ階層のディレクトリに存在していてもマージ処理はされます。

e.g. 同じ階層のディレクトリのプロパティのマージ @dfprop
dfprop
 |-it
 |  |-databaseInfoMap.dfprop             // 基本となるプロパティ(マージされる側)
 |  |-databaseInfoMap+.dfprop            // 隣の dfprop をマージ(追加・上書き)
 |  |-outsideSqlDefinitionMap.dfprop     // it の時評価されるが特にマージされない
 |
 |-basicInfoMap.dfprop              // 常にマージされる側
 |-basicInfoMap+.dfprop             // 常にマージ(追加・上書き)する
 |-databaseInfoMap.dfprop           // it の時は評価されない
 |-outsideSqlDefinitionMap+.dfprop  // 生涯評価されない(同・上位レベルにプロパティがないので)

なので、厳密に言うと、環境タイプを利用しない場合の構成でもこのマージ機能は利用可能です。 その必要性はほぼありませんが、もし、プロパティをツールなどで自動生成するような仕組みを作った場合に、 DBFluteプロパティのジェネレーションギャップとして利用することはあるかもしれません。

また、環境タイプのディレクトリ配下の "+" のないdfpropでmapが空っぽのときは、完全な上書きになります(@since 1.0.4F)。 ただし、古いバージョンでは、空っぽだとファイルが存在しないのと同様に扱われます(@until 1.0.4D)

環境タイプの設定タイミング

DBFluteタスクの実行時にこの環境変数が有効になるように設定し、設定の仕方は任意でそのとき都合良いやり方で構いません。

環境ごとのコマンドファイル

例えば、"replace-schema-ut.bat|sh" と "replace-schema-it.bat|sh" というように 環境ごとにコマンドファイルを用意 して、それぞれのコマンドの中で環境変数を定義する。 宣言した環境変数が別のDBFluteタスク実行時に有効にならないように、 環境変数のスコープに注意して下さい(スコープを限定するコマンドを利用したり、タスク実行後に削除されるようにしたりなど)。

e.g. コマンドファイルに環境変数を定義 {type=it} @replace-schema-it.bat
...
setlocal
%~d0
cd %~p0
call _project.bat

set DBFLUTE_ENVIRONMENT_TYPE=it
...
e.g. コマンドファイルに環境変数を定義 {type=it} @replace-schema-it.sh
#!/bin/sh

cd `dirname $0`
. _project.sh

export DBFLUTE_ENVIRONMENT_TYPE=it
...
unset DBFLUTE_ENVIRONMENT_TYPE

システム(ユーザ)の環境変数

ナイトリーテストのサーバや結合テストのサーバなど、サーバの "システム(ユーザ)環境変数" として設定して、それらサーバでの実行時にだけDBFluteプロパティが切り替わるようにする。

相対パス含み環境タイプ

環境タイプに ../../foo というような相対パス含みの値を指定すると、環境タイプの dfprop の置き場を変更することができます。 ただし、repsEnvType に影響してしまうので、その場合は repsEnvType は明示的に設定しておいた方が良いでしょう(他にも影響があればつどつど明示的に設定していくと良いでしょう)。 また、環境タイプを明示的に指定するところでちょっと煩雑な指定になってはしまいます(checkEnvなど)

相対パス含みの必要性があるかというとめったにないと思われますが、"アプリごとのBehavior" で利用できます。

環境タイプのターゲット

ReplaceSchemaでのデータ登録

主には、ReplaceSchemaタスクの repsEnvType を切り替えるために利用することが多いでしょう。DBFLUTE_ENVIRONMENT_TYPE が指定されている場合は、repsEnvType のデフォルト値がその環境タイプの値になります。例えば、DBFLUTE_ENVIRONMENT_TYPE で test という値を設定すると、データ登録対象のディレクトリが ut ではなく test になります。(common は常に対象となります)

Generate系のタスクにおいて環境ごとにプロパティを切り替える必要性はあまり多くないと考えられますが、 ナイトリーサーバで自動生成処理を行うなど自動生成する環境ごとにDBの接続先が変わるような場合はこの環境タイプを利用すると良いでしょう。

アプリごとのBehaviorの利用

アプリごとのBehavior、ApplicationBehavior の自動生成の環境を作る際に、この切り替え機能を使うと便利です。ApplicationBehavior のExampleでは実際に利用しています。

また、この環境タイプを "相対パス含み で指定すると、特殊な環境タイプの名前になってはしまいますが環境タイプの dfprop の場所で変更することができます。アプリごとのBehaviorならぬ、アプリごとのdfpropにすることができます(単に置き場所がそれぞれのアプリに配置するというだけですが)。ただしその場合、repsEnvType に影響してしまうので repsEnvType は明示的に設定しておいた方が良いでしょう。