feat: implement @Embedded annotation with column name prefix support (#1384)

* feat: implement @Embedded annotation with column name prefix support

This comprehensive feature enables embedding value objects within entities
with customizable column name prefixes, allowing the same embeddable type
to be used multiple times in a single entity with different column naming.

## Core Features Implemented

### @Embedded Annotation
- New @Embedded annotation with prefix attribute for column name prefixing
- Comprehensive JavaDoc documentation with usage examples
- Proper annotation meta-annotations (@target, @retention, @EntityField)

### Column Name Prefix Support
- Extended DefaultPropertyType to support columnNamePrefix parameter
- Updated EmbeddableType interface with new getEmbeddablePropertyTypes method
- Backward compatibility maintained with deprecated method delegation

### Annotation Processor Integration
- New EmbeddedAnnot class for annotation processing
- Enhanced EntityPropertyMetaFactory to handle @Embedded annotations
- Updated code generation to pass column prefixes to property types
- Proper error handling for invalid @Embedded usage (DOMA4498)

### Comprehensive Test Coverage
- Unit tests for DefaultPropertyType.columnNamePrefix functionality
- Integration tests with Customer/CustomerAddress entities
- Processor tests for annotation validation and code generation
- Database compatibility tests across all supported databases

### Database Integration
- Customer entity with embedded billing and shipping addresses
- CustomerDao interface with insert/select operations
- Complete SQL scripts for all supported databases (H2, MySQL, PostgreSQL,
  Oracle, SQLite, SQL Server, DB2, HSQLDB)
- Integration test suite demonstrating real-world usage

## Technical Implementation

### Type System Integration
- Enhanced EmbeddableTypeGenerator for prefix parameter passing
- Updated EntityTypePropertyGenerator for embedded property creation
- Seamless integration with existing entity/embeddable architecture

### Backward Compatibility
- Existing @embeddable classes work without modification
- Default empty prefix maintains current behavior
- Deprecated methods provide smooth migration path

## Usage Example

```java
@embeddable
public record Address(String street, String city, String zipCode) {}

@entity
public class Customer {
    @id Integer customerId;

    @Embedded(prefix = "billing_")
    Address billingAddress;

    @Embedded(prefix = "shipping_")
    Address shippingAddress;
}
```

This creates columns: billing_street, billing_city, billing_zip_code,
shipping_street, shipping_city, shipping_zip_code.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* feat: add CUSTOMER table to SQLite script for integration tests

---------

Co-authored-by: Claude <[email protected]>

Author: nakamura-to

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

@@ -0,0 +1,74 @@
+/*
+ * 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;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates an embedded property.
+ *
+ * <p>The annotated field must be a member of an {@link Entity} annotated class. The type of the
+ * field must be a class annotated with {@link Embeddable}.
+ *
+ * <p>The {@link Embedded} annotation allows for embedding value objects within entities, enabling
+ * composition of entities from smaller, reusable components.
+ *
+ * <pre>
+ * &#064;Embeddable
+ * public class Address {
+ *     String street;
+ *     String city;
+ *     String zipCode;
+ * }
+ *
+ * &#064;Entity
+ * public class Employee {
+ *
+ *     &#064;Id
+ *     Integer id;
+ *
+ *     String name;
+ *
+ *     &#064;Embedded
+ *     Address address;
+ *
+ *     &#064;Embedded(prefix = "home_")
+ *     Address homeAddress;
+ * }
+ * </pre>
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+@EntityField
+public @interface Embedded {
+
+  /**
+   * The prefix for column names of the embedded properties.
+   *
+   * <p>When specified, the prefix is prepended to the column names of all properties within the
+   * embedded object. This is useful when embedding the same embeddable type multiple times in an
+   * entity.
+   *
+   * <p>For example, if an embeddable has a property mapped to column "street" and the prefix is
+   * "home_", the resulting column name will be "home_street".
+   *
+   * @return the column name prefix
+   */
+  String prefix() default "";
+}

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

@@ -62,6 +62,8 @@ public class DefaultPropertyType<ENTITY, BASIC, CONTAINER>
 
   protected final PropertyField<ENTITY> field;
 
+  protected final String columnNamePrefix;
+
   public DefaultPropertyType(
       Class<ENTITY> entityClass,
       Supplier<Scalar<BASIC, CONTAINER>> scalarSupplier,
@@ -71,6 +73,28 @@ public DefaultPropertyType(
       boolean insertable,
       boolean updatable,
       boolean quoteRequired) {
+    this(
+        entityClass,
+        scalarSupplier,
+        name,
+        columnName,
+        namingType,
+        insertable,
+        updatable,
+        quoteRequired,
+        "");
+  }
+
+  public DefaultPropertyType(
+      Class<ENTITY> entityClass,
+      Supplier<Scalar<BASIC, CONTAINER>> scalarSupplier,
+      String name,
+      String columnName,
+      NamingType namingType,
+      boolean insertable,
+      boolean updatable,
+      boolean quoteRequired,
+      String columnNamePrefix) {
     if (entityClass == null) {
       throw new DomaNullPointerException("entityClass");
     }
@@ -83,6 +107,9 @@ 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;
@@ -94,6 +121,7 @@ public DefaultPropertyType(
     this.updatable = updatable;
     this.quoteRequired = quoteRequired;
     this.field = new PropertyField<>(name, entityClass);
+    this.columnNamePrefix = columnNamePrefix;
   }
 
   @Override
@@ -134,9 +162,11 @@ public String getColumnName(BiFunction<NamingType, String, String> namingFunctio
   public String getColumnName(
       BiFunction<NamingType, String, String> namingFunction,
       Function<String, String> quoteFunction) {
-    String columnName = this.columnName;
-    if (columnName.isEmpty()) {
-      columnName = namingFunction.apply(namingType, simpleName);
+    String columnName;
+    if (this.columnName.isEmpty()) {
+      columnName = columnNamePrefix + namingFunction.apply(namingType, simpleName);
+    } else {
+      columnName = columnNamePrefix + this.columnName;
     }
     return quoteRequired ? quoteFunction.apply(columnName) : columnName;
   }

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

@@ -47,8 +47,34 @@ public interface EmbeddableType<EMBEDDABLE> {
    * @param namingType the naming convention used for column names
    * @return a list of entity property types for the embeddable properties
    */
+  @Deprecated
+  default <ENTITY> List<EntityPropertyType<ENTITY, ?>> getEmbeddablePropertyTypes(
+      String embeddedPropertyName, Class<ENTITY> entityClass, NamingType namingType) {
+    return getEmbeddablePropertyTypes(embeddedPropertyName, entityClass, namingType, "");
+  }
+
+  /**
+   * Returns a list of entity property types for the embeddable properties with a column name
+   * prefix.
+   *
+   * <p>This method is used to obtain metadata about the properties within an embeddable object when
+   * it is embedded in an entity. The property types are used for mapping between the embeddable
+   * object's properties and database columns. The column name prefix is applied to all column names
+   * of the embeddable properties, which is useful when the same embeddable type is used multiple
+   * times within an entity.
+   *
+   * @param <ENTITY> the entity type that contains the 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
+   * @return a list of entity property types for the embeddable properties
+   */
   <ENTITY> List<EntityPropertyType<ENTITY, ?>> getEmbeddablePropertyTypes(
-      String embeddedPropertyName, Class<ENTITY> entityClass, NamingType namingType);
+      String embeddedPropertyName,
+      Class<ENTITY> entityClass,
+      NamingType namingType,
+      String columNamePrefix);
 
   /**
    * Creates a new instance of the embeddable object.

doma-core/src/main/java/org/seasar/doma/message/Message.java

@@ -1017,6 +1017,8 @@ public enum Message implements MessageResource {
   DOMA4496(
       "When \"returning = @Returning\" is specified, the return type must be a List of the entity class \"{0}\"."),
   DOMA4497("The {0} type parameter of BiConsumer must be an entity class."),
+  DOMA4498(
+      "You cannot annotate the field with @Embedded if the field type is not an embeddable class."),
 
   // other
   DOMA5001(

doma-core/src/test/java/org/seasar/doma/jdbc/entity/DefaultPropertyTypeTest.java

@@ -235,6 +235,135 @@ public void testWrapperPropertyDefaultValue() {
     assertNull(property.get());
   }
 
+  @Test
+  public void testColumnNamePrefix_columnDefined() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "foo",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            false,
+            "prefix_");
+    assertEquals("prefix_foo", propertyType.getColumnName());
+  }
+
+  @Test
+  public void testColumnNamePrefix_columnNotDefined() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            false,
+            "prefix_");
+    assertEquals("prefix_HOGE", propertyType.getColumnName());
+  }
+
+  @Test
+  public void testColumnNamePrefix_emptyString() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "foo",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            false,
+            "");
+    assertEquals("foo", propertyType.getColumnName());
+  }
+
+  @Test
+  public void testColumnNamePrefix_quoteRequired() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "foo",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            true,
+            "prefix_");
+    assertEquals("[prefix_foo]", propertyType.getColumnName(text -> "[" + text + "]"));
+  }
+
+  @Test
+  public void testColumnNamePrefix_quoteNotRequired() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "foo",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            false,
+            "prefix_");
+    assertEquals("prefix_foo", propertyType.getColumnName(text -> "[" + text + "]"));
+  }
+
+  @Test
+  public void testColumnNamePrefix_embeddableProperty() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "foo.hoge",
+            "",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            false,
+            "prefix_");
+    assertEquals("prefix_HOGE", propertyType.getColumnName());
+  }
+
+  @Test
+  public void testColumnNamePrefix_namingFunction() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            false,
+            "prefix_");
+    assertEquals("prefix_HOGE", propertyType.getColumnName(NamingType::apply));
+  }
+
+  @Test
+  public void testColumnNamePrefix_namingAndQuoteFunction() {
+    DefaultPropertyType<DefaultPropertyTypeTest, String, String> propertyType =
+        new DefaultPropertyType<>(
+            DefaultPropertyTypeTest.class,
+            () -> new BasicScalar<>(StringWrapper::new),
+            "hoge",
+            "",
+            NamingType.UPPER_CASE,
+            true,
+            true,
+            true,
+            "prefix_");
+    assertEquals(
+        "[prefix_HOGE]", propertyType.getColumnName(NamingType::apply, text -> "[" + text + "]"));
+  }
+
   public static class Foo {
     String hoge;
   }

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

@@ -38,6 +38,7 @@
 import org.seasar.doma.Domain;
 import org.seasar.doma.DomainConverters;
 import org.seasar.doma.Embeddable;
+import org.seasar.doma.Embedded;
 import org.seasar.doma.Entity;
 import org.seasar.doma.ResultSet;
 import org.seasar.doma.SequenceGenerator;
@@ -274,6 +275,15 @@ public EmbeddableAnnot newEmbeddableAnnot(TypeElement typeElement) {
     return new EmbeddableAnnot(embeddableMirror, metamodelAnnot);
   }
 
+  /**
+   * @param field non-null
+   * @return nullable
+   */
+  public EmbeddedAnnot newEmbeddedAnnot(VariableElement field) {
+    assertNotNull(field);
+    return newInstance(field, Embedded.class, EmbeddedAnnot::new);
+  }
+
   /**
    * @param typeElement non-null
    * @return nullable

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

@@ -0,0 +1,48 @@
+/*
+ * 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.Map;
+import javax.lang.model.element.AnnotationMirror;
+import javax.lang.model.element.AnnotationValue;
+import org.seasar.doma.internal.apt.AptIllegalStateException;
+import org.seasar.doma.internal.apt.util.AnnotationValueUtil;
+
+public class EmbeddedAnnot extends AbstractAnnot {
+
+  public static final String PREFIX = "prefix";
+
+  private final AnnotationValue prefix;
+
+  EmbeddedAnnot(AnnotationMirror annotationMirror, Map<String, AnnotationValue> values) {
+    super(annotationMirror);
+    this.prefix = assertNonNullValue(values, PREFIX);
+  }
+
+  public AnnotationValue getPrefix() {
+    return prefix;
+  }
+
+  public String getPrefixValue() {
+    String value = AnnotationValueUtil.toString(prefix);
+    if (value == null) {
+      throw new AptIllegalStateException(PREFIX);
+    }
+    return value;
+  }
+}