About

ドキュメント

プロジェクト文書

Built by Maven

概要

SQLファイルは、SQL文を格納したテキストファイルで、Data Access Object のメソッドにマッピングされます。 SQLのブロックコメント(/* */)や行コメント(--)を使用することで、バインド変数や動的なSQLのための条件分岐を表現できます。 SQLのツールですぐにそのSQLを実行できるように、バインド変数にはテスト用のデータを指定できます。テスト用のデータは、実行時には使用されません。 たとえば、SQLファイルには次のようなSQL文が格納されます。

select * from employee where employee_id = /*employeeId*/99

ここでは、ブロックコメントで囲まれた employeeIdData 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 ディレクトリ以下に配置しなければいけません。

ファイル名の形式

ファイル名は、次の形式でなければいけません。

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.DialectgetName メソッドの値が使用されます。

エンコーディング

SQLファイルのエンコーディングは UTF-8 でなければいけません。

SQLコメント

バインド変数コメント

1つのバインド変数

バインド変数はブロックコメントで囲んで示します。バインド変数はメソッドのパラメータ名になります。/* の後ろや */ の直前に空白を入れてはいけません。 ブロックコメント直後のテスト用データは必須です。テスト用データは、実行時には使用されません。 Data Access Object のメソッドと、対応するSQLの例は次のとおりです。

List<Employee> selectById(IntegerDomain employeeId);
select * from employee where employee_id = /*employeeId*/99

リストのバインド変数(IN句にバインドする場合)

IN句にバインドする場合は、INの直後にブロックコメントをおき、ブロックコメントの直後には括弧つきでテスト用データを指定します。テスト用データは、実行時には使用されません。 Data Access Object のメソッドと、対応するSQLの例は次のとおりです。

List<Employee> selectByIdList(List<IntegerDomain> 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

条件コメント

ifend

条件によってSQLを組み立てる場合は、/*%if 条件*/ ~ /*%end*/ という構文を使用できます。

select * from employee where /*%if employeeId != null*/employee_id = /*employeeId*/99/*%end*/

このSQL文は、 employeeIdnull でない場合 次のような準備された文に変換されます。

select * from employee where employee_id = ?

このSQL文は、 employeeIdnull の場合に次のような準備された文に変換されます。

select * from employee

ANDの自動除去

条件コメントを使用した場合、条件の後ろにつづく AND や OR について、自動で出力の要/不要を判定します。 たとえば、次のようなSQLでemployeeIdnull の場合、

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%'

elseifelse

/*%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*/

通常のコメント

/* の直後に、Javaの変数で使用できない値が続く場合、それは通常のSQLコメントだとみなされます。 ただし、条件コメントである %if%end がつづく場合は例外です。

select * from employee /* 通常のコメント */

式言語

条件コメントの /*%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

比較演算子

==!= 以外の比較演算子は、 被演算子が java.lang.Comparable を実装している必要があります。

比較演算子
==
!=
<
<=
>
>=

メソッド呼び出し

ドット(.)で区切ってメソッドを指定することでメソッドを実行可能です。

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*/