The Seasar Project

目次

• 概要
• 問い合わせ条件
• 複数件検索
• 1件検索
• イテレーションによる検索
• 検索オプションを利用した検索
  • ページング
  • 悲観的排他制御
  • 集計
• 検索結果の保証
• 検索結果のマッピングの保証
• クエリタイムアウト
• フェッチサイズ
• 最大行数
• マップのキーのネーミング規約

概要

検索を行うには、 @SelectをDaoのメソッドに注釈します。

@Config(config = AppConfig.class)
public interface EmployeeDao {
    @Select
    List<Employee> selectByDepartmentName(String departmentName);
    ...
}

検索では、SQLファイルが必須です。 検索系のSQLを自動生成する機能はありません。

検索結果を受ける型には、基本型、ドメインクラス、エンティティクラス、java.util.Map<String, Object>、また、それらを要素とするjava.util.Listを使用できますが、 エンティティクラスを利用する場合、エンティティクラスは検索結果に応じて作成する必要があります。

たとえば、EMPLOYEEテーブルに対応するEmployeeエンティティクラスが定義されている場合、 EMPLOYEEテーブルのカラムを含む結果セットはEmployeeエンティティクラスで受けられますが、 EMPLOYEEテーブルとDEPARTMENTテーブルを結合して得られる結果セットに対しては、Employeeエンティティクラスとは別のクラス（たとえばEmployeeDepartmentクラス）が必要です。 通常は、テーブルごとにエンティティクラスを作成し、結合して得られる結果セットに対しては、テーブルに対応するエンティティクラスを継承したクラスを作成するのがよいでしょう。 もちろん、継承せずに作成することも可能です。

問い合わせ条件

問い合わせ条件にはメソッドのパラメータを使用します。 パラメータの型には、基本型、ドメインクラス、任意の型、 および基本型やドメインクラスを要素とするjava.lang.Iterableのサブタイプが使用できます。 パラメータの数に制限はありません。 パラメータの型が基本型もしくはドメインクラスの場合、引数をnullにできます。 それ以外の型の場合、引数はnullであってはいけません。

@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.getSalary() */100

任意の型であっても複数のパラメータを指定できます。

@Select
List<Employee> selectByEmployeeAndDepartment(Employee employee, Department department);

基本型やドメインクラスを要素とするjava.lang.Iterableのサブタイプは、 IN句を利用した検索を行う場合に使用します。java.lang.Iterableのサブタイプは、通常java.util.Listが適切でしょう。

@Select
List<Employee> selectByNames(List<String> names);

select * from employee where employee_name in /* names */('aaa','bbb','ccc')

複数件検索

複数件を検索するには、メソッドの戻り値の型をjava.util.Listにします。 Listの要素の型には、基本型、ドメインクラス、エンティティクラス、java.util.Map<String, Object>が使用できます。

@Select
List<Employee> selectByNameAndSalary(String name, BigDecimal salary);

結果が0件のときは、空のListが返されます。nullは返されません。 ただし、@SelectのensureResult要素にtrueを指定した場合、 結果が0件ならばorg.seasar.doma.jdbc.NoResultExceptionがスローされます。

1件検索

1件を検索するには、メソッドの戻り値の型を基本型、ドメインクラス、エンティティクラス、java.util.Map<String, Object>のいずれかにします。

@Select
Employee selectByNameAndSalary(String name, BigDecimal salary);

結果が0件のときは、nullが返されます。 ただし、@SelectのensureResult要素にtrueを指定した場合、 結果が0件ならばorg.seasar.doma.jdbc.NoResultExceptionがスローされます。

結果が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.selectByNameAndSalary(name, salary, new IterationCallback<Void, Employee>() {
        @Override
        public Void iterate(Employee target, IterationContext context) {
            ...
            return null;
        }
    });

org.seasar.doma.IterationCallback<R, T>の最初の型パラメータは、 Daoのメソッドの戻り値にあわせなければいけません。2番目の型パラメータは、基本型、ドメインクラス、 エンティティクラス、java.util.Map<String, Object>のいずれかでなければいけません。

@SelectのensureResult要素にtrueを指定した場合、 結果が0件ならばorg.seasar.doma.jdbc.NoResultExceptionがスローされます。

イテレーションが完了した後に任意の処理を行うには、org.seasar.doma.IterationCallback<R, T>の代わりに org.seasar.doma.PostIterationCallback<R, T>のサブタイプを定義します。 イテレーション完了後にpostIterateが呼び出されます。

EmployeeDao dao = new EmployeeDao();
dao.selectByNameAndSalary(name, salary, new PostIterationCallback<Void, Employee>() {
        @Override
        public Void iterate(Employee target, IterationContext context) {
            ...
            return null;
        }

        @Override
        public Void postIterate(Void result, IterationContext context) {
            ...
            return null;
        }
    });

検索オプションを利用した検索

検索オプションのクラス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 options = SelectOptions.get().offset(5).limit(10);
EmployeeDao dao = new EmployeeDao();
List<Employee> list = dao.selectByDepartmentName("ACCOUNT", options);

SelectOptions options = SelectOptions.get().forUpdate();
EmployeeDao dao = new EmployeeDao();
List<Employee> list = dao.selectByDepartmentName("ACCOUNT", options);

SelectOptions options = SelectOptions.get().offset(5).limit(10).count();
EmployeeDao dao = new EmployeeDao();
List<Employee> list = dao.selectByDepartmentName("ACCOUNT", options);
long count = options.getCount();

検索結果の保証

検索結果が1件以上存在することを保証したい場合は、@SelectのensureResult要素にtrueを指定します。

@Select(ensureResult = true)
Employee selectById(Integer id);

検索結果が0件ならばorg.seasar.doma.jdbc.NoResultExceptionがスローされます。

検索結果のマッピングの保証

検索結果を受ける型がエンティティクラスやエンティティクラスを要素とするjava.util.Listの場合において、エンティティのプロパティすべてに対して漏れなく結果セットのカラムをマッピングすることを保証したい場合は、@SelectのensureResultMapping要素にtrueを指定します。

@Select(ensureResultMapping = true)
Employee selectById(Integer id);

結果セットのカラムにマッピングされないプロパティが存在する場合org.seasar.doma.jdbc.ResultMappingExceptionがスローされます。

クエリタイムアウト

@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要素に値を指定しない場合、 設定クラスに指定された最大行数が使用されます。

マップのキーのネーミング規約

検索結果をjava.util.Map<String, Object>にマッピングする場合、 @SelectのmapKeyNaming要素にマップのキーのネーミング規約を指定できます。

@Select(mapKeyNaming = MapKeyNamingType.CAMEL_CASE)
List<Map<String, Object>> selectAll();

MapKeyNamingType.CAMEL_CASEは、カラム名をキャメルケースに変換することを示します。 そのほかに、カラム名を大文字や小文字に変換する規約があります。 指定しない場合、変換は行われません。