Sql2Entityタスク

Sql2Entityタスクとは?

外だしSQLの情報を元に、主に Entity などのSQL対応のクラスを自動生成するDBFluteタスクです。

Sql2Entityタスクを利用することで、以下のような開発が可能になります。

  1. SQLファイルにSQLを実装する。
  2. SQL対応のEntity(その他必要なもの)を自動生成する。
  3. SQLを実行する。

外だしSQL の実行には、以下の3つの要素が必要ですが、Sql2Entityでこれらを自動生成できます。

また、ストアドプロシージャに対応する ParameterBean (ProcedurePmb) も自動生成できます。

主な実行タイミング

  • 外だしSQLの実装中 (ディベロッパー)
  • DB変更の発生 (アーキテクト)
  • DBFluteアップグレード直後 (アーキテクト)

実行コマンド

DBFluteクライアント配下の sql2entity.(bat|sh) をコマンドから実行します。

環境構築

DBFluteのセットアップが終わった時点から利用できます。 但し、外だしSQLの情報を Behaviorクラス に保持するため、実行前にGenerateタスクが必ず(一度は)実行されていることが前提です。

処理概要

Sql2Entityタスクを実行すると処理が始まります。

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