HHH-19257 - Introduce @EmbeddedTable

sebersole · sebersole · commit a5dc4134a6bc · 2025-10-03T09:41:01.000-06:00
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddedTable.java b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddedTable.java
@@ -0,0 +1,49 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.annotations;
+
+import org.hibernate.Incubating;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * An easier mechanism to declare the table to which an embedded value
+ * maps compared to the Jakarta Persistence compliant mechanism requiring
+ * multiple {@link jakarta.persistence.AttributeOverride}
+ * and {@link jakarta.persistence.AssociationOverride} annotations.
+ * <pre>
+ *  &#64;Entity
+ *  &#64;Table(name="primary")
+ *  &#64;SecondaryTable(name="secondary")
+ *  class Person {
+ *  	...
+ *  	&#64;Embedded
+ *  	&#64;EmbeddedTable("secondary")
+ *  	Address address;
+ *  }
+ * </pre>
+ *
+ * @apiNote Only supported for an embedded declared on an entity or mapped-superclass; all other (mis)uses
+ * will lead to a {@linkplain org.hibernate.boot.models.AnnotationPlacementException}.
+ *
+ * @see EmbeddedColumnNaming
+ *
+ * @since 7.2
+ * @author Steve Ebersole
+ */
+@Target({METHOD, FIELD})
+@Retention(RUNTIME)
+@Incubating
+public @interface EmbeddedTable {
+	/**
+	 * The name of the table in which the embedded value is stored.
+	 */
+	String value();
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/AbstractPropertyHolder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/AbstractPropertyHolder.java
@@ -53,7 +53,7 @@ public abstract class AbstractPropertyHolder implements PropertyHolder {
 
 	private final String path;
 	protected final AbstractPropertyHolder parent;
-	private final MetadataBuildingContext context;
+	protected final MetadataBuildingContext context;
 
 	private Boolean isInIdClass;
 
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java
@@ -20,6 +20,7 @@
 import org.hibernate.MappingException;
 import org.hibernate.annotations.*;
 import org.hibernate.boot.model.IdentifierGeneratorDefinition;
+import org.hibernate.boot.models.AnnotationPlacementException;
 import org.hibernate.boot.models.JpaAnnotations;
 import org.hibernate.boot.models.annotations.internal.MapKeyColumnJpaAnnotation;
 import org.hibernate.boot.spi.AccessType;
@@ -1052,10 +1053,17 @@ private void setDeclaringClass(ClassDetails declaringClass) {
 	}
 
 	private void bind() {
+		if ( property != null ) {
+			final EmbeddedTable misplaced = property.getDirectAnnotationUsage( EmbeddedTable.class );
+			if ( misplaced != null ) {
+				// not allowed
+				throw new AnnotationPlacementException( "@EmbeddedTable only supported for use on entity or mapped-superclass" );
+			}
+		}
 		collection = createCollection( propertyHolder.getPersistentClass() );
 		final String role = qualify( propertyHolder.getPath(), propertyName );
 		if ( BOOT_LOGGER.isTraceEnabled() ) {
-BOOT_LOGGER.bindingCollectionRole( role );
+			BOOT_LOGGER.bindingCollectionRole( role );
 		}
 		collection.setRole( role );
 		collection.setMappedByProperty( mappedBy );
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java
@@ -9,6 +9,10 @@
 
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.hibernate.AnnotationException;
+import org.hibernate.annotations.EmbeddedTable;
+import org.hibernate.boot.model.naming.Identifier;
+import org.hibernate.boot.models.AnnotationPlacementException;
+import org.hibernate.boot.spi.InFlightMetadataCollector;
 import org.hibernate.boot.spi.MetadataBuildingContext;
 import org.hibernate.boot.spi.PropertyData;
 import org.hibernate.mapping.AggregateColumn;
@@ -83,6 +87,8 @@ public ComponentPropertyHolder(
 		this.component = component;
 		this.inheritanceStatePerClass = inheritanceStatePerClass;
 
+		applyExplicitTableName( component, inferredData, parent, context );
+
 		isOrWithinEmbeddedId = parent.isOrWithinEmbeddedId()
 				|| embeddedMemberDetails != null && hasIdAnnotation( embeddedMemberDetails );
 		isWithinElementCollection = parent.isWithinElementCollection()
@@ -98,6 +104,61 @@ public ComponentPropertyHolder(
 		}
 	}
 
+	/**
+	 * Apply the explicit {@link EmbeddedTable} if there is one and if its
+	 * appropriate for the context (the type of {@code container}).
+	 *
+	 * @param component The (in-flight) component mapping details.
+	 * @param propertyData Details about the property defining this component.
+	 * @param container The container for this component.
+	 */
+	public static void applyExplicitTableName(
+			Component component,
+			PropertyData propertyData,
+			PropertyHolder container,
+			MetadataBuildingContext buildingContext) {
+		Table tableToUse = container.getTable();
+		boolean wasExplicit = false;
+		if ( container instanceof ComponentPropertyHolder componentPropertyHolder ) {
+			wasExplicit = componentPropertyHolder.getComponent().wasTableExplicitlyDefined();
+		}
+
+		if ( propertyData.getAttributeMember() != null ) {
+			final EmbeddedTable embeddedTableAnn = propertyData.getAttributeMember()
+					.getDirectAnnotationUsage( EmbeddedTable.class );
+			// we only allow this when done for an embedded on an entity or mapped-superclass
+			if ( container instanceof ClassPropertyHolder ) {
+				if ( embeddedTableAnn != null ) {
+					final Identifier tableNameIdentifier = buildingContext.getObjectNameNormalizer().normalizeIdentifierQuoting( embeddedTableAnn.value() );
+					final InFlightMetadataCollector.EntityTableXref entityTableXref = buildingContext
+							.getMetadataCollector()
+							.getEntityTableXref( container.getEntityName() );
+					tableToUse =  entityTableXref.resolveTable( tableNameIdentifier );
+					wasExplicit = true;
+				}
+			}
+			else {
+				if ( embeddedTableAnn != null ) {
+					// not allowed
+					throw new AnnotationPlacementException( "@EmbeddedTable only supported for use on entity or mapped-superclass" );
+				}
+			}
+		}
+		if ( propertyData.getAttributeMember() != null && container instanceof ClassPropertyHolder ) {
+			final EmbeddedTable embeddedTableAnn = propertyData.getAttributeMember().getDirectAnnotationUsage( EmbeddedTable.class );
+			if ( embeddedTableAnn != null ) {
+				final Identifier tableNameIdentifier = buildingContext.getObjectNameNormalizer().normalizeIdentifierQuoting( embeddedTableAnn.value() );
+				final InFlightMetadataCollector.EntityTableXref entityTableXref = buildingContext
+						.getMetadataCollector()
+						.getEntityTableXref( container.getEntityName() );
+				tableToUse =  entityTableXref.resolveTable( tableNameIdentifier );
+				wasExplicit = true;
+			}
+		}
+
+		component.setTable( tableToUse, wasExplicit );
+	}
+
 	/**
 	 * Access to the underlying component
 	 */
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/EmbeddableBinder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/EmbeddableBinder.java
@@ -951,16 +951,16 @@ private static String canonicalize(String typeName) {
 	static Component createEmbeddable(
 			PropertyHolder propertyHolder,
 			PropertyData inferredData,
-			boolean isComponentEmbedded,
+			boolean isNonAggregated,
 			boolean isIdentifierMapper,
 			Class<? extends EmbeddableInstantiator> customInstantiatorImpl,
 			MetadataBuildingContext context) {
 		final var embeddable = new Component( context, propertyHolder.getPersistentClass() );
-		embeddable.setEmbedded( isComponentEmbedded );
-		//yuk
-		embeddable.setTable( propertyHolder.getTable() );
+		embeddable.setEmbedded( isNonAggregated );
+		ComponentPropertyHolder.applyExplicitTableName( embeddable, inferredData, propertyHolder, context );
+
 		if ( isIdentifierMapper
-				|| isComponentEmbedded && inferredData.getPropertyName() == null ) {
+			|| isNonAggregated && inferredData.getPropertyName() == null ) {
 			embeddable.setComponentClassName( embeddable.getOwner().getClassName() );
 		}
 		else {
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/PropertyBinder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/PropertyBinder.java
@@ -269,6 +269,13 @@ private Property makePropertyAndValue() {
 		basicValueBinder.setReferencedEntityName( referencedEntityName );
 		basicValueBinder.setAccessType( accessType );
 
+		if ( holder instanceof ComponentPropertyHolder embeddableTypedContainer ) {
+			final Component component = embeddableTypedContainer.getComponent();
+			if ( component.wasTableExplicitlyDefined() ) {
+				basicValueBinder.setTable( component.getTable() );
+			}
+		}
+
 		value = basicValueBinder.make();
 
 		return makeProperty();
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/models/HibernateAnnotations.java b/hibernate-core/src/main/java/org/hibernate/boot/models/HibernateAnnotations.java
@@ -248,6 +248,10 @@ public interface HibernateAnnotations {
 			EmbeddedColumnNaming.class,
 			EmbeddedColumnNamingAnnotation.class
 	);
+	OrmAnnotationDescriptor<EmbeddedTable,EmbeddedTableAnnotation> EMBEDDED_TABLE = new OrmAnnotationDescriptor<>(
+			EmbeddedTable.class,
+			EmbeddedTableAnnotation.class
+	);
 	OrmAnnotationDescriptor<Fetch,FetchAnnotation> FETCH = new OrmAnnotationDescriptor<>(
 			Fetch.class,
 			FetchAnnotation.class
diff --git a/hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/EmbeddedTableAnnotation.java b/hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/EmbeddedTableAnnotation.java
@@ -0,0 +1,57 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.boot.models.annotations.internal;
+
+import org.hibernate.annotations.EmbeddedTable;
+import org.hibernate.models.spi.ModelsContext;
+
+import java.lang.annotation.Annotation;
+import java.util.Map;
+
+/**
+ * @author Steve Ebersole
+ */
+@SuppressWarnings({ "ClassExplicitlyAnnotation", "unused" })
+public class EmbeddedTableAnnotation implements EmbeddedTable {
+	private String value;
+
+	/**
+	 * Used in creating dynamic annotation instances (e.g. from XML)
+	 */
+	public EmbeddedTableAnnotation(ModelsContext modelContext) {
+	}
+
+	/**
+	 * Used in creating annotation instances from JDK variant
+	 */
+	public EmbeddedTableAnnotation(
+			EmbeddedTable annotation,
+			ModelsContext modelContext) {
+		this.value = annotation.value();
+	}
+
+	/**
+	 * Used in creating annotation instances from Jandex variant
+	 */
+	public EmbeddedTableAnnotation(
+			Map<String, Object> attributeValues,
+			ModelsContext modelContext) {
+		this.value = (String) attributeValues.get( "value" );
+	}
+
+	@Override
+	public Class<? extends Annotation> annotationType() {
+		return EmbeddedTable.class;
+	}
+
+	@Override
+	public String value() {
+		return value;
+	}
+
+	public void value(String value) {
+		this.value = value;
+	}
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Component.java b/hibernate-core/src/main/java/org/hibernate/mapping/Component.java
@@ -100,6 +100,8 @@ public class Component extends SimpleValue implements AttributeContainer, MetaAt
 	private transient Boolean simpleRecord;
 	private String columnNamingPattern;
 
+	private boolean tableWasExplicit;
+
 	public Component(MetadataBuildingContext metadata, PersistentClass owner) throws MappingException {
 		this( metadata, owner.getTable(), owner );
 	}
@@ -158,6 +160,23 @@ public List<Property> getProperties() {
 		return properties;
 	}
 
+	public void setTable(Table table) {
+		if ( !tableWasExplicit ) {
+			super.setTable( table );
+		}
+
+		// otherwise, ignore it...
+	}
+
+	public void setTable(Table table, boolean wasExplicit) {
+		super.setTable( table );
+		tableWasExplicit = wasExplicit;
+	}
+
+	public boolean wasTableExplicitlyDefined() {
+		return tableWasExplicit;
+	}
+
 	public void addProperty(Property p, ClassDetails declaringClass) {
 		properties.add( p );
 		if ( isPolymorphic() && declaringClass != null ) {
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/embeddable/table/EmbeddedTableTests.java b/hibernate-core/src/test/java/org/hibernate/orm/test/embeddable/table/EmbeddedTableTests.java
diff --git a/hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/ServiceRegistryScope.java b/hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/ServiceRegistryScope.java
diff --git a/whats-new.adoc b/whats-new.adoc
