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の配置パッケージ
