Add support for the @Returning annotation in Delete, Insert, and Update DAO operations

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/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/message/Message.java

@@ -1005,6 +1005,12 @@ public enum Message implements MessageResource {
   DOMA4489("The property path \"{0}\" is duplicated in another @AssociationLinker."),
   DOMA4490(
       "Multiple @ExternalDomain definitions were found for type \"{0}\". \"{1}\" conflicts with \"{2}\"."),
+  DOMA4491("\"returning = @Returning\" cannot be specified when \"sqlFile = true\"."),
+  DOMA4492("\"returning = @Returning\" is not allowed in combination with @Sql."),
+  DOMA4493("The property \"{0}\" is not found in the entity class \"{1}\"."),
+  DOMA4494("The property \"{0}\" is not found in the entity class \"{1}\"."),
+  DOMA4495(
+      "When \"returning = @Returning\" is specified, the return type must be the same as the parameter type or an Optional whose element is the parameter type."),
 
   // other
   DOMA5001(

doma-processor/src/main/java/org/seasar/doma/internal/apt/annot/Annotations.java

@@ -188,7 +188,14 @@ public DomainConvertersAnnot newDomainConvertersAnnot(TypeElement typeElement) {
 
   public DeleteAnnot newDeleteAnnot(ExecutableElement method) {
     assertNotNull(method);
-    return newInstance(method, Delete.class, DeleteAnnot::new);
+    AnnotationMirror deleteMirror = ctx.getMoreElements().getAnnotationMirror(method, Delete.class);
+    if (deleteMirror == null) {
+      return null;
+    }
+    ReturningAnnot returningAnnot = newReturningAnnot(deleteMirror, ModifyAnnot.RETURNING);
+    Map<String, AnnotationValue> valuesWithDefaults =
+        ctx.getMoreElements().getValuesWithDefaults(deleteMirror);
+    return new DeleteAnnot(deleteMirror, returningAnnot, valuesWithDefaults);
   }
 
   public EmbeddableAnnot newEmbeddableAnnot(TypeElement typeElement) {
@@ -241,7 +248,14 @@ public FunctionAnnot newFunctionAnnot(final ExecutableElement method) {
 
   public InsertAnnot newInsertAnnot(ExecutableElement method) {
     assertNotNull(method);
-    return newInstance(method, Insert.class, InsertAnnot::new);
+    AnnotationMirror insertMirror = ctx.getMoreElements().getAnnotationMirror(method, Insert.class);
+    if (insertMirror == null) {
+      return null;
+    }
+    ReturningAnnot returningAnnot = newReturningAnnot(insertMirror, ModifyAnnot.RETURNING);
+    Map<String, AnnotationValue> valuesWithDefaults =
+        ctx.getMoreElements().getValuesWithDefaults(insertMirror);
+    return new InsertAnnot(insertMirror, returningAnnot, valuesWithDefaults);
   }
 
   public MultiInsertAnnot newMultiInsertAnnot(ExecutableElement method) {
@@ -273,6 +287,27 @@ public ResultSetAnnot newResultSetAnnot(VariableElement param) {
     return newInstance(param, ResultSet.class, ResultSetAnnot::new);
   }
 
+  private ReturningAnnot newReturningAnnot(AnnotationMirror annotationMirror) {
+    assertNotNull(annotationMirror);
+    return newInstance(annotationMirror, ReturningAnnot::new);
+  }
+
+  private ReturningAnnot newReturningAnnot(
+      AnnotationMirror ownerAnnotationMirror, String returningElementName) {
+    assertNotNull(ownerAnnotationMirror, returningElementName);
+    Map<String, AnnotationValue> valuesWithoutDefaults =
+        ctx.getMoreElements().getValuesWithoutDefaults(ownerAnnotationMirror);
+    AnnotationValue returning = valuesWithoutDefaults.get(returningElementName);
+    if (returning == null) {
+      return null;
+    }
+    AnnotationMirror returningMirror = AnnotationValueUtil.toAnnotation(returning);
+    if (returningMirror == null) {
+      return null;
+    }
+    return newReturningAnnot(returningMirror);
+  }
+
   public ScriptAnnot newScriptAnnot(ExecutableElement method) {
     assertNotNull(method);
     return newInstance(method, Script.class, ScriptAnnot::new);
@@ -315,7 +350,14 @@ public TableAnnot newTableAnnot(TypeElement typeElement) {
 
   public UpdateAnnot newUpdateAnnot(ExecutableElement method) {
     assertNotNull(method);
-    return newInstance(method, Update.class, UpdateAnnot::new);
+    AnnotationMirror updateMirror = ctx.getMoreElements().getAnnotationMirror(method, Update.class);
+    if (updateMirror == null) {
+      return null;
+    }
+    ReturningAnnot returningAnnot = newReturningAnnot(updateMirror, ModifyAnnot.RETURNING);
+    Map<String, AnnotationValue> valuesWithDefaults =
+        ctx.getMoreElements().getValuesWithDefaults(updateMirror);
+    return new UpdateAnnot(updateMirror, returningAnnot, valuesWithDefaults);
   }
 
   public ValueAnnot newValueAnnot(TypeElement typeElement) {

doma-processor/src/main/java/org/seasar/doma/internal/apt/annot/DeleteAnnot.java

@@ -21,7 +21,10 @@
 
 public class DeleteAnnot extends ModifyAnnot {
 
-  DeleteAnnot(AnnotationMirror annotationMirror, Map<String, AnnotationValue> values) {
-    super(annotationMirror, values);
+  DeleteAnnot(
+      AnnotationMirror annotationMirror,
+      ReturningAnnot returningAnnot,
+      Map<String, AnnotationValue> values) {
+    super(annotationMirror, returningAnnot, values);
   }
 }

doma-processor/src/main/java/org/seasar/doma/internal/apt/annot/InsertAnnot.java

@@ -21,7 +21,10 @@
 
 public class InsertAnnot extends ModifyAnnot {
 
-  InsertAnnot(AnnotationMirror annotationMirror, Map<String, AnnotationValue> values) {
-    super(annotationMirror, values);
+  InsertAnnot(
+      AnnotationMirror annotationMirror,
+      ReturningAnnot returningAnnot,
+      Map<String, AnnotationValue> values) {
+    super(annotationMirror, returningAnnot, values);
   }
 }

doma-processor/src/main/java/org/seasar/doma/internal/apt/annot/ModifyAnnot.java

@@ -52,6 +52,10 @@ public abstract class ModifyAnnot extends AbstractAnnot {
 
   private static final String DUPLICATE_KEYS = "duplicateKeys";
 
+  static final String RETURNING = "returning";
+
+  private final ReturningAnnot returningAnnot;
+
   private final AnnotationValue sqlFile;
 
   private final AnnotationValue queryTimeout;
@@ -74,7 +78,10 @@ public abstract class ModifyAnnot extends AbstractAnnot {
 
   private final AnnotationValue duplicateKeys;
 
-  ModifyAnnot(AnnotationMirror annotationMirror, Map<String, AnnotationValue> values) {
+  ModifyAnnot(
+      AnnotationMirror annotationMirror,
+      ReturningAnnot returningAnnot,
+      Map<String, AnnotationValue> values) {
     super(annotationMirror);
 
     // non null values
@@ -83,6 +90,7 @@ public abstract class ModifyAnnot extends AbstractAnnot {
     this.sqlLog = assertNonNullValue(values, SQL_LOG);
 
     // nullable values
+    this.returningAnnot = returningAnnot;
     this.ignoreVersion = values.get(IGNORE_VERSION);
     this.excludeNull = values.get(EXCLUDE_NULL);
     this.suppressOptimisticLockException = values.get(SUPPRESS_OPTIMISTIC_LOCK_EXCEPTION);
@@ -93,6 +101,10 @@ public abstract class ModifyAnnot extends AbstractAnnot {
     this.duplicateKeys = values.get(DUPLICATE_KEYS);
   }
 
+  public ReturningAnnot getReturningAnnot() {
+    return returningAnnot;
+  }
+
   public AnnotationValue getSqlFile() {
     return sqlFile;
   }

doma-processor/src/main/java/org/seasar/doma/internal/apt/annot/ReturningAnnot.java

@@ -0,0 +1,57 @@
+/*
+ * 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.internal.apt.annot;
+
+import static org.seasar.doma.internal.util.AssertionUtil.assertNonNullValue;
+
+import java.util.List;
+import java.util.Map;
+import javax.lang.model.element.AnnotationMirror;
+import javax.lang.model.element.AnnotationValue;
+import org.seasar.doma.internal.apt.util.AnnotationValueUtil;
+
+public class ReturningAnnot extends AbstractAnnot {
+
+  private static final String INCLUDE = "include";
+
+  private static final String EXCLUDE = "exclude";
+
+  private final AnnotationValue include;
+
+  private final AnnotationValue exclude;
+
+  ReturningAnnot(AnnotationMirror annotationMirror, Map<String, AnnotationValue> values) {
+    super(annotationMirror);
+    this.include = assertNonNullValue(values, INCLUDE);
+    this.exclude = assertNonNullValue(values, EXCLUDE);
+  }
+
+  public AnnotationValue getInclude() {
+    return include;
+  }
+
+  public AnnotationValue getExclude() {
+    return exclude;
+  }
+
+  public List<String> getIncludeValue() {
+    return AnnotationValueUtil.toStringList(include);
+  }
+
+  public List<String> getExcludeValue() {
+    return AnnotationValueUtil.toStringList(exclude);
+  }
+}