Sql2Entity

このような開発が可能になります。

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

CustomizeEntity

外だしSQLで利用する戻り値の型は、DomainEntityでなく、そのSQL独自の構造を持ったEntityであって欲しい場合が多々あります。 そのEntityを手動で作成すると、面倒なのはもとより、「プロパティ名とSQLで定義したカラム名が食い違うバグ」も発生します。 Sql2EntityはSQL文そのものから定義すべきプロパティ名を導出し自動生成し、そのような問題を解決します。 手動作成の面倒な点もなくなり、入力ミスなどによる名称定義の食い違いでのバグも一切なくなります。 Sql2Entityで作ったそのSQL独自の構造を持ったEntityのことを「CustomizeEntity」と呼びます。

ParameterBean

SQLへ渡す引数は実開発ではかなり多くなりがちです。引数につらつら並べるのは可読性がよくありません。 Sql2EntityはSQLへ渡す引数オブジェクトも自動生成します。 Sql2Entityで作ったSQLへ渡す引数オブジェクトのことを「ParameterBean」と呼びます。

BehaviorQueryPath

SQLファイルへのパスを解決は悩ましい問題です。作成したSQLのファイル名とプログラムで指定するファイル名が食い違って「そんなファイルありません」エラーになることがよくあります。 Sql2Entityはある規約に則ったSQLファイルに限ってそのSQLのパス定義をBehaviorクラスに自動生成します。これに関しては、外だしSQLの基本に解説がありますのでそちらご覧下さい。 Sql2Entityで作ったSQLのパス定義のことを「BehaviorQueryPath」と呼びます。

Sql2Entityの実行方法

Sql2Entityは、DBFluteのANTタスクの一つです。
DBFluteクライアントディレクトリのsql2entity.bat(.sh)を起動することで、Sql2Entityを実行できます。

実行されると、Sql2Entity対象のSQLファイルを探して処理をします。
SQLファイルの配置先などの仕様に関して詳しくはこちら

Eclipseをご利用の場合はSql2Entity実行後に必ず「プロジェクトの更新」を行って下さい。

CustomizeEntityの生成手順

  1. CustomizeEntityのクラス指定

    外だしSQLにて、生成したいCustomizeEntityのクラス名を「-- #クラス名#」という形式で指定します。

    
-- #SimpleMember#

select ... from ...

    「--#」というように空白なしでも動作しますが、DBによっては例外になってしまう場合があるのでご注意下さい(MySQL)。
    また、SQL文の後ろに宣言しないとDBによって例外になってしまうこともありますのでご注意下さい(DB2)。

    このとき、SQL文は必ず「2WAY-SQL(についてはこちら)」で実装する必要があります。
    Sql2EntityがそのSQLを実際にDBで実行することでメタ情報を取得するためです。

  2. CustomizeEntityのオプション指定 {必要であれば}

    PK指定
    必須指定ではありませんが、CustomizeEntityにPK情報(ユニークになるカラム)を指定することも可能です。 
    
-- #SimpleMember#
-- *MEMBER_ID*
    複数カラムでユニークになる場合は、「-- *MEMBER_ID, XXX_DATE*」というようにカンマ区切りで指定します。

    生成されるCustomizeEntityのequals()メソッドがユニークになるカラムだけで比較をするようになります。
    また、その他PK情報を利用したユーティリティメソッドにおいて、そのCustomizeEntityが利用可能になります。
    必須ではありませんが、そのSQLのユニーク性を明示しておくのは良いことです。

    カーソル指定
    カーソル検索を行う場合は、カーソルオプションを付けます。(カーソル検索に関して詳しくはこちら)
    「-- +オプション名+」という形式で指定します。 
    
-- #SimpleMember#
-- +cursor+

  3. Sql2Entityの実行

    これでSql2Entityを実行すれば、指定したクラス名のCustomizeEntityが「exentity.customize」パッケージ配下に生成されます。
    文法ミスなどでSQL文の実行自体が例外になってしまう場合は、SQL文を修正して再度実行します。
    実行ログがDBFluteクライアントディレクトリの「./log/dbflute.log」に出力されますので、例外発生時はそちらをご覧下さい。

ParameterBeanの生成手順

  1. ParameterBeanのクラス指定

    外だしSQLにて、生成したいParameterBeanのクラス名を「-- !クラス名!」という形式で指定します。

    
-- !SimpleMemberPmb!

select ... from ...

    「--」コメントの注意点ならびに「2Way-SQL」であることの注意点に関しては「CustomizeEntity」のときと同じです。

    ページング検索をしたい場合は、クラス指定のクラス名の後ろに「 extends SPB」を付与します。
    すると、ParameterBeanがSimplePagingBeanを継承した状態で生成されるようなります。 

    
-- !SimpleMemberPmb extends SPB!

    外だしSQLのページング検索に関して詳しくはこちら

  2. ParameterBeanのプロパティ指定

    外だしSQLにて、ParameterBeanに定義するプロパティの型と名前を「-- !!型 プロパティ名!!」という形式で指定します。
    型で自動解決されないものは明示的にパッケージ名も付与する必要があります。(例えばjava.util.Dateなど) 

    
-- !SimpleMemberPmb!
-- !!Integer memberId!!
-- !!String memberName!!

select ... from ...

    Likeオプション指定

    曖昧検索対象のプロパティに「Likeオプション」を指定することが可能です。 

    ex) 会員名称で「Likeオプション」を指定
-- !!String memberName:like!!
    ParameterBeanの該当プロパティにおいて、ConditionBeanで使っているLikeSearchOptionが利用可能になります。
    曖昧検索の一致の方向(前方、中間、後方)をアプリケーションにて動的に決定する場合や、エスケープ処理を入れる場合に有効です。
    外だしSQLの曖昧検索についてはこちら

    Likeオプションの利用可能バージョン

    • [Java-1.4]の場合 → 未実装です。今後も実装予定はありません
    • [Java-5.0 or Java6.0]の場合 → DBFlute-0.5.9より利用可能です。
    • [C#-2.0 or C-#3.0]の場合 → 未実装です。実装予定あり。

  3. Sql2Entityの実行

    これでSql2Entityを実行すれば、指定したクラス名のCustomizeEntityが「exdao.pmbean」パッケージ配下に生成されます。
    文法ミスなどでSQL文の実行自体が例外になってしまう場合は、SQL文を修正して再度実行します。
    実行ログがDBFluteクライアントディレクトリの「./log/dbflute.log」に出力されますので、例外発生時はそちらをご覧下さい。

ParameterBeanのSQL間での再利用

ParameterBeanは、1SQLに付き1つというわけではありません。明らかな共通ParameterのSQLがある場合は、あるSQLで生成したParameterBeanを別のSQLで利用しても全然構いません。ParameterBeanのクラス名も特に規約があるわけでないので、「SQL名 + Pmb」でなくて再利用に都合の良い名前をつけてもらって構いません(後ろのPmbという名前は習慣です)。

そこであまり凝りすぎるのも良くないので、通常は「1SQLに付き1ParameterBean」で、「明らかな共通ParameterのSQL」が複数存在したときに上記のように再利用すると良いでしょう。