Update aggregate-strategy.rst to support BiConsumer functions

Author: nakamura-to

docs/aggregate-strategy.rst

@@ -29,19 +29,21 @@ This annotation specifies how an entity aggregate is reconstructed from a query
 Association linker definition
 ===============================
 
-An aggregate strategy must contain at least one field of type ``BiFunction`` annotated with ``@AssociationLinker``.
-This ``BiFunction`` is responsible for dynamically associating two entity instances.
+An aggregate strategy must contain at least one field of type ``BiConsumer`` or ``BiFunction``,
+annotated with ``@AssociationLinker``.
+These functions are responsible for dynamically associating two entity instances.
+Use a ``BiFunction`` when associating immutable entities.
+For mutable entities, you may use either a ``BiConsumer`` or a ``BiFunction``.
 
 .. code-block:: java
 
     @AggregateStrategy(root = Department.class, tableAlias = "d")
     interface DepartmentAggregateStrategy {
       @AssociationLinker(propertyPath = "employees", tableAlias = "e")
-      BiFunction<Department, Employee, Department> employees =
+      BiConsumer<Department, Employee> employees =
           (d, e) -> {
             d.getEmployees().add(e);
             e.setDepartment(d);
-            return d;
           };
 
       @AssociationLinker(propertyPath = "employees.address", tableAlias = "a")
@@ -52,11 +54,13 @@ This ``BiFunction`` is responsible for dynamically associating two entity instan
           };
     }
 
-- In the ``BiFunction``, the first and third type parameters represent the class that owns the property,
-  while the second type parameter represents the property type.
-- The ``propertyPath`` element specifies the target property's name as a dot-separated path from the root entity class.
+- The first type parameter of a ``BiConsumer`` or ``BiFunction`` represents the type of the property owner,
+  and the second type parameter represents the type of the property.
+  The third type parameter of a ``BiFunction`` must be the same as the first one and represents the type of
+  the entity after the association is applied.
+- The ``propertyPath`` element specifies the name of the target property as a dot-separated path from the root entity class.
 - The ``tableAlias`` element specifies the alias for the table corresponding to the entity class used as the second
-  type parameter of ``BiFunction``. This alias must be used in the SELECT statement.
+  type parameter of the ``BiConsumer`` or ``BiFunction``. This alias must be used in the SELECT statement.
 
 Example
 ================

docs/locale/ja/LC_MESSAGES/aggregate-strategy.po

@@ -2,7 +2,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: doma-docs\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-05-03 13:10+0900\n"
+"POT-Creation-Date: 2025-05-05 21:25+0900\n"
 "Last-Translator: \n"
 "Language-Team: Japanese\n"
 "MIME-Version: 1.0\n"
@@ -48,90 +48,90 @@ msgid "Association linker definition"
 msgstr "関連付けリンカーの定義"
 
 #: ../../aggregate-strategy.rst:32
-msgid "An aggregate strategy must contain at least one field of type ``BiFunction`` annotated with ``@AssociationLinker``. This ``BiFunction`` is responsible for dynamically associating two entity instances."
-msgstr "アグリゲート戦略には、``@AssociationLinker`` で注釈された ``BiFunction`` 型のフィールドが少なくとも1つ含まれている必要があります。``BiFunction`` は、2つのエンティティインスタンスを動的に関連付ける責任があります。"
-
-#: ../../aggregate-strategy.rst:55
-msgid "In the ``BiFunction``, the first and third type parameters represent the class that owns the property, while the second type parameter represents the property type."
-msgstr "``BiFunction`` の最初と 3 番目の型パラメータはプロパティを所有するクラスを表し、2 番目の型パラメータはプロパティの型を表します。"
+msgid "An aggregate strategy must contain at least one field of type ``BiConsumer`` or ``BiFunction``, annotated with ``@AssociationLinker``. These functions are responsible for dynamically associating two entity instances. Use a ``BiFunction`` when associating immutable entities. For mutable entities, you may use either a ``BiConsumer`` or a ``BiFunction``."
+msgstr "アグリゲート戦略には、 ``@AssociationLinker`` で注釈された ``BiConsumer`` または ``BiFunction`` 型のフィールドが少なくとも1つ含まれている必要があります。これらの関数は、2つのエンティティインスタンスを動的に関連付ける責任があります。不変エンティティを関連付ける場合は、``BiFunction`` を使用します。変更可能なエンティティの場合は、``BiConsumer`` または ``BiFunction`` のいずれかを使用できます。"
 
 #: ../../aggregate-strategy.rst:57
-msgid "The ``propertyPath`` element specifies the target property's name as a dot-separated path from the root entity class."
+msgid "The first type parameter of a ``BiConsumer`` or ``BiFunction`` represents the type of the property owner, and the second type parameter represents the type of the property. The third type parameter of a ``BiFunction`` must be the same as the first one and represents the type of the entity after the association is applied."
+msgstr "``BiConsumer`` と ``BiFunction`` の1番目の型パラメータはプロパティオーナーの型を表し、2番目の型パラメータはプロパティの型を表します。 ``BiFunction`` の3番目の型パラメータは1番目のものと同じでなければならず、関連付けが適用された後のエンティティの型を表します。"
+
+#: ../../aggregate-strategy.rst:61
+msgid "The ``propertyPath`` element specifies the name of the target property as a dot-separated path from the root entity class."
 msgstr "``propertyPath`` 要素は、ルートエンティティクラスからドットで区切られたパスとしてターゲットプロパティの名前を指定します。"
 
-#: ../../aggregate-strategy.rst:58
-msgid "The ``tableAlias`` element specifies the alias for the table corresponding to the entity class used as the second type parameter of ``BiFunction``. This alias must be used in the SELECT statement."
+#: ../../aggregate-strategy.rst:62
+msgid "The ``tableAlias`` element specifies the alias for the table corresponding to the entity class used as the second type parameter of the ``BiConsumer`` or ``BiFunction``. This alias must be used in the SELECT statement."
 msgstr "``tableAlias`` 要素は、``BiFunction`` の 2 番目の型パラメータとして使用されるエンティティクラスに対応するテーブルのエイリアスを指定します。 このエイリアスはSELECT文で使用する必要があります。"
 
-#: ../../aggregate-strategy.rst:62
+#: ../../aggregate-strategy.rst:66
 msgid "Example"
 msgstr "例"
 
-#: ../../aggregate-strategy.rst:64
+#: ../../aggregate-strategy.rst:68
 msgid "The ``DepartmentAggregateStrategy`` described above is based on the following entity definitions:"
 msgstr "上記の ``DepartmentAggregateStrategy`` は以下のエンティティ定義に基づいています。"
 
-#: ../../aggregate-strategy.rst:97
+#: ../../aggregate-strategy.rst:101
 msgid "In entity classes, association properties must be annotated with ``@Association``. These properties can be linked using ``@AssociationLinker``."
 msgstr "エンティティクラスでは、関連プロパティに ``@Association`` を付与する必要があります。これらのプロパティは ``@AssociationLinker`` を使用してリンクできます。"
 
-#: ../../aggregate-strategy.rst:101
+#: ../../aggregate-strategy.rst:105
 msgid "Using an aggregate strategy"
 msgstr "アグリゲート戦略の使用"
 
-#: ../../aggregate-strategy.rst:103
+#: ../../aggregate-strategy.rst:107
 msgid "``DepartmentAggregateStrategy`` is used by specifying it in the ``aggregateStrategy`` element of ``@Select``:"
 msgstr "``DepartmentAggregateStrategy`` は ``@Select`` の ``aggregateStrategy`` 要素に指定することで使用されます。"
 
-#: ../../aggregate-strategy.rst:113
+#: ../../aggregate-strategy.rst:117
 msgid "The ``selectById`` method requires a SELECT statement like the following:"
 msgstr "``selectById`` メソッドは、次のような SELECT ステートメントを必要とします:"
 
-#: ../../aggregate-strategy.rst:137
+#: ../../aggregate-strategy.rst:141
 msgid "The SELECT list must include the IDs of all entities that form the aggregate."
 msgstr "SELECTリストにはアグリゲートを形成するすべてのエンティティのIDを含める必要があります。"
 
-#: ../../aggregate-strategy.rst:140
+#: ../../aggregate-strategy.rst:144
 msgid "Column aliasing rules"
 msgstr "カラムエイリアスのルール"
 
-#: ../../aggregate-strategy.rst:142
+#: ../../aggregate-strategy.rst:146
 msgid "Table aliases must match those defined in ``DepartmentAggregateStrategy``."
 msgstr "テーブルエイリアスは ``DepartmentAggregateStrategy`` で定義されているものと一致する必要があります。"
 
-#: ../../aggregate-strategy.rst:143
+#: ../../aggregate-strategy.rst:147
 msgid "Column aliases must begin with the table alias followed by an underscore (``_``). For example, ``d.id`` should be aliased as ``d_id`` and ``e.id`` as ``e_id``."
 msgstr "カラムのエイリアスは、テーブルのエイリアスにアンダースコア（``_``）を付けた形式で指定する必要があります。例えば、``d.id`` は ``d_id``、``e.id`` は ``e_id`` としてエイリアスされます。"
 
-#: ../../aggregate-strategy.rst:147
+#: ../../aggregate-strategy.rst:151
 msgid "Using the expansion directive"
 msgstr "選択カラムリスト展開ディレクティブの使用"
 
-#: ../../aggregate-strategy.rst:149
+#: ../../aggregate-strategy.rst:153
 msgid "By using the :ref:`expansion directive <expand>`, the above SELECT statement can be written more concisely:"
 msgstr ":ref:`選択カラムリスト展開ディレクティブ <expand>` を使用することで、上記のSELECT文をより簡潔に記述することができます。"
 
-#: ../../aggregate-strategy.rst:166
+#: ../../aggregate-strategy.rst:170
 msgid "How expansion works"
 msgstr "カラムリスト展開の仕組み"
 
-#: ../../aggregate-strategy.rst:168
+#: ../../aggregate-strategy.rst:172
 msgid "The ``/*%expand*/*`` directive automatically expands into a column list following predefined aliasing rules."
 msgstr "``/*%expand */*`` ディレクティブは、あらかじめ定義されたエイリアスルールを使用して列リストに自動的に展開します。"
 
-#: ../../aggregate-strategy.rst:169
+#: ../../aggregate-strategy.rst:173
 msgid "By default, all columns from all tables are included in the result set."
 msgstr "デフォルトでは、すべてのテーブルのすべての列が結果セットに含まれます。"
 
-#: ../../aggregate-strategy.rst:171
+#: ../../aggregate-strategy.rst:175
 msgid "To selectively expand only specific tables, pass a comma-separated list of table aliases:"
 msgstr "特定のテーブルのみを選択的に展開するには、テーブルエイリアスのカンマ区切りリストを渡します。"
 
-#: ../../aggregate-strategy.rst:188
+#: ../../aggregate-strategy.rst:192
 msgid "Here, only columns from tables ``e`` (``employee``) and ``d`` (``department``) are expanded."
 msgstr "ここでは、テーブルの ``e`` (``employee``) と ``d`` (``department``) のカラムのみが展開されます。"
 
-#: ../../aggregate-strategy.rst:189
+#: ../../aggregate-strategy.rst:193
 msgid "The columns from table ``a`` (``address``) are explicitly specified."
 msgstr "テーブル ``a`` (``address``) の列は明示的に指定されています。"