feat: add columnOverrides attribute to @Embedded annotation (#1386)

Author: nakamura-to

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

@@ -0,0 +1,87 @@
+/*
+ * 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;
+
+/**
+ * Overrides the column mapping for a specific property within an embeddable object.
+ *
+ * <p>This annotation is used within the {@link Embedded} annotation to customize how properties of
+ * an embeddable object are mapped to database columns. It allows you to override the default column
+ * name and attributes (such as insertable, updatable, and quote) for individual properties when the
+ * embeddable is embedded in an entity.
+ *
+ * <p>This is particularly useful when:
+ *
+ * <ul>
+ *   <li>The same embeddable type is used multiple times in an entity and requires different column
+ *       names to avoid conflicts
+ *   <li>The column names in the database don't match the default naming conventions
+ *   <li>You need to control the behavior of specific columns (e.g., making them read-only)
+ * </ul>
+ *
+ * <pre>
+ * &#064;Embeddable
+ * public class Address {
+ *     String street;
+ *     String city;
+ *     String zipCode;
+ * }
+ *
+ * &#064;Entity
+ * public class Employee {
+ *     &#064;Id
+ *     Integer id;
+ *
+ *     &#064;Embedded(columnOverrides = {
+ *         &#064;ColumnOverride(name = "street", column = &#064;Column(name = "HOME_STREET")),
+ *         &#064;ColumnOverride(name = "city", column = &#064;Column(name = "HOME_CITY")),
+ *         &#064;ColumnOverride(name = "zipCode", column = &#064;Column(name = "HOME_ZIP"))
+ *     })
+ *     Address homeAddress;
+ *
+ *     &#064;Embedded(columnOverrides = {
+ *         &#064;ColumnOverride(name = "street", column = &#064;Column(name = "WORK_STREET")),
+ *         &#064;ColumnOverride(name = "city", column = &#064;Column(name = "WORK_CITY")),
+ *         &#064;ColumnOverride(name = "zipCode", column = &#064;Column(name = "WORK_ZIP"))
+ *     })
+ *     Address workAddress;
+ * }
+ * </pre>
+ *
+ * @see Embedded
+ * @see Column
+ * @see Embeddable
+ */
+public @interface ColumnOverride {
+  /**
+   * The name of the property in the embeddable class whose column mapping should be overridden.
+   *
+   * <p>This must match exactly the name of a field in the embeddable class.
+   *
+   * @return the property name in the embeddable class
+   */
+  String name();
+
+  /**
+   * The column definition that overrides the default column mapping for the specified property.
+   *
+   * <p>This allows you to specify a custom column name and control column attributes such as
+   * insertable, updatable, and quote.
+   *
+   * @return the column definition to use for the property
+   */
+  Column column();
+}

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

@@ -29,6 +29,8 @@
  * <p>The {@link Embedded} annotation allows for embedding value objects within entities, enabling
  * composition of entities from smaller, reusable components.
  *
+ * <h3>Basic Usage</h3>
+ *
  * <pre>
  * &#064;Embeddable
  * public class Address {
@@ -39,19 +41,58 @@
  *
  * &#064;Entity
  * public class Employee {
- *
  *     &#064;Id
  *     Integer id;
  *
  *     String name;
  *
  *     &#064;Embedded
  *     Address address;
+ * }
+ * </pre>
+ *
+ * <h3>Using Prefix</h3>
+ *
+ * <pre>
+ * &#064;Entity
+ * public class Person {
+ *     &#064;Id
+ *     Integer id;
  *
  *     &#064;Embedded(prefix = "home_")
  *     Address homeAddress;
+ *
+ *     &#064;Embedded(prefix = "work_")
+ *     Address workAddress;
+ * }
+ * </pre>
+ *
+ * <h3>Using Column Overrides</h3>
+ *
+ * <pre>
+ * &#064;Entity
+ * public class Customer {
+ *     &#064;Id
+ *     Integer id;
+ *
+ *     &#064;Embedded(columnOverrides = {
+ *         &#064;ColumnOverride(name = "street", column = &#064;Column(name = "BILLING_STREET")),
+ *         &#064;ColumnOverride(name = "city", column = &#064;Column(name = "BILLING_CITY")),
+ *         &#064;ColumnOverride(name = "zipCode", column = &#064;Column(name = "BILLING_ZIP"))
+ *     })
+ *     Address billingAddress;
+ *
+ *     &#064;Embedded(columnOverrides = {
+ *         &#064;ColumnOverride(name = "street", column = &#064;Column(name = "SHIPPING_STREET")),
+ *         &#064;ColumnOverride(name = "city", column = &#064;Column(name = "SHIPPING_CITY")),
+ *         &#064;ColumnOverride(name = "zipCode", column = &#064;Column(name = "SHIPPING_ZIP", updatable = false))
+ *     })
+ *     Address shippingAddress;
  * }
  * </pre>
+ *
+ * @see Embeddable
+ * @see ColumnOverride
  */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
@@ -71,4 +112,30 @@
    * @return the column name prefix
    */
   String prefix() default "";
+
+  /**
+   * Column overrides for specific properties within the embedded object.
+   *
+   * <p>This allows fine-grained control over the column mappings of individual properties in the
+   * embeddable. Each {@link ColumnOverride} specifies a property name and its corresponding column
+   * definition, which overrides the default column mapping for that property.
+   *
+   * <p>Column overrides are particularly useful when:
+   *
+   * <ul>
+   *   <li>You need to map properties to columns with names that don't follow the standard naming
+   *       convention
+   *   <li>You want to control column attributes (insertable, updatable, quote) for specific
+   *       properties
+   *   <li>Different instances of the same embeddable require different column configurations
+   * </ul>
+   *
+   * <p>Note that column overrides take precedence over the {@link #prefix()} attribute. If both are
+   * specified, the column override will be used for the specified properties, while the prefix will
+   * be applied to all other properties.
+   *
+   * @return an array of column overrides for properties in the embedded object
+   * @see ColumnOverride
+   */
+  ColumnOverride[] columnOverrides() default {};
 }

doma-core/src/main/java/org/seasar/doma/jdbc/entity/ColumnType.java

@@ -0,0 +1,36 @@
+/*
+ * 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.entity;
+
+/**
+ * Represents the metadata for a database column.
+ *
+ * <p>This record encapsulates the configuration of a column in a database table, including its name
+ * and behavioral attributes. It is used internally by the Doma framework to manage column mappings
+ * and SQL generation.
+ *
+ * <p>The column type information is typically derived from {@link org.seasar.doma.Column}
+ * annotations or {@link org.seasar.doma.ColumnOverride} configurations, and is used to control how
+ * entity properties are mapped to database columns.
+ *
+ * @param name the column name in the database
+ * @param insertable whether the column should be included in SQL INSERT statements
+ * @param updatable whether the column should be included in SQL UPDATE statements
+ * @param quote whether the column name should be enclosed by quotation marks in SQL statements
+ * @see org.seasar.doma.Column
+ * @see org.seasar.doma.ColumnOverride
+ */
+public record ColumnType(String name, Boolean insertable, Boolean updatable, Boolean quote) {}

doma-core/src/main/java/org/seasar/doma/jdbc/entity/DefaultPropertyType.java

@@ -62,7 +62,9 @@ public class DefaultPropertyType<ENTITY, BASIC, CONTAINER>
 
   protected final PropertyField<ENTITY> field;
 
-  protected final String columnNamePrefix;
+  protected final String prefix;
+
+  protected final ColumnType columnType;
 
   public DefaultPropertyType(
       Class<ENTITY> entityClass,
@@ -82,7 +84,7 @@ public DefaultPropertyType(
         insertable,
         updatable,
         quoteRequired,
-        "");
+        null);
   }
 
   public DefaultPropertyType(
@@ -94,7 +96,7 @@ public DefaultPropertyType(
       boolean insertable,
       boolean updatable,
       boolean quoteRequired,
-      String columnNamePrefix) {
+      EmbeddedType embeddedType) {
     if (entityClass == null) {
       throw new DomaNullPointerException("entityClass");
     }
@@ -107,21 +109,31 @@ public DefaultPropertyType(
     if (columnName == null) {
       throw new DomaNullPointerException("columnName");
     }
-    if (columnNamePrefix == null) {
-      throw new DomaNullPointerException("columnNamePrefix");
-    }
     this.entityClass = entityClass;
     this.scalarSupplier = scalarSupplier;
     this.name = name;
     int pos = name.lastIndexOf('.');
     this.simpleName = pos > -1 ? name.substring(pos + 1) : name;
-    this.columnName = columnName;
     this.namingType = namingType;
-    this.insertable = insertable;
-    this.updatable = updatable;
-    this.quoteRequired = quoteRequired;
+    if (embeddedType == null) {
+      this.prefix = "";
+      columnType = null;
+    } else {
+      this.prefix = embeddedType.prefix();
+      columnType = embeddedType.columnTypeMap().get(simpleName);
+    }
+    if (columnType == null) {
+      this.columnName = columnName;
+      this.insertable = insertable;
+      this.updatable = updatable;
+      this.quoteRequired = quoteRequired;
+    } else {
+      this.columnName = columnType.name() != null ? columnType.name() : columnName;
+      this.insertable = columnType.insertable() != null ? columnType.insertable() : insertable;
+      this.updatable = columnType.updatable() != null ? columnType.updatable() : updatable;
+      this.quoteRequired = columnType.quote() != null ? columnType.quote() : quoteRequired;
+    }
     this.field = new PropertyField<>(name, entityClass);
-    this.columnNamePrefix = columnNamePrefix;
   }
 
   @Override
@@ -164,9 +176,14 @@ public String getColumnName(
       Function<String, String> quoteFunction) {
     String columnName;
     if (this.columnName.isEmpty()) {
-      columnName = columnNamePrefix + namingFunction.apply(namingType, simpleName);
+      columnName = prefix + namingFunction.apply(namingType, simpleName);
     } else {
-      columnName = columnNamePrefix + this.columnName;
+      if (columnType != null) {
+        // column overrides take precedence over the prefix attribute
+        columnName = this.columnName;
+      } else {
+        columnName = prefix + this.columnName;
+      }
     }
     return quoteRequired ? quoteFunction.apply(columnName) : columnName;
   }

doma-core/src/main/java/org/seasar/doma/jdbc/entity/EmbeddableType.java

@@ -15,6 +15,7 @@
  */
 package org.seasar.doma.jdbc.entity;
 
+import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
@@ -50,7 +51,11 @@ public interface EmbeddableType<EMBEDDABLE> {
   @Deprecated
   default <ENTITY> List<EntityPropertyType<ENTITY, ?>> getEmbeddablePropertyTypes(
       String embeddedPropertyName, Class<ENTITY> entityClass, NamingType namingType) {
-    return getEmbeddablePropertyTypes(embeddedPropertyName, entityClass, namingType, "");
+    return getEmbeddablePropertyTypes(
+        embeddedPropertyName,
+        entityClass,
+        namingType,
+        new EmbeddedType("", Collections.emptyMap()));
   }
 
   /**
@@ -67,14 +72,14 @@ public interface EmbeddableType<EMBEDDABLE> {
    * @param embeddedPropertyName the name of the property in the entity that holds the embeddable
    * @param entityClass the entity class
    * @param namingType the naming convention used for column names
-   * @param columNamePrefix the prefix to be prepended to column names of all embeddable properties
+   * @param embeddedType the embedded type metadata containing column prefix and column overrides
    * @return a list of entity property types for the embeddable properties
    */
   <ENTITY> List<EntityPropertyType<ENTITY, ?>> getEmbeddablePropertyTypes(
       String embeddedPropertyName,
       Class<ENTITY> entityClass,
       NamingType namingType,
-      String columNamePrefix);
+      EmbeddedType embeddedType);
 
   /**
    * Creates a new instance of the embeddable object.