HHH-4396 - Ability to patternize embedded column names

Author: sebersole

documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc

@@ -134,6 +134,68 @@ include::{extrasdir}/embeddable/embeddable-type-override-mapping-example.sql[]
 ----
 ====
 
+[[embeddable-column-naming]]
+==== @EmbeddedColumnNaming
+
+The most common use case for `@AttributeOverride` in relation to an embeddable is to rename the associated columns.
+
+Consider a typical embeddable mapping -
+
+[[embeddable-column-naming-example-model]]
+.Typical embeddable mapping
+====
+[source,java]
+----
+@Embeddable
+class Address {
+	String street;
+	String city;
+	// ...
+}
+
+@Entity
+class Person {
+	// ...
+    @Embedded
+    Address homeAddress;
+    @Embedded
+    Address workAddress;
+}
+----
+====
+
+In strict Jakarta Persistence sense, this will lead to a bootstrapping error because
+Jakarta Persistence requires that the implicit names for all of the columns for these
+both of the embedded `Address` mappings to be based on the attribute names from the embeddable -
+here, `street`, `city`, etc.  However, that will lead to duplicate column names here.
+
+The strict compliance way to accomplish this would be a tedious use of the `@AttributeOverride` annotation
+as <<embeddable-override,discussed previously>>.
+
+Since this is such a common pattern, Hibernate offers a much simpler solution through its `@EmbeddedColumnNaming` annotation
+which allows to "patternize" the column naming -
+
+[[embeddable-column-naming-example-basic]]
+.@EmbeddedColumnNaming example
+====
+[source,java]
+----
+@Entity
+class Person {
+	// ...
+    @Embedded
+    @EmbeddedColumnNaming("home_%s")
+    Address homeAddress;
+    @Embedded
+    @EmbeddedColumnNaming("work_%s")
+    Address workAddress;
+}
+----
+====
+
+Here we'd end up with implicit column names `home_street`, `home_city`, `work_street`, `work_city`, etc.
+
+
 
 [[embeddable-collections]]
 ==== Collections of embeddable types

documentation/src/main/asciidoc/userguide/chapters/domain/naming.adoc

@@ -65,6 +65,12 @@ to specify the ImplicitNamingStrategy to use.  See
 <<chapters/bootstrap/Bootstrap.adoc#bootstrap,Bootstrap>> for additional details on bootstrapping.
 
 
+[NOTE]
+.@EmbeddedColumnNaming
+====
+A related topic is the use of `@EmbeddedColumnNaming` to help with the implicit naming of columns associated with mapping an embeddable.
+See <<bnb,the disucussion>>
+====
 
 [[PhysicalNamingStrategy]]
 ==== PhysicalNamingStrategy

hibernate-core/src/main/java/org/hibernate/annotations/EmbeddedColumnNaming.java

@@ -30,6 +30,10 @@
 	/**
 	 * The naming pattern.  It is expected to contain a single pattern marker ({@code %})
 	 * into which the "raw" column name will be injected.
+	 * <p/>
+	 * The {@code value} may be omitted which will indicate to use the pattern
+	 * {@code "{ATTRIBUTE_NAME}_%s"} where {@code {ATTRIBUTE_NAME}} is the name of the attribute
+	 * where the annotation is placed.
 	 */
-	String value();
+	String value() default "";
 }

hibernate-core/src/main/java/org/hibernate/boot/model/internal/EmbeddableBinder.java

@@ -32,6 +32,7 @@
 import org.hibernate.boot.spi.PropertyData;
 import org.hibernate.internal.CoreMessageLogger;
 import org.hibernate.internal.util.MutableInteger;
+import org.hibernate.internal.util.NullnessHelper;
 import org.hibernate.internal.util.StringHelper;
 import org.hibernate.mapping.BasicValue;
 import org.hibernate.mapping.Component;
@@ -1019,7 +1020,11 @@ private static void applyColumnNamingPattern(Component component, PropertyData i
 			return;
 		}
 
-		final String columnNamingPattern = columnNaming.value();
+		final String columnNamingPattern = NullnessHelper.coalesce(
+				columnNaming.value(),
+				inferredData.getPropertyName() + "_%s"
+		);
+
 		final int markerCount = StringHelper.count( columnNamingPattern, '%' );
 		if ( markerCount != 1 ) {
 			throw new MappingException( String.format(

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/EmbeddedColumnNamingAnnotation.java

@@ -1,5 +1,5 @@
 /*
- * SPDX-License-Identifier: Apache-2.0
+ * SPDX-License-Identifier: LGPL-2.1-or-later
  * Copyright Red Hat Inc. and Hibernate Authors
  */
 package org.hibernate.boot.models.annotations.internal;

hibernate-core/src/test/java/org/hibernate/orm/test/embeddable/EmbeddedColumnNamingImplicitTests.java

@@ -0,0 +1,62 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.orm.test.embeddable;
+
+import jakarta.persistence.Embeddable;
+import jakarta.persistence.Embedded;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import org.hibernate.annotations.EmbeddedColumnNaming;
+import org.hibernate.engine.spi.SessionFactoryImplementor;
+import org.hibernate.metamodel.spi.MappingMetamodelImplementor;
+import org.hibernate.persister.entity.EntityPersister;
+import org.hibernate.testing.orm.junit.DomainModel;
+import org.hibernate.testing.orm.junit.SessionFactory;
+import org.hibernate.testing.orm.junit.SessionFactoryScope;
+import org.junit.jupiter.api.Test;
+
+import static org.hibernate.orm.test.embeddable.EmbeddedColumnNamingTests.verifyColumnNames;
+
+/**
+ * @author Steve Ebersole
+ */
+@SuppressWarnings("JUnitMalformedDeclaration")
+public class EmbeddedColumnNamingImplicitTests {
+	@Test
+	@DomainModel( annotatedClasses = {Person.class, Address.class} )
+	@SessionFactory(exportSchema = false)
+	void testNaming(SessionFactoryScope factoryScope) {
+		final SessionFactoryImplementor sessionFactory = factoryScope.getSessionFactory();
+		final MappingMetamodelImplementor mappingMetamodel = sessionFactory.getMappingMetamodel();
+		final EntityPersister persister = mappingMetamodel.getEntityDescriptor( Person.class );
+		verifyColumnNames( persister.findAttributeMapping( "homeAddress" ), "homeAddress_" );
+		verifyColumnNames( persister.findAttributeMapping( "workAddress" ), "workAddress_" );
+	}
+
+	@Entity(name="Person")
+	@Table(name="person")
+	public static class Person {
+		@Id
+		private Integer id;
+		private String name;
+
+		@Embedded
+		@EmbeddedColumnNaming
+		private Address homeAddress;
+
+		@Embedded
+		@EmbeddedColumnNaming
+		private Address workAddress;
+	}
+
+	@Embeddable
+	public static class Address {
+		private String street;
+		private String city;
+		private String state;
+		private String zip;
+	}
+}

hibernate-core/src/test/java/org/hibernate/orm/test/embeddable/EmbeddedColumnNamingMixedTests.java

@@ -27,6 +27,8 @@
 import static org.junit.jupiter.api.Assertions.fail;
 
 /**
+ * Tests how {@code @EmbeddedColumnNaming} and {@code @Column} work together.
+ *
  * @author Steve Ebersole
  */
 @SuppressWarnings("JUnitMalformedDeclaration")