Merge remote-tracking branch 'upstream/master'

Author: pinzolo

docs/sources/index.rst

@@ -52,6 +52,7 @@ User Documentation
    transaction
    annotation-processing
    build
+   lombok-support
    kotlin-support
 
 Developer Documentation

docs/sources/lombok-support.rst

@@ -0,0 +1,145 @@
+==================
+Lombok サポート
+==================
+
+.. contents:: 目次
+   :depth: 3
+
+Doma は `Lombok <https://projectlombok.org/>`_ のバージョン 1.16.12 以上をサポートしています。
+
+.. note::
+
+  IDE として Eclipse を利用する場合はバージョン 4.5 以上を使ってください。
+  4.5 未満ではアノテーションプロッサで取得されるクラスに定義されたフィールドなどの並びがソースコードに記載されている順序と異なり、
+  正しく動作しないためです。
+
+Lombok サポートの概要
+================================
+
+Lombok と Doma は共に JSR 269 で規定されたアノテーションプロセッサを提供していますが、
+Lombok と Doma を同時に利用する場合はアノテーションプロセッサの処理順序が問題になることがあります。
+例えば、 Lombok のアノテーションプロセッサがコンストラクタを生成し、
+Doma のアノテーションプロセッサがそのコンストラクタを読み取る場合などです。
+仮に、Doma のアノテーションプロセッサが先に実行されると単にコンストラクタが定義されていないものとして動作し、
+コンパイルに失敗します。
+
+アノテーションプロセッサの処理順序を指定できればこの問題は解決するのですが、
+残念ながら処理順序が保証されないことが仕様に記載されており、実際に問題解決の仕組みは提供されていません。
+
+Doma では、この問題に対応するために、Lombok のアノテーションの有無を認識して処理順序に依存にしない振る舞いをするようにしています。
+先ほどの例で言えば、 ``@lombok.Value`` などコンストラクタを生成するLombokのアノテーションが存在する場合は
+実際にはコンストラクタを読み取らなくてもコンストラクタが存在するものとして動作するということです。
+
+Lombok 利用のベストプラクティス
+================================
+
+Lombok のアノテーションを用いたクラスの定義について推奨する方法を記載します。
+
+エンティティクラス
+-------------------
+
+immutable（イミュータブル）
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+イミュータブルなエンティティクラスを定義する場合は下記の点に注意します。
+
+* ``@Entity`` の ``immutable`` 要素に ``true`` を設定する
+* ``@lombok.Value`` もしくは ``@lombok.AllArgsConstructor`` を注釈する
+* ``@lombok.AllArgsConstructor`` を選んだ場合、getterを生成するためには ``@lombok.Getter`` を注釈する
+
+.. code-block:: java
+
+  @Entity(immutable = true)
+  @Value
+  public class Employee {
+    @Id
+    Integer id;
+    String name;
+    Age age;
+  }
+
+.. code-block:: java
+
+  @Entity(immutable = true)
+  @AllArgsConstructor
+  @Getter
+  public class Worker {
+    @Id
+    private final Integer id;
+    private final String name;
+    private final Age age;
+  }
+
+mutable（ミュータブル）
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ミュータブルなエンティティクラスを定義する場合は下記の点に注意します。
+
+* デフォルトコンストラクタを定義する（デフォルトコンストラクタの生成を抑制しない）
+* getter/setterを生成する場合は ``@lombok.Data`` もしくは ``@lombok.Getter`` / ``@lombok.Setter`` を注釈する
+
+.. code-block:: java
+
+  @Entity
+  @Data
+  public class Person {
+    @Id
+    private Integer id;
+    private String name;
+    private Age age;
+  }
+
+.. code-block:: java
+
+  @Entity
+  @Getter
+  @Setter
+  public class Businessman {
+    @Id
+    private Integer id;
+    private String name;
+    private Age age;
+  }
+
+ドメインクラス
+-------------------
+
+ドメインクラスを定義する場合は下記の点に注意します。
+
+* ``@lombok.Value`` を注釈する
+* インスタンスフィールドは1つだけ定義し名前は ``value`` にする
+
+.. code-block:: java
+
+  @Domain(valueType = Integer.class)
+  @Value
+  public class Age {
+    Integer value;
+  }
+
+エンベッダブルクラス
+----------------------
+
+エンベッダブルクラスを定義する場合は下記の点に注意します。
+
+* ``@lombok.Value`` もしくは ``@lombok.AllArgsConstructor`` を注釈する
+* ``@lombok.AllArgsConstructor`` を選んだ場合、getterを生成するためには ``@lombok.Getter`` を注釈する
+
+.. code-block:: java
+
+  @Embeddable
+  @Value
+  public class Address {
+    String street;
+    String city;
+  }
+
+.. code-block:: java
+
+  @Embeddable
+  @AllArgsConstructor
+  @Getter
+  public class Location {
+    private final String street;
+    private final String city;
+  }

docs/sources/query/index.rst

@@ -16,3 +16,4 @@
    procedure
    factory
    script
+   sql-processor

docs/sources/query/sql-processor.rst

@@ -0,0 +1,68 @@
+==================
+SQLプロセッサ
+==================
+
+.. contents:: 目次
+   :depth: 3
+
+SQLテンプレートで組み立てられたSQLをアプリケーションで扱うには、 ``@SqlProcessor`` をDaoのメソッドに注釈します。
+
+.. code-block:: java
+
+  @Config(config = AppConfig.class)
+  public interface EmployeeDao {
+      @SqlProcessor
+      <R> R process(Integer id, BiFunction<Config, PreparedSql, R> handler);
+      ...
+  }
+
+メソッドに対応する :doc:`../sql` が必須です。
+
+.. warning::
+
+  SQLプロセッサを使ってSQLを組み立て実行する場合、潜在的には常にSQLインジェクションのリスクがあります。
+  まずは、他のクエリもしくはクエリビルダを使う方法を検討してください。
+  また、SQLプロセッサでは信頼できない値をSQLの組み立てに使わないように注意してください。
+
+戻り値
+==================
+
+メソッドの戻り値は任意の型にできます。
+ただし、 ``BiFunction`` 型のパラメータの3番目の型パラメータと合わせる必要があります。
+
+なお、戻り値の型を ``void`` にする場合、 ``BiFunction`` 型のパラメータの3番目の型パラメータには ``Void`` を指定します。
+
+.. code-block:: java
+
+  @SqlProcessor
+  void process(Integer id, BiFunction<Config, PreparedSql, Void> handler);
+
+パラメータ
+==================
+
+ ``BiFunction`` 型のパラメータを1つのみ含める必要があります。
+ ``BiFunction`` 型のパラメータはSQLテンプレート処理後のSQLを処理するために使われます。
+
+その他のパラメータはSQLテンプレートで参照できます。
+基本的には、 :doc:`select` の問い合わせ条件に指定できるのと同じ型を使用できます。 
+
+利用例
+==================
+
+例えば、SQLテンプレートで処理したSQLをさらに変形し直接実行することができます。（この例では例外処理を省略しています。）
+
+.. code-block:: java
+
+  EmployeeDao dao = ...
+  dao.process(1, (config, preparedSql) -> {
+    String sql = preparedSql.getRawSql();
+    String anotherSql = createAnotherSql(sql);
+    DataSource dataSource = config.getDataSource()
+    Connection connection = dataSource.getConnection();
+    PreparedStatement statement = connection.prepareStatement(anotherSql);
+    return statement.execute();
+  });
+
+.. code-block:: sql
+
+  select * from employee where id = /*^ id */0

src/main/java/org/seasar/doma/SqlProcessor.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2004-2010 the Seasar Foundation and the Others.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+package org.seasar.doma;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * SQLテンプレートで組み立てられたSQLを扱うことを示します。
+ * <p>
+ * このアノテーションが注釈されるメソッドは、Daoインタフェースのメンバでなければいけません。
+ * 
+ * <h3>例:</h3>
+ * 
+ * <pre>
+ * &#064;Dao(config = AppConfig.class)
+ * public interface EmployeeDao {
+ *     &#64;SqlProcessor
+ *     &lt;R&gt; R process(Integer id, BiFunction&lt;Config, PreparedSql, R&gt; handler);
+ * }
+ * </pre>
+ * 
+ * @author nakamura
+ * @since 2.14.0
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@DaoMethod
+public @interface SqlProcessor {
+
+}