/*%populate*/ についてのドキュメントを追記

Author: nakamura-to

docs/sources/query/batch-update.rst

@@ -34,6 +34,8 @@
 
 上記の条件を満たさないない場合、戻り値は各更新処理の更新件数を表す ``int[]`` でなければいけません。
 
+.. _auto-batch-update:
+
 SQLの自動生成によるバッチ更新
 =============================
 
@@ -127,6 +129,40 @@ SQLファイルによるバッチ更新を行うには、
 ``@BatchUpdate`` の ``sqlFile`` 要素に ``true`` を設定し、
 メソッドに対応するSQLファイルを用意します。
 
+.. note::
+
+  SQLファイルによるバッチ更新は、 :ref:`populate` の利用有無によりルールが異なります。
+
+更新カラムリスト生成コメントを使用する場合
+-------------------------------------------------
+
+.. code-block:: java
+
+  @BatchUpdate(sqlFile = true)
+  int[] update(List<Employee> employees);
+
+  @BatchUpdate
+  BatchResult<ImmutableEmployee> update(List<ImmutableEmployee> employees);
+
+パラメータの型は :doc:`../entity` を要素とする ``java.lang.Iterable`` のサブタイプでなければいけません。
+指定できるパラメータの数は1つです。
+引数は ``null`` であってはいけません。
+戻り値の配列の要素の数はパラメータの ``Iterable`` の要素の数と等しくなります。
+配列のそれぞれの要素が更新された件数を返します。
+
+たとえば、上記のメソッドに対応するSQLは次のように記述します。
+
+.. code-block:: sql
+
+  update employee set /*%populate*/ id = id where name = /* employees.name */'hoge'
+
+SQLファイル上では、パラメータの名前は ``Iterable`` のサブタイプの要素を指します。
+
+更新対象プロパティの制御に関するルールは、 :ref:`auto-batch-update` と同じです。
+
+更新カラムリスト生成コメントを使用しない場合
+-------------------------------------------------
+
 .. code-block:: java
 
   @BatchUpdate(sqlFile = true)
@@ -154,7 +190,7 @@ SQLファイルによるバッチ更新では、バージョン番号の自動
 また、 ``@BatchUpdate`` の ``exclude`` 要素、 ``include`` 要素は参照されません。
 
 SQLファイルにおけるバージョン番号と楽観的排他制御
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 次の条件を満たす場合に、楽観的排他制御が行われます。
 
@@ -184,7 +220,7 @@ WHERE句でバージョンを番号を指定しSET句でバージョン番号を
 はスローされず、エンティティのバージョンプロパティの値が1増分されます。
 
 ignoreVersion
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 ``@BatchUpdate`` の ``ignoreVersion`` 要素が ``true`` の場合、
 更新件数が0件または複数件であっても、 ``BatchOptimisticLockException`` はスローされません。
@@ -196,7 +232,7 @@ ignoreVersion
   int[] update(List<Employee> employees);
 
 suppressOptimisticLockException
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``@BatchUpdate`` の ``suppressOptimisticLockException`` 要素が ``true`` の場合、
 更新件数が0件または複数件であっても ``BatchOptimisticLockException`` はスローされません。
@@ -251,4 +287,3 @@ SQL のログ出力形式
   int[] update(List<Employee> employees);
 
 ``SqlLogType.RAW`` はバインドパラメータ（?）付きの SQL をログ出力することを表します。
-

docs/sources/query/update.rst

@@ -34,6 +34,8 @@
 
 上記の条件を満たさないない場合、戻り値は更新件数を表す ``int`` でなければいけません。
 
+.. _auto-update:
+
 SQLの自動生成による更新
 =======================
 
@@ -163,6 +165,37 @@ SQLファイルによる更新
 SQLファイルによる更新を行うには、 ``@Update`` の ``sqlFile`` 要素に ``true`` を設定し、
 メソッドに対応するSQLファイルを用意します。
 
+.. note::
+
+  SQLファイルによる更新は、 :ref:`populate` の利用有無によりルールが異なります。
+
+更新カラムリスト生成コメントを使用する場合
+-------------------------------------------------
+
+最初のパラメータの型はエンティティクラスでなければいけません。
+指定できるパラメータの数に制限はありません。
+パラメータの型が基本型もしくはドメインクラスの場合、引数を ``null`` にできます。
+それ以外の型の場合、引数は ``null`` であってはいけません。
+
+.. code-block:: java
+
+  @Update(sqlFile = true)
+  int update(Employee employee, BigDecimal salary);
+
+  @Update(sqlFile = true)
+  Result<ImmutableEmployee> update(ImmutableEmployee employee, , BigDecimal salary);
+
+たとえば、上記のメソッドに対応するSQLは次のように記述します。
+
+.. code-block:: sql
+
+  update employee set /*%populate*/ id = id where salary > /* salary */0
+
+更新対象プロパティの制御に関するルールは、 :ref:`auto-update` と同じです。
+
+更新カラムリスト生成コメントを使用しない場合
+-------------------------------------------------
+
 パラメータには任意の型が使用できます。
 指定できるパラメータの数に制限はありません。
 パラメータの型が基本型もしくはドメインクラスの場合、引数を ``null`` にできます。
@@ -188,7 +221,7 @@ SQLファイルによる更新では、
 ``includeUnchanged`` 要素は参照されません。
 
 SQLファイルにおけるバージョン番号と楽観的排他制御
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 次の条件を満たす場合に、楽観的排他制御が行われます。
 
@@ -211,7 +244,7 @@ WHERE句でバージョンを番号を指定しSET句でバージョン番号を
 エンティティのバージョンプロパティの値が1増分されます。
 
 ignoreVersion
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 ``@Update`` の ``ignoreVersion`` 要素が ``true`` の場合、
 更新件数が0件であっても、 ``OptimisticLockException`` はスローされません。
@@ -223,7 +256,7 @@ ignoreVersion
   int update(Employee employee);
 
 suppressOptimisticLockException
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``@Update`` の ``suppressOptimisticLockException`` 要素が ``true`` の場合、
 更新件数が0件であっても、 ``OptimisticLockException`` はスローされません。

docs/sources/sql.rst

@@ -208,7 +208,7 @@ Dao インタフェースのメソッドと対応する SQL の例は次のと
 
   select * from employee
   where
-  employee_name = /* dto.employeeName */'abc' 
+  employee_name = /* dto.employeeName */'abc'
   and
   salary = /* dto.salary */1234
 
@@ -279,7 +279,7 @@ ifとend
 
 .. code-block:: sql
 
-  select * from employee where 
+  select * from employee where
   /*%if employeeId != null */
       employee_id = /* employeeId */99
   /*%end*/
@@ -307,7 +307,7 @@ ifとend
 
 .. code-block:: sql
 
-  select * from employee where 
+  select * from employee where
   /*%if employeeId != null */
       employee_id = /* employeeId */99
   /*%end*/
@@ -327,7 +327,7 @@ ifとend
 
 .. code-block:: sql
 
-  select * from employee where 
+  select * from employee where
   /*%if employeeId != null */
       employee_id = /* employeeId */99
   /*%end*/
@@ -351,14 +351,14 @@ elseifとelse
 
 .. code-block:: sql
 
-  select 
-    * 
+  select
+    *
   from
-    employee 
-  where 
+    employee
+  where
   /*%if employeeId != null */
     employee_id = /* employeeId */9999
-  /*%elseif department_id != null */ 
+  /*%elseif department_id != null */
     and
     department_id = /* departmentId */99
   /*%else*/
@@ -370,35 +370,35 @@ elseifとelse
 
 .. code-block:: sql
 
-  select 
-    * 
+  select
+    *
   from
-    employee 
-  where 
+    employee
+  where
     employee_id = ?
 
 ``employeeId == null && department_id != null`` が成立するとき、実際は次の SQL に変換されます。
 ``department_id`` の直前の ``AND`` は自動で除去されるため出力されません。
 
 .. code-block:: sql
 
-  select 
-    * 
+  select
+    *
   from
-    employee 
-  where 
+    employee
+  where
     department_id = ?
 
 ``employeeId == null && department_id == null`` が成立するとき、実際は次の SQL に変換されます。
 ``department_id`` の直前の ``AND`` は自動で除去されるため出力されません。
 
 .. code-block:: sql
 
-  select 
-    * 
+  select
+    *
   from
-    employee 
-  where 
+    employee
+  where
     department_id is null
 
 ネストした条件コメント
@@ -408,10 +408,10 @@ elseifとelse
 
 .. code-block:: sql
 
-  select * from employee where 
+  select * from employee where
   /*%if employeeId != null */
     employee_id = /* employeeId */99
-    /*%if employeeName != null */ 
+    /*%if employeeName != null */
       and
       employee_name = /* employeeName */'hoge'
     /*%else*/
@@ -429,7 +429,7 @@ elseifとelse
 
 .. code-block:: sql
 
-  select * from employee /*%if employeeId != null */ 
+  select * from employee /*%if employeeId != null */
   where employee_id = /* employeeId */99 /*%end*/
 
 また、 ``if`` と ``end`` は同じレベルの文に含まれなければいけません。
@@ -472,7 +472,7 @@ forとend
 .. code-block:: sql
 
   select * from employee where
-  employee_name like ? 
+  employee_name like ?
   or
   employee_name like ?
   or
@@ -502,7 +502,7 @@ item_has_nextとitem_index
 
 .. code-block:: sql
 
-  select * from employee where 
+  select * from employee where
   /*%for name : names */
   employee_name like /* name */'hoge'
     /*%if name_has_next */
@@ -525,7 +525,7 @@ item_has_nextとitem_index
 
 .. code-block:: sql
 
-  select * from employee where 
+  select * from employee where
   /*%for name : names */
   employee_name like /* name */'hoge'
     /*%if name_has_next */
@@ -550,14 +550,14 @@ item_has_nextとitem_index
 また、 ``for`` と ``end`` は同じレベルの文に含まれなければいけません。
 つまり、括弧の外で ``for`` 、括弧の内側で ``end`` という記述は認められません。
 
-カラムリスト展開コメント
-------------------------
+選択カラムリスト展開コメント
+----------------------------
 
 expand
 ~~~~~~
 
 SELECT節のアスタリスク ``*`` を :doc:`entity` の定義を
-参照して自動でカラムのリストに展開する式をカラムリスト展開コメントと呼びます。
+参照して自動でカラムのリストに展開する式を選択カラムリスト展開コメントと呼びます。
 構文は次のとおりです。
 
 ::
@@ -593,7 +593,7 @@ SELECT節のアスタリスク ``*`` を :doc:`entity` の定義を
   select id, name, age from employee
 
 SQL 上でテーブルにエイリアスを指定する場合、
-カラムリスト展開コメントにも同じエイリアスを指定してください。
+選択カラムリスト展開コメントにも同じエイリアスを指定してください。
 
 .. code-block:: sql
 
@@ -605,6 +605,49 @@ SQL 上でテーブルにエイリアスを指定する場合、
 
   select e.id, e.name, e.age from employee e
 
+.. _populate:
+
+更新カラムリスト生成コメント
+-----------------------------
+
+populate
+~~~~~~~~
+
+UPDATE文のSET節 を :doc:`entity` の定義を
+参照して自動で生成する式を更新カラムリスト生成コメントと呼びます。
+構文は次のとおりです。
+
+::
+
+  /*%populate*/
+
+
+例を示します。
+
+.. code-block:: sql
+
+  update employee set /*%populate*/ id = id where age < 30
+
+上記のSQL文への入力が次のような :doc:`entity` にマッピングされているものとします。
+
+.. code-block:: java
+
+   @Entity
+   public class Employee {
+       Integer id;
+       String name;
+       Integer age;
+   }
+
+このとき、 SQL は以下のように変換されます。
+
+.. code-block:: sql
+
+  update employee set id = ?, name = ?, age = ? where age < 30
+
+更新カラムリスト生成コメントは、 ``/*%populate*/`` からWHERE句までをカラムリストで置き換えます。
+つまり、元のSQLにあった ``id = id`` の記述は最終的なSQLからは削除されます。
+
 通常のブロックコメント
 ----------------------
 
@@ -649,4 +692,3 @@ SQL 上でテーブルにエイリアスを指定する場合、
 ``--`` は通常の行コメントだとみなされます。
 
 Domaでは行コメントを特別に解釈することはありません。
-