Introduce RETURNING functionality for DSL and DAO operations (#1321)

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/Delete.java

@@ -100,4 +100,10 @@
    * @return the output format of SQL logs.
    */
   SqlLogType sqlLog() default SqlLogType.FORMATTED;
+
+  /**
+   * @return the {@link Returning} annotation configuration, which defines inclusions or exclusions
+   *     for returning values.
+   */
+  Returning returning() default @Returning;
 }

doma-core/src/main/java/org/seasar/doma/Insert.java

@@ -137,4 +137,10 @@
    * @return the keys that should be used to determine if a duplicate key exists.
    */
   String[] duplicateKeys() default {};
+
+  /**
+   * @return the {@link Returning} annotation configuration, which defines inclusions or exclusions
+   *     for returning values.
+   */
+  Returning returning() default @Returning;
 }

doma-core/src/main/java/org/seasar/doma/MultiInsert.java

@@ -116,4 +116,10 @@
    * @return the keys that should be used to determine if a duplicate key exists.
    */
   String[] duplicateKeys() default {};
+
+  /**
+   * @return the {@link Returning} annotation configuration, which defines inclusions or exclusions
+   *     for returning values.
+   */
+  Returning returning() default @Returning;
 }

doma-core/src/main/java/org/seasar/doma/Returning.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright Doma Authors
+ *
+ * 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
+ *
+ *     https://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;
+
+/**
+ * Indicates that specific properties of an entity should be included or excluded in the context of
+ * a {@link Dao} operation.
+ *
+ * <ul>
+ *   <li>These attributes are optional and can be used together.
+ *   <li>When neither attribute is specified, all properties are included by default.
+ * </ul>
+ */
+public @interface Returning {
+  /**
+   * Specifies the names of properties to be explicitly included. If specified, only the listed
+   * properties will be included.
+   *
+   * @return an array of property names to include
+   */
+  String[] include() default {};
+
+  /**
+   * Specifies the names of properties to be explicitly excluded. If specified, all properties will
+   * be included except for those listed.
+   *
+   * @return an array of property names to exclude
+   */
+  String[] exclude() default {};
+}

doma-core/src/main/java/org/seasar/doma/Update.java

@@ -138,4 +138,10 @@
    * @return the output format of SQL logs.
    */
   SqlLogType sqlLog() default SqlLogType.FORMATTED;
+
+  /**
+   * @return the {@link Returning} annotation configuration, which defines inclusions or exclusions
+   *     for returning values.
+   */
+  Returning returning() default @Returning;
 }

doma-core/src/main/java/org/seasar/doma/jdbc/CommandImplementors.java

@@ -17,6 +17,7 @@
 
 import java.lang.reflect.Method;
 import java.util.function.BiFunction;
+import java.util.function.Supplier;
 import org.seasar.doma.jdbc.aggregate.AggregateCommand;
 import org.seasar.doma.jdbc.aggregate.AggregateStrategyType;
 import org.seasar.doma.jdbc.aggregate.StreamReducer;
@@ -26,14 +27,17 @@
 import org.seasar.doma.jdbc.command.Command;
 import org.seasar.doma.jdbc.command.CreateCommand;
 import org.seasar.doma.jdbc.command.DeleteCommand;
+import org.seasar.doma.jdbc.command.DeleteReturningCommand;
 import org.seasar.doma.jdbc.command.FunctionCommand;
 import org.seasar.doma.jdbc.command.InsertCommand;
+import org.seasar.doma.jdbc.command.InsertReturningCommand;
 import org.seasar.doma.jdbc.command.ProcedureCommand;
 import org.seasar.doma.jdbc.command.ResultSetHandler;
 import org.seasar.doma.jdbc.command.ScriptCommand;
 import org.seasar.doma.jdbc.command.SelectCommand;
 import org.seasar.doma.jdbc.command.SqlProcessorCommand;
 import org.seasar.doma.jdbc.command.UpdateCommand;
+import org.seasar.doma.jdbc.command.UpdateReturningCommand;
 import org.seasar.doma.jdbc.entity.EntityType;
 import org.seasar.doma.jdbc.query.BatchDeleteQuery;
 import org.seasar.doma.jdbc.query.BatchInsertQuery;
@@ -65,6 +69,20 @@ default <RESULT> SelectCommand<RESULT> createSelectCommand(
     return new SelectCommand<>(query, resultSetHandler);
   }
 
+  /**
+   * Creates an {@link AggregateCommand} object for aggregating entities based on a specified query
+   * and strategy.
+   *
+   * @param <RESULT> the result type of the aggregation
+   * @param <ENTITY> the entity type used in the aggregation
+   * @param method the DAO method associated with the command
+   * @param query the select query to be executed
+   * @param entityType the type of the root entity for aggregation
+   * @param resultReducer the reducer used to process the stream of aggregated entities into a final
+   *     result
+   * @param aggregateStrategyType the strategy type used for aggregation logic
+   * @return a new {@link AggregateCommand} instance configured with the provided parameters
+   */
   default <RESULT, ENTITY> AggregateCommand<RESULT, ENTITY> createAggregateCommand(
       Method method,
       SelectQuery query,
@@ -107,6 +125,58 @@ default UpdateCommand createUpdateCommand(Method method, UpdateQuery query) {
     return new UpdateCommand(query);
   }
 
+  /**
+   * Creates a {@link DeleteReturningCommand} object.
+   *
+   * @param <RESULT> the result type of the command
+   * @param method the DAO method
+   * @param query the delete query
+   * @param resultSetHandler the handler for processing the result set
+   * @param emptyResultSupplier the supplier for providing an empty result
+   * @return the created {@link DeleteReturningCommand} object
+   */
+  default <RESULT> DeleteReturningCommand<RESULT> createDeleteReturningCommand(
+      Method method,
+      DeleteQuery query,
+      ResultSetHandler<RESULT> resultSetHandler,
+      Supplier<RESULT> emptyResultSupplier) {
+    return new DeleteReturningCommand<>(query, resultSetHandler, emptyResultSupplier);
+  }
+
+  /**
+   * Creates an {@link InsertReturningCommand} object.
+   *
+   * @param method the DAO method
+   * @param query the query
+   * @param resultSetHandler the result set handler
+   * @return the command
+   */
+  default <RESULT> InsertReturningCommand<RESULT> createInsertReturningCommand(
+      Method method,
+      InsertQuery query,
+      ResultSetHandler<RESULT> resultSetHandler,
+      Supplier<RESULT> emptyResultSupplier) {
+    return new InsertReturningCommand<>(query, resultSetHandler, emptyResultSupplier);
+  }
+
+  /**
+   * Creates an {@link UpdateReturningCommand} object.
+   *
+   * @param <RESULT> the result type of the command
+   * @param method the DAO method
+   * @param query the update query
+   * @param resultSetHandler the handler for processing the result set
+   * @param emptyResultSupplier the supplier for providing an empty result
+   * @return the created {@link UpdateReturningCommand} object
+   */
+  default <RESULT> UpdateReturningCommand<RESULT> createUpdateReturningCommand(
+      Method method,
+      UpdateQuery query,
+      ResultSetHandler<RESULT> resultSetHandler,
+      Supplier<RESULT> emptyResultSupplier) {
+    return new UpdateReturningCommand<>(query, resultSetHandler, emptyResultSupplier);
+  }
+
   /**
    * Creates a {@link BatchDeleteCommand} object.
    *

doma-core/src/main/java/org/seasar/doma/jdbc/command/DeleteReturningCommand.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Doma Authors
+ *
+ * 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
+ *
+ *     https://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.jdbc.command;
+
+import java.sql.PreparedStatement;
+import java.sql.SQLException;
+import java.util.function.Supplier;
+import org.seasar.doma.jdbc.query.DeleteQuery;
+import org.seasar.doma.jdbc.statistic.StatisticManager;
+
+public class DeleteReturningCommand<RESULT> extends ModifyReturningCommand<DeleteQuery, RESULT> {
+
+  public DeleteReturningCommand(
+      DeleteQuery query,
+      ResultSetHandler<RESULT> resultSetHandler,
+      Supplier<RESULT> emptyResultSupplier) {
+    super(query, resultSetHandler, emptyResultSupplier);
+  }
+
+  @Override
+  protected RESULT executeInternal(PreparedStatement preparedStatement) throws SQLException {
+    StatisticManager statisticManager = query.getConfig().getStatisticManager();
+    return statisticManager.executeSql(query.getSql(), () -> executeQuery(preparedStatement));
+  }
+}

doma-core/src/main/java/org/seasar/doma/jdbc/command/InsertReturningCommand.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Doma Authors
+ *
+ * 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
+ *
+ *     https://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.jdbc.command;
+
+import java.sql.PreparedStatement;
+import java.sql.SQLException;
+import java.util.function.Supplier;
+import org.seasar.doma.jdbc.query.InsertQuery;
+import org.seasar.doma.jdbc.statistic.StatisticManager;
+
+public class InsertReturningCommand<RESULT> extends ModifyReturningCommand<InsertQuery, RESULT> {
+
+  public InsertReturningCommand(
+      InsertQuery query,
+      ResultSetHandler<RESULT> resultSetHandler,
+      Supplier<RESULT> emptyResultSupplier) {
+    super(query, resultSetHandler, emptyResultSupplier);
+  }
+
+  @Override
+  protected RESULT executeInternal(PreparedStatement preparedStatement) throws SQLException {
+    StatisticManager statisticManager = query.getConfig().getStatisticManager();
+    return statisticManager.executeSql(query.getSql(), () -> executeQuery(preparedStatement));
+  }
+}