概要
検索を行うには、 @Select
をDaoのメソッドに注釈します。
@Config(config = AppConfig.class) public interface EmployeeDao { @Select List<Employee> selectByDepartmentName(String departmentName); ... }
検索では、SQLファイルが必須です。 検索系のSQLを自動生成する機能はありません。
問い合わせ条件
問い合わせ条件にはメソッドのパラメータを使用します。
パラメータの型には、基本型、ドメインクラス、エンティティティクラス
および基本型やドメインクラスを要素とするjava.util.List
が使用できます。
パラメータの数に制限はありません。
@Select List<Employee> selectByNameAndSalary(String name, BigDecimal salary);
SQLファイルではSQLコメントを使いメソッドのパラメータをSQLにマッピングさせます。 SQLコメントではメソッドのパラメータ名を参照します。
select * from employee where employee_name = /* name */'hoge' and salary > /* salary */100
メソッドのパラメータに基本型ではなくエンティティクラスを使用する場合は、ドット(.)でエンティティのプロパティにアクセスしSQLにマッピングさせます。
@Select List<Employee> selectByExample(Employee employee);
select * from employee where employee_name = /* employee.name */'hoge' and salary > /* employee.salary */100
基本型やドメインクラスを要素とするjava.util.List
は、
IN句を利用した検索を行う場合に使用します。
@Select List<Employee> selectByNames(List<String> names);
select * from employee where employee_name in /* names */('aaa','bbb','ccc')
複数件検索
複数件を検索するには、メソッドの戻り値の型をjava.util.List
にします。
List
の要素の型には、基本型、ドメインクラス、エンティティティクラスが使用できます。
@Select List<Employee> selectByNameAndSalary(String name, BigDecimal salary);
結果が0件のときは、空のList
が返されます。null
は返されません。
1件検索
複数件を検索するには、メソッドの戻り値の型を基本型、ドメインクラス、エンティティティクラスのいずれかにします。
@Select Employee selectByNameAndSalary(String name, BigDecimal salary);
結果が0件のときは、null
が返されます。
結果が2件以上存在するときは、org.seasar.doma.jdbc.NonUniqueResultException
がスローされます。
イテレーションによる検索
全件を一度にList
で受け取るのではなく1件ずつ処理を行いたい場合は、
イテレーションによる検索ができます。
イテレーションによる検索を行うには、@Select
のiterate
要素をtrue
に設定し、
メソッドのパラメータにorg.seasar.doma.IterationCallback<R, T>
もしくは、
org.seasar.doma.IterationCallback<R, T>
のサブタイプを定義します。
@Select(iterate = true) Void selectByNameAndSalary(String name, BigDecimal salary, IterationCallback<Void, Employee> callback);
IterationCallback
のiterate
メソッドに検索対象がインスタンス化され1件ずつ渡されます。
EmployeeDao dao = new EmployeeDao(); dao.selectAll(new IterationCallback<Void, Employee>() { @Override public Void iterate(Employee target, IterationContext context) { ... return null; } });
org.seasar.doma.IterationCallback<R, T>
の最初の型パラメータは、
Daoのメソッドの戻り値にあわせなければいけません。2番目の型パラメータは、基本型、ドメインクラス、
エンティティティクラスのいずれかでなければいけません。
検索オプションを利用した検索
検索オプションのクラスSelectOptions
を使用することで、SELECT文が記述されたSQLファイルをベースにし、
ページング処理や悲観的排他制御用のSQLを自動で生成できます。
SelectOptions
は、複数件検索、
1件検索、イテレーションによる検索と組み合わせて使用します。
SelectOptions
は、Daoのメソッドのパラメータとして定義します。
@Config(config = AppConfig.class) public interface EmployeeDao { @Select List<Employee> selectByDepartmentName(String departmentName, SelectOptions options); ... }
SelectOptions
は、SelectOptions
のstaticなget
メソッドにより取得できます。
SelectOptions options = SelectOptions.get();
ページング
SelectOptions
のoffset
メソッドで開始位置、limit
メソッドで取得件数を指定し、
SelectOptions
のインスタンスをDaoのメソッドに渡します。
SelectOptions options = SelectOptions.get().offset(5).limit(10); EmployeeDao dao = new EmployeeDao(); List<Employee> list = dao.selectByDepartmentName("ACCOUNT", options);
ページングの制約
ページングは、ファイルに記述されているオリジナルのSQLを書き換え実行することで実現されています。 オリジナルのSQLは次の条件を満たしていなければいけません。
- SELECT文である
- 最上位のレベルでUNION、EXCEPT、INTERSECT等の集合演算を行っていない(サブクエリで利用している場合は可)
- ページング処理を含んでいない
さらに、データベースの方言によっては特定の条件を満たしていなければいけません。
方言クラス | 条件 |
---|---|
org.seasar.doma.jdbc.dialect.Db2Dialect |
offsetを指定する場合、ORDER BY句を持ちORDER BY句で指定するカラムすべてをSELECT句に含んでいる。 |
org.seasar.doma.jdbc.dialect.Mssql2008Dialect |
offsetを指定する場合、ORDER BY句を持ちORDER BY句で指定するカラムすべてをSELECT句に含んでいる。 |
org.seasar.doma.jdbc.dialect.StandardDialect |
ORDER BY句を持ちORDER BY句で指定するカラムすべてをSELECT句に含んでいる。 |
悲観的排他制御
SelectOptions
のforUpdate
メソッドで悲観的排他制御を行うことを指示し、
SelectOptions
のインスタンスをDaoのメソッドに渡します。
SelectOptions options = SelectOptions.get().forUpdate(); EmployeeDao dao = new EmployeeDao(); List<Employee> list = dao.selectByDepartmentName("ACCOUNT", options);
SelectOptions
には、ロック対象のテーブルやカラムのエイリアスを指定できるforUpdate
メソッドや、
ロックの取得を待機しないforUpdateNowait
など、名前が「forUpdate」で始まる悲観的排他制御用のメソッドが用意されています。
詳しくはJavadocコメントを参照ください。
悲観的排他制御の制約
悲観的排他制御は、ファイルに記述されているオリジナルのSQLを書き換え実行することで実現されています。 オリジナルのSQLは次の条件を満たしていなければいけません。
- SELECT文である
- 最上位のレベルでUNION、EXCEPT、INTERSECT等の集合演算を行っていない(サブクエリで利用している場合は可)
- 悲観的排他制御の処理を含んでいない
データベースの方言によっては、悲観的排他制御用のメソッドのすべてもしくは一部が使用できません。
方言クラス | 説明 |
---|---|
org.seasar.doma.jdbc.dialect.Db2Dialect |
forUpdate() を使用できる。 |
org.seasar.doma.jdbc.dialect.H2Dialect |
forUpdate() を使用できる。 |
org.seasar.doma.jdbc.dialect.HsqldbDialect |
forUpdate() を使用できる。 |
org.seasar.doma.jdbc.dialect.Mssql2008Dialect |
forUpdate() とforUpdateNoWait() を使用できる。ただし、オリジナルのSQLのFROM句は1つのテーブルだけから成らねばならない。 |
org.seasar.doma.jdbc.dialect.MysqlDialect |
forUpdate() を使用できる。 |
org.seasar.doma.jdbc.dialect.OracleDialect |
forUpdate() 、forUpdate(String... aliases) 、forUpdateNowait() 、forUpdateNowait(String... aliases) 、 forUpdateWait(int waitSeconds) 、forUpdateWait(int waitSeconds, String... aliases) を使用できる。 |
org.seasar.doma.jdbc.dialect.PostgresDialect |
forUpdate() とforUpdate(String... aliases) を使用できる。 |
org.seasar.doma.jdbc.dialect.StandardDialect |
悲観的排他制御用のメソッドすべてを使用できない。 |
集計
SelectOptions
のcount
メソッドを呼び出すことで、集計件数を取得できるようになります。
通常、ページングのオプションと組み合わせて使用し、ページングで絞り込まない場合の全件数を取得する場合に使います。
SelectOptions options = SelectOptions.get().offset(5).limit(10).count(); EmployeeDao dao = new EmployeeDao(); List<Employee> list = dao.selectByDepartmentName("ACCOUNT", options); long count = options.getCount();
集計件数は、Daoのメソッド呼出し後に、SelectOptions
のgetCount
メソッドを使って取得します。
メソッド呼び出しの前にcount
メソッドを実行していない場合、getCount
メソッドは-1
を返します。
クエリタイムアウト
@Select
のqueryTimeout
要素にクエリタイムアウトの秒数を指定できます。
@Select(queryTimeout = 10) List<Employee> selectAll();
queryTimeout
要素に値を指定しない場合、
設定クラスに指定されたクエリタイムアウトが使用されます。
フェッチサイズ
@Select
のfetchSize
要素にフェッチサイズを指定できます。
@Select(fetchSize = 20) List<Employee> selectAll();
fetchSize
要素に値を指定しない場合、
設定クラスに指定されたフェッチサイズが使用されます。
最大行数
@Select
のmaxRows
要素に最大行数を指定できます。
@Select(maxRows = 100) List<Employee> selectAll();
maxRows
要素に値を指定しない場合、
設定クラスに指定された最大行数が使用されます。