sql2Entityタスク
sql2Entityタスクとは？
外だしsQLの情報を元に、主に Entity などのsQL対応のクラスを自動生成するDBFluteタスクです。
sql2Entityタスクを利用することで、以下のような開発が可能になります。
- sQLファイルにsQLを実装する。
- sQL対応のEntity(その他必要なもの)を自動生成する。
- sQLを実行する。
外だしsQL の実行には、以下の３つの要素が必要ですが、sql2Entityでこれらを自動生成できます。
- 結果を受け取るクラス (CustomizeEntity, TypesafeCursor)
- 検索条件などの条件値を格納したクラス (ParameterBean)
- どのsQL(ファイル)を実行するのかの情報 (BehaviorQueryPath)
また、ストアドプロシージャに対応する ParameterBean (ProcedurePmb) も自動生成できます。
主な実行タイミング
- 外だしsQLの実装中 (ディベロッパー)
- DB変更の発生 (アーキテクト)
- DBFluteアップグレード直後 (アーキテクト)
実行コマンド
DBFluteクライアント配下の sql2entity.(bat|sh) をコマンドから実行します。
環境構築
DBFluteのセットアップが終わった時点から利用できます。 但し、外だしsQLの情報を Behaviorクラス に保持するため、実行前にGenerateタスクが必ず(一度は)実行されていることが前提です。
処理概要
sql2Entityタスクを実行すると処理が始まります。
- 1. 外だしsQLを参照
- 2. 外だしsQLを(2Way-sQLとして)実行
- 3. プロシージャのメタデータを取得 (オプション)
- 4. 古いクラスを削除
- 5. クラスを自動生成
- 6. BehaviorQueryPathをBehaviorに反映
- 7. Eclipseプロジェクトをリフレッシュ (オプション)
1. 外だしsQLを参照
読み込み対象のディレクトリ配下に存在する、拡張子が .sql のsQLを読み込みます。
読み込み対象のディレクトリ
ここで言うとディレクトリとは、ソースディレクトリ(Javaで言うclasspath対象のディレクトリ)を指します。 例えば、../src/main/java や ../src/main/resources のことです。 そのソースディレクトリ配下のサブディレクトリに関しては、パッケージという扱いとなります。
読み込み対象のディレクトリのルールは以下の通りです。
- A. outsidesqlDefinitionMap.dfprop の sqlDirectory
- このプロパティが設定されている場合は(デフォルトでは設定されていない)、指定されたディレクトリ配下のsQLを読み込みます。
- B. basicInfoMap.dfprop の generateOutputDirectory
- "A" が設定されていなければ、このプロパティで指定されたディレクトリ配下のsQLを読み込みます。 このプロパティはデフォルト値を持つので、必ずプロパティ値が存在します。
- C. "A" と "B" どちらにおいても resources を参照
- "A" と "B" どちらにおいても、パスの中に "src/main/java" という文字が含まれている場合は、その部分を "src/main/resources" に置換したパスのsQLも追加的に読み込みます。
- D. ApplicationOutsidesql で指定されたプロジェクトを参照
- "A", "B", "C" のルールに加えて、DBFluteプロパティで アプリごとの外だしsQL を指定している場合は、指定されたプロジェクトに "A", "B", "C" を適用させた場所のsQLを読み込みます。
セットアップデフォルトでは "B" と "C" が適用され、src/main/java と src/main/resources が読み込み対象となります。
読み込み対象のパッケージ
デフォルトでは、読み込み対象のディレクトリ配下の 全て のsQLが対象ですが、outsidesqlDefinitionMap.dfprop の sqlPackage を設定することで、とあるパッケージ配下のsQLのみを対象にすることができます。
主に、複数DB対応で、一つのプロジェクト上に複数DBFluteクライアントを配置する際に、別のDB用のsQLを読み込まないようにするために利用されます。 逆にそれ以外の場面での利用はあまり想定されていません。
sql2Entityマークの解析
この処理において、sql2Entityマーク が解析されます。
2. 外だしsQLを(2Way-sQLとして)実行
CustomizeEntityマーク (TypesafeCursorマークを含む)が指定されているsQL(select文)を そのまま実行 します。よって、実行されるsQLは 2Way-sQL 形式となっていなければなりません。sQLエラーはタスクが中断されます。また、全てトランザクション内の実行で必ずロールバックされます。
sQLに不具合がある場合は、タスクの実行ログで原因を確認して修正してから 再度実行して下さい。
sQLを実行することにより、sQLのselect句の構造(メタデータ)が判明します。具体的には Resultset.getMetaData() で取得できる ResultsetMetaData の情報を利用しています。
3. プロシージャのメタデータを取得 (オプション)
outsidesqlDefinitionMap.dfprop にて ProcedurePmb (プロシージャ対応のParameterBean)の自動生成が有効になっている場合は、プロシージャのメタデータを取得します。このメタデータを元に後に ProcedurePmb を自動生成します。
対象となるプロシージャは、デフォルトでは該当スキーマと Additionalschema に存在する全てのプロシージャですが、outsidesqlDefinitionMap.dfprop で細かく指定することができます。
4. 古いクラスを削除
どこの外だしsQLにも定義されていない既存の CustomizeEntity (TypesafeCursor含む)および ParameterBean (ProcedurePmb含む)は、(ファイルシステム上から)削除されます。
5. クラスを自動生成
取得したメタデータから CustomizeEntity (TypesafeCursor含む)および ParameterBean (ProcedurePmb含む)を自動生成します。
出力先およびパッケージ構造(の仕様)は Generateタスク と同じです。 ただ、DBFluteプロパティで アプリごとの外だしsQL を指定している場合は、それぞれ対応する外だしsQLの存在するプロジェクト配下を基点にクラスが出力されます。
- CustomizeEntity
- sQL対応のEntity (bsentity|exentity.customize)
- DBMeta
- EntityのDBMeta (bsentity.customize.dbmeta)
- TypesafeCursor
- カーソルクラス (bsbhv|exbhv.cursor)
- ParameterBean
- パラメータオブジェクト (bsbhv|exbhv.pmbean)
- ProcedurePmb
- プロシージャ対応のクラス (bsbhv|exbhv.pmbean)
6. BehaviorQueryPathをBehaviorに反映
BehaviorQueryPathをBehaviorに反映します。既にBehaviorクラスが存在することが前提です。
7. Eclipseプロジェクトをリフレッシュ (オプション)
Generateタスクと同じく、Eclipseプロジェクトをリフレッシュ(更新)します。
sql2Entityマーク
CustomizeEntityを生成するか否か、ParameterBeanを生成するか否かなどを示すsQL上のマークの総称を "sql2Entityマーク" と呼びます。全てのマークはsQLの行コメントとして記述されるため、2Way-sQLを保ったままそのsQLにsql2Entityの情報を付与することができます。
sql2Entityマークには主に以下のようなものがあります：
- CustomizeEntityマーク
- CustomizeEntityを生成するか否か・クラス名を表現
- TypesafeCursorマーク
- TypesafeCursorを生成するか否か・クラス名を表現
- ParameterBeanマーク
- ParameterBeanを生成するか否か・クラス名・プロパティ構造を表現
様々なオプション
DBFluteプロパティを利用することで、様々なオプションが利用可能です。
- sqlFileEncoding
- 外だしsQLのエンコーディング
- sqlDirectory
- 外だしsQLの配置ディレクトリ
- sqlPackage
- 外だしsQLの配置パッケージ
