概要
SQLファイルは、SQL文を格納したテキストファイルで、Data Access Object
のメソッドにマッピングされます。
SQLのブロックコメント(/* */)や行コメント(--)を使用することで、バインド変数や動的なSQLのための条件分岐を表現できます。
SQLのツールですぐにそのSQLを実行できるように、バインド変数にはテスト用のデータを指定できます。テスト用のデータは、実行時には使用されません。
たとえば、SQLファイルには次のようなSQL文が格納されます。
select * from employee where employee_id = /*employeeId*/99
ここでは、ブロックコメントで囲まれた employeeId
が Data Access Object
のメソッドのパラメータに対応します。
直後の 99
はテスト用の条件になります。
SQLファイルにマッピングするためのアノテーション
SQLファイルとマッピングするには、Data Access Object
のメソッドに次のアノテーションを注釈しなければいけません。
@Select
が注釈されたメソッド@Insert(sqlFile = true)
が注釈されたメソッド@Update(sqlFile = true)
が注釈されたメソッド@Delete(sqlFile = true)
が注釈されたメソッド@BatchInsert(sqlFile = true)
が注釈されたメソッド@BatchUpdate(sqlFile = true)
が注釈されたメソッド@BatchDelete(sqlFile = true)
が注釈されたメソッド
SQLファイル
ファイル名の形式
ファイル名は、次の形式でなければいけません。
META-INF/Data Access Objectのクラスの完全修飾名をディレクトリに変換したもの/Data Access Objectのメソッド名.sql
例えば、 Data Access Object
のクラスが aaa.bbb.EmployeeDao
で
マッピングしたいメソッドが selectById
の場合、パス名は次のようになります。
META-INF/aaa/bbb/EmployeeDao/selectById.sql
複数のRDBMSに対応する必要があり特定のRDBMSでは別のSQLファイルを使いたい場合、
.sql
の前にRDBMS名を入れることで、優先的に使用するファイルを指示できます。
たとえば、PostgreSQL専用のSQLファイルは次の名前にします。
META-INF/aaa/bbb/EmployeeDao/selectById_postgres.sql
この場合、PostgreSQLを使用している場合に限り、META-INF/aaa/bbb/EmployeeDao/selectById.sql
よりも
META-INF/aaa/bbb/EmployeeDao/selectById_postgres.sql
が優先的に使用されます。
RDBMS名は、 org.seasar.doma.jdbc.dialect.Dialect
の getName
メソッドの値が使用されます。
SQLコメント
バインド変数コメント
1つのバインド変数
バインド変数はブロックコメントで囲んで示します。バインド変数はメソッドのパラメータ名になります。/* の後ろや */ の直前に空白を入れてはいけません。
ブロックコメント直後のテスト用データは必須です。テスト用データは、実行時には使用されません。
Data Access Object
のメソッドと、対応するSQLの例は次のとおりです。
List<Employee> selectById(Identity employeeId);
select * from employee where employee_id = /*employeeId*/99
リストのバインド変数(IN句にバインドする場合)
IN句にバインドする場合は、INの直後にブロックコメントをおき、ブロックコメントの直後には括弧つきでテスト用データを指定します。テスト用データは、実行時には使用されません。
Data Access Object
のメソッドと、対応するSQLの例は次のとおりです。
List<Employee> selectByIdList(List<Identity> employeeIdList);
select * from employee where employee_id in /*employeeIdList*/(1,2,3)
エンティティ型パラメータをバインド変数に利用する場合
メソッドでエンティティを渡す場合、バインド変数コメント内でドット(.)を使用することでエンティティのプロパティにアクセスできます。
Data Access Object
のメソッドと、対応するSQLの例は次のとおりです。
List<Employee> selectById(Employee employee);
select * from employee where employee_id = /*employee.employeeId*/99
条件コメント
if
と end
条件によってSQLを組み立てる場合は、/*%if 条件*/ ~ /*%end*/
という構文を使用できます。
select * from employee where /*%if employeeId != null*/employee_id = /*employeeId*/99/*%end*/
このSQL文は、 employeeId
が null
でない場合 次のような準備された文に変換されます。
select * from employee where employee_id = ?
このSQL文は、 employeeId
が null
の場合に次のような準備された文に変換されます。
select * from employee
ANDの自動除去
条件コメントを使用した場合、条件の後ろにつづく AND や OR について、自動で出力の要/不要を判定します。
たとえば、次のようなSQLでemployeeId
が null
の場合、
select * from employee where /*%if employeeId != null*/employee_id = /*employeeId*/99/*%end*/ and employeeName like 's%'
/*%end*/
の後ろの and
は自動で除去されます。
select * from employee where employeeName like 's%'
elseif
と else
/*%if 条件*/
と /*%end*/
の間では、
行コメントを使用した --elseif 条件--
や --else
という構文も使用できます。
select * from employee where /*%if employeeId != null*/ employee_id = /*employeeId*/99 --elseif employeeId == 999-- department_id is null --else employee_id is null /*%end*/
式言語
条件コメントの /*%if 条件*/
や、 --elseif 条件--
の条件部には、式を記述できます。
定数
次の定数が用意されています。
定数 | 型 |
null |
void |
true |
boolean |
false |
boolean |
10 |
int |
10L |
long |
0.123F |
float |
0.123D |
doubl |
0.123B |
java.math.BigDecimal |
'a' |
char |
"a" |
String |
メソッド呼び出し
ドット(.)で区切ってメソッドを指定することでメソッドを実行可能です。
select * from employee where /*%if employeeName.startsWith("s") */ employee_name = /*employeeName*/'smith'/*%end*/
引数がない場合は、メソッド名の後ろの()を省略してもかまいません。
select * from employee where /*%if employeeName.length > 10 */ employee_name = /*employeeName*/'smith'/*%end*/