HHH-19952: Add @CollectionTableOverride to override collection table names for embeddable collection fields

Author: RealTake

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

@@ -0,0 +1,56 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Used to override the collection table name for a collection
+ * that is nested within an embeddable class.
+ *
+ * <p>This annotation allows overriding the collection table name
+ * for collections that are defined within an embeddable class.
+ *
+ * <p>Example:
+ * <pre>
+ * &#064;Embeddable
+ * public class Address {
+ *     &#064;ElementCollection
+ *     &#064;CollectionTable(name = "default_phones")
+ *     List&lt;Phone&gt; phones;
+ * }
+ *
+ * &#064;Entity
+ * public class Person {
+ *     &#064;Embedded
+ *     &#064;CollectionTableOverride(
+ *         name = "phones",
+ *         table = "person_phones"
+ *     )
+ *     Address address;
+ * }
+ * </pre>
+ */
+@Target({TYPE, METHOD, FIELD})
+@Retention(RUNTIME)
+public @interface CollectionTableOverride {
+	/**
+	 * The path to the collection property within the embeddable.
+	 * For example, if the embeddable has a field "phones", the name would be "phones".
+	 * For nested embeddables, use dot notation like "address.phones".
+	 */
+	String name();
+
+	/**
+	 * The name of the collection table to use instead of the default.
+	 */
+	String table();
+}

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

@@ -0,0 +1,22 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Container for multiple {@link CollectionTableOverride} annotations.
+ */
+@Target({TYPE, METHOD, FIELD})
+@Retention(RUNTIME)
+public @interface CollectionTableOverrides {
+	CollectionTableOverride[] value();
+}

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

@@ -19,6 +19,8 @@
 import org.hibernate.FetchMode;
 import org.hibernate.MappingException;
 import org.hibernate.annotations.*;
+import org.hibernate.annotations.CollectionTableOverride;
+import org.hibernate.annotations.CollectionTableOverrides;
 import org.hibernate.boot.model.IdentifierGeneratorDefinition;
 import org.hibernate.boot.models.AnnotationPlacementException;
 import org.hibernate.boot.models.JpaAnnotations;
@@ -103,6 +105,7 @@
 import static org.hibernate.boot.model.internal.BinderHelper.extractFromPackage;
 import static org.hibernate.boot.model.internal.BinderHelper.getFetchMode;
 import static org.hibernate.boot.model.internal.BinderHelper.getPath;
+import static org.hibernate.boot.model.internal.BinderHelper.getRelativePath;
 import static org.hibernate.boot.model.internal.BinderHelper.isDefault;
 import static org.hibernate.boot.model.internal.BinderHelper.isPrimitive;
 import static org.hibernate.boot.model.internal.DialectOverridesAnnotationHelper.getOverridableAnnotation;
@@ -620,6 +623,14 @@ private static void bindJoinedTableAssociation(
 		final var assocTable = propertyHolder.getJoinTable( property );
 		final var collectionTable = property.getDirectAnnotationUsage( CollectionTable.class );
 
+		// Check for @CollectionTableOverride annotation
+		final var collectionTableOverride = findCollectionTableOverride(
+				propertyHolder,
+				property,
+				inferredData,
+				buildingContext
+		);
+
 		final JoinColumn[] annJoins;
 		final JoinColumn[] annInverseJoins;
 		if ( assocTable != null || collectionTable != null ) {
@@ -636,7 +647,10 @@ private static void bindJoinedTableAssociation(
 			if ( collectionTable != null ) {
 				catalog = collectionTable.catalog();
 				schema = collectionTable.schema();
-				tableName = collectionTable.name();
+				// Use overridden table name if @CollectionTableOverride is present
+				tableName = collectionTableOverride != null
+						? collectionTableOverride.table()
+						: collectionTable.name();
 				uniqueConstraints = collectionTable.uniqueConstraints();
 				joins = collectionTable.joinColumns();
 				inverseJoins = null;
@@ -2805,4 +2819,149 @@ else if ( isManyToAny ) {
 			}
 		}
 	}
+
+	/**
+	 * Finds a @CollectionTableOverride annotation for the given collection property.
+	 *
+	 * @param propertyHolder The PropertyHolder containing the property
+	 * @param property The collection property MemberDetails
+	 * @param inferredData The PropertyData for the property
+	 * @param buildingContext The MetadataBuildingContext
+	 * @return The CollectionTableOverride if found, null otherwise
+	 */
+	private static CollectionTableOverride findCollectionTableOverride(
+			PropertyHolder propertyHolder,
+			MemberDetails property,
+			PropertyData inferredData,
+			MetadataBuildingContext buildingContext) {
+
+		// Get the entity's PersistentClass
+		final PersistentClass persistentClass = propertyHolder.getPersistentClass();
+		if (persistentClass == null) {
+			return null;
+		}
+
+		// Get the ClassDetails from the models context
+		final var modelsContext = buildingContext.getBootstrapContext().getModelsContext();
+		final ClassDetails entityClassDetails = modelsContext.getClassDetailsRegistry()
+				.resolveClassDetails(persistentClass.getClassName());
+
+		if (entityClassDetails == null) {
+			return null;
+		}
+
+		// Get the full relative path (e.g., "address.phones" for embeddable collections)
+		final String fullPath = getRelativePath(propertyHolder, property.getName());
+
+		// Extract the first part of the path (e.g., "address" from "address.phones")
+		// This is the field name in the entity class where @CollectionTableOverride is attached
+		final String fieldName;
+		if (fullPath.contains(".")) {
+			fieldName = fullPath.substring(0, fullPath.indexOf('.'));
+		} else {
+			// Direct collection on entity, use property name directly
+			fieldName = property.getName();
+		}
+
+		// Find the field property in the entity class
+		MemberDetails entityField = null;
+		try {
+			// Try to get the property from the entity class
+			for (MemberDetails member : entityClassDetails.getFields()) {
+				if (member.getName().equals(fieldName)) {
+					entityField = member;
+					break;
+				}
+			}
+			if (entityField == null) {
+				for (MemberDetails member : entityClassDetails.getMethods()) {
+					if (member.getName().equals(fieldName) ||
+							(member.getName().startsWith("get") &&
+							member.getName().substring(3).toLowerCase().equals(fieldName.toLowerCase()))) {
+						entityField = member;
+						break;
+					}
+				}
+			}
+		} catch (Exception e) {
+			// Ignore and fall back to class-level annotation
+		}
+
+		// Check field-level annotations first (if field found)
+		if (entityField != null) {
+			// Check for @CollectionTableOverrides (plural) on field
+			final var overridesAnnotation = entityField.getDirectAnnotationUsage(CollectionTableOverrides.class);
+			if (overridesAnnotation != null) {
+				for (CollectionTableOverride override : overridesAnnotation.value()) {
+					if (matchesPath(override.name(), propertyHolder, property, inferredData)) {
+						return override;
+					}
+				}
+			}
+
+			// Check for @CollectionTableOverride (singular) on field
+			final var singleOverride = entityField.getDirectAnnotationUsage(CollectionTableOverride.class);
+			if (singleOverride != null && matchesPath(
+					singleOverride.name(),
+					propertyHolder,
+					property,
+					inferredData)) {
+				return singleOverride;
+			}
+		}
+
+		// Fall back to class-level annotations
+		// Check for @CollectionTableOverrides (plural) on class
+		final var classOverridesAnnotation = entityClassDetails.getDirectAnnotationUsage(CollectionTableOverrides.class);
+		if (classOverridesAnnotation != null) {
+			for (CollectionTableOverride override : classOverridesAnnotation.value()) {
+				if (matchesPath(override.name(), propertyHolder, property, inferredData)) {
+					return override;
+				}
+			}
+		}
+
+		// Check for @CollectionTableOverride (singular) on class
+		final var classSingleOverride = entityClassDetails.getDirectAnnotationUsage(CollectionTableOverride.class);
+		if (classSingleOverride != null && matchesPath(
+				classSingleOverride.name(),
+				propertyHolder,
+				property,
+				inferredData)) {
+			return classSingleOverride;
+		}
+
+		return null;
+	}
+
+	/**
+	 * Checks if the override name matches the current collection property path.
+	 *
+	 * @param overrideName The name from @CollectionTableOverride
+	 * @param propertyHolder The PropertyHolder containing the property
+	 * @param property The collection property MemberDetails
+	 * @param inferredData The PropertyData for the property
+	 * @return true if the path matches
+	 */
+	private static boolean matchesPath(
+			String overrideName,
+			PropertyHolder propertyHolder,
+			MemberDetails property,
+			PropertyData inferredData) {
+
+		// Get the full relative path (e.g., "address.phones" for embeddable collections)
+		final String fullPath = getRelativePath(propertyHolder, property.getName());
+
+		// Direct match: override name matches the full path
+		if (overrideName.equals(fullPath)) {
+			return true;
+		}
+
+		// Simple case: property name directly matches (for direct entity collections)
+		if (overrideName.equals(property.getName())) {
+			return true;
+		}
+
+		return false;
+	}
 }