HHH-4396 - Ability to patternize embedded column names

Author: sebersole

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

@@ -134,6 +134,147 @@ 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]
+----
+@Entity
+class Person {
+	// ...
+    @Embedded
+    Address homeAddress;
+    @Embedded
+    Address workAddress;
+}
+
+@Embeddable
+class Address {
+	String street;
+	String city;
+	// ...
+}
+----
+====
+
+In strict Jakarta Persistence sense, this will lead to a bootstrapping error because
+Jakarta Persistence requires that the implicit names for the columns for both of the
+embedded `Address` mappings to be based on the attribute names from the embeddable -
+`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]]
+.Simple `@EmbeddedColumnNaming` example
+====
+[source,java]
+----
+@Entity
+class Person {
+	// ...
+    @Embedded
+    @EmbeddedColumnNaming("home_%s")
+    Address homeAddress;
+    @Embedded
+    @EmbeddedColumnNaming("work_%s")
+    Address workAddress;
+}
+----
+====
+
+This mapping produces implicit column names `home_street`, `home_city`, `work_street`, `work_city`, etc.
+
+`@EmbeddedColumnNaming` also works in nested usages and plays nicely with explicit column names.
+
+[[embeddable-column-naming-example-column]]
+.Explicit @Column example
+====
+[source,java]
+----
+@Entity
+class Person {
+	// ...
+    @Embedded
+	@EmbeddedColumnNaming("home_%s")
+    Address homeAddress;
+    @Embedded
+    @EmbeddedColumnNaming("work_%s")
+    Address workAddress;
+}
+
+@Embeddable
+class Address {
+	String street;
+	String city;
+    @Embedded
+    private ZipPlus zip;
+	// ...
+}
+
+@Embeddable
+public static class ZipPlus {
+    @Column(name="zip_code")
+    private String code;
+    @Column(name="zip_plus4")
+    private String plus4;
+}
+----
+====
+
+This will produce implicit column names `home_street`, `home_city`, `home_zip_code`, `home_zip_plus4`, ...
+
+
+When `@EmbeddedColumnNaming` is used withing nested embeddables, the affect will be cumulative.
+Given the following model:
+
+[[embeddable-column-naming-example-cumulative]]
+.Cumulative @EmbeddedColumnNaming example
+====
+[source,java]
+----
+@Entity
+class Person {
+	// ...
+    @Embedded
+	@EmbeddedColumnNaming("home_%s")
+    Address homeAddress;
+    @Embedded
+    @EmbeddedColumnNaming("work_%s")
+    Address workAddress;
+}
+
+@Embeddable
+class Address {
+	String street;
+	String city;
+    @Embedded
+    @EmbeddedColumnNaming("zip_%s")
+    private ZipPlus zip;
+	// ...
+}
+
+@Embeddable
+public static class ZipPlus {
+    private String code;
+    private String plus4;
+}
+----
+====
+
+Here we will end up with the columns `home_street`, `home_city`, `home_zip_code`, `home_zip_plus4`, ...
+
+
 
 [[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

@@ -1,11 +1,11 @@
 /*
- * Hibernate, Relational Persistence for Idiomatic Java
- *
- * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
- * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html.
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
  */
 package org.hibernate.annotations;
 
+import org.hibernate.Incubating;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -16,17 +16,67 @@
 /**
  * Allows specifying a pattern to be applied to the naming of columns for
  * a particular {@linkplain jakarta.persistence.Embedded embedded mapping}.
+ * For example, given a typical embeddable named {@code Address} and
+ * {@code @EmbeddedColumnNaming("home_%s)}, we will get columns named
+ * {@code home_street}, {@code home_city}, etc.
+ * <p/>
+ * Explicit {@linkplain jakarta.persistence.Column @Column(name)} mappings are incorporated
+ * into the result.  When embeddables are nested, the affect will be cumulative.  Given the following model:
+ *
+ * <pre>
+ * &#64;Entity
+ * class Person {
+ *     ...
+ *     &#64;Embedded
+ *     &#64;EmbeddedColumnNaming("home_%s")
+ *     Address homeAddress;
+ *     &#64;Embedded
+ *     &#64;EmbeddedColumnNaming("work_%s")
+ *     Address workAddress;
+ * }
+ *
+ * &#64;Embeddable
+ * class Address {
+ *     &#64;Column(name="line1")
+ *     String street;
+ *     ...
+ *     &#64;Embedded
+ *     &#64;EmbeddedColumnNaming("zip_%s")
+ *     ZipPlus4 zip;
+ * }
+ *
+ * &#64;Embeddable
+ * class ZipPlus4 {
+ *    &#64;Column(name="zip_code")
+ *    String zipCode;
+ *    &#64;Column(name="plus_code")
+ *     String plusCode;
+ * }
+ * </pre>
+ * Will result in the following columns:<ol>
+ *     <li>{@code home_line1}</li>
+ *     <li>{@code home_zip_zip_code}</li>
+ *     <li>{@code home_zip_plus_code}</li>
+ *     <li>{@code work_line1}</li>
+ *     <li>{@code work_zip_zip_code}</li>
+ *     <li>{@code work_zip_plus_code}</li>
+ * </ol>
  *
+ * @since 7.0
  * @author Steve Ebersole
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
+@Incubating
 public @interface EmbeddedColumnNaming {
 	/**
 	 * The naming pattern.  It is expected to contain a single pattern marker ({@code %})
-	 * into which the "raw" column name will be injected.  E.g., given a typical {@code Address}
-	 * embeddable and {@code @Embedded @EmbeddedColumnNaming("home_%s)}, we will get columns named
-	 * {@code home_street}, {@code home_city}, etc.
+	 * 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 - e.g. {@code @Embedded @EmbeddedColumnNaming Address homeAddress}
+	 * would create columns {@code homeAddress_street}, {@code homeAddress_city}, etc.
 	 */
-	String value();
+	String value() default "";
 }

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

@@ -342,18 +342,61 @@ public boolean isNameDeferred() {
 	}
 
 	public void redefineColumnName(String columnName, String propertyName, boolean applyNamingStrategy) {
-		if ( isNotEmpty( columnName ) ) {
-			mappingColumn.setName( processColumnName( columnName, applyNamingStrategy ) );
+		if ( StringHelper.isEmpty( columnName ) && StringHelper.isEmpty( propertyName ) ) {
+			// nothing to do
+			return;
+		}
+		final String logicalColumnName = resolveLogicalColumnName( columnName, propertyName );
+		mappingColumn.setName( processColumnName( logicalColumnName, applyNamingStrategy ) );
+	}
+
+	private String resolveLogicalColumnName(String columnName, String propertyName) {
+		final String baseColumnName = StringHelper.isNotEmpty( columnName )
+				? columnName
+				: inferColumnName( propertyName );
+
+		if ( parent.getPropertyHolder() != null && parent.getPropertyHolder().isComponent() ) {
+			// see if we need to apply one-or-more @EmbeddedColumnNaming patterns
+			return applyEmbeddedColumnNaming( baseColumnName, (ComponentPropertyHolder) parent.getPropertyHolder() );
 		}
 		else {
-			if ( propertyName != null && applyNamingStrategy ) {
-				mappingColumn.setName( inferColumnName( propertyName ) );
+			return baseColumnName;
+		}
+	}
+
+	private String applyEmbeddedColumnNaming(String inferredColumnName, ComponentPropertyHolder propertyHolder) {
+		// code
+		String result = inferredColumnName;
+		boolean appliedAnyPatterns = false;
+
+		final String columnNamingPattern = propertyHolder.getComponent().getColumnNamingPattern();
+		if ( StringHelper.isNotEmpty( columnNamingPattern ) ) {
+			// zip_code
+			result = String.format( columnNamingPattern, result );
+			appliedAnyPatterns = true;
+		}
+
+		ComponentPropertyHolder tester = propertyHolder;
+		while ( tester.parent.isComponent() ) {
+			final ComponentPropertyHolder parentHolder = (ComponentPropertyHolder) tester.parent;
+			final String parentColumnNamingPattern = parentHolder.getComponent().getColumnNamingPattern();
+			if ( StringHelper.isNotEmpty( parentColumnNamingPattern ) ) {
+				// 	home_zip_code
+				result = String.format( parentColumnNamingPattern, result );
+				appliedAnyPatterns = true;
 			}
-			//Do nothing otherwise
+			tester = parentHolder;
 		}
+
+		if ( appliedAnyPatterns ) {
+			// we need to adjust the logical name to be picked up in `#addColumnBinding`
+			this.logicalColumnName = result;
+		}
+
+		return result;
 	}
 
-	private String processColumnName(String columnName, boolean applyNamingStrategy) {
+	protected String processColumnName(String columnName, boolean applyNamingStrategy) {
 		if ( applyNamingStrategy ) {
 			final Database database = getBuildingContext().getMetadataCollector().getDatabase();
 			return getBuildingContext().getBuildingOptions().getPhysicalNamingStrategy()
@@ -366,7 +409,7 @@ private String processColumnName(String columnName, boolean applyNamingStrategy)
 
 	}
 
-	private String inferColumnName(String propertyName) {
+	protected String inferColumnName(String propertyName) {
 		final Database database = getBuildingContext().getMetadataCollector().getDatabase();
 		final ObjectNameNormalizer normalizer = getBuildingContext().getObjectNameNormalizer();
 		final ImplicitNamingStrategy implicitNamingStrategy = getBuildingContext().getBuildingOptions().getImplicitNamingStrategy();

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

@@ -13,6 +13,7 @@
 import org.hibernate.boot.spi.InFlightMetadataCollector;
 import org.hibernate.boot.spi.MetadataBuildingContext;
 import org.hibernate.boot.spi.PropertyData;
+import org.hibernate.internal.util.StringHelper;
 import org.hibernate.mapping.Column;
 import org.hibernate.mapping.PersistentClass;
 import org.hibernate.mapping.SimpleValue;
@@ -452,7 +453,9 @@ public void overrideFromReferencedColumnIfNecessary(Column column) {
 
 	@Override
 	public void redefineColumnName(String columnName, String propertyName, boolean applyNamingStrategy) {
-		super.redefineColumnName( columnName, null, applyNamingStrategy );
+		if ( StringHelper.isNotEmpty( columnName ) ) {
+			getMappingColumn().setName( processColumnName( columnName, applyNamingStrategy ) );
+		}
 	}
 
 	static AnnotatedJoinColumn buildImplicitJoinTableJoinColumn(

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

@@ -96,6 +96,13 @@ public ComponentPropertyHolder(
 		}
 	}
 
+	/**
+	 * Access to the underlying component
+	 */
+	public Component getComponent() {
+		return component;
+	}
+
 	/**
 	 * This is called from our constructor and handles (in order):<ol>
 	 *     <li>@Convert annotation at the Embeddable class level</li>