HHH-19952: Support nested @CollectionTable in @CollectionTableOverride

Replace table name string with nested @CollectionTable annotation
to allow full collection table configuration override, including
schema, catalog, joinColumns, indexes, and other attributes.

Author: RealTake

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

@@ -7,16 +7,18 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import jakarta.persistence.CollectionTable;
+
 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
+ * Used to override the collection table configuration for a collection
  * that is nested within an embeddable class.
  *
- * <p>This annotation allows overriding the collection table name
+ * <p>This annotation allows overriding the collection table configuration
  * for collections that are defined within an embeddable class.
  *
  * <p>Example:
@@ -33,7 +35,7 @@
  *     &#064;Embedded
  *     &#064;CollectionTableOverride(
  *         name = "phones",
- *         table = "person_phones"
+ *         collectionTable = &#064;CollectionTable(name = "person_phones")
  *     )
  *     Address address;
  * }
@@ -50,7 +52,9 @@
 	String name();
 
 	/**
-	 * The name of the collection table to use instead of the default.
+	 * The collection table configuration to use instead of the default.
+	 * This allows specifying the full {@link CollectionTable} annotation
+	 * with all its attributes (name, schema, catalog, joinColumns, indexes, etc.).
 	 */
-	String table();
+	CollectionTable collectionTable();
 }

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

@@ -357,7 +357,7 @@ private static NotFoundAction notFoundAction(
 		if ( notFound != null ) {
 			if ( manyToManyAnn == null ) {
 				throw new AnnotationException( "Collection '" + getPath( propertyHolder, inferredData )
-													   + "' annotated '@NotFound' is not a '@ManyToMany' association" );
+													+ "' annotated '@NotFound' is not a '@ManyToMany' association" );
 			}
 			return notFound.action();
 		}
@@ -405,8 +405,8 @@ private static void checkAnnotations(
 		if ( ( oneToMany != null || manyToMany != null || elementCollection != null )
 				&& isToManyAssociationWithinEmbeddableCollection( propertyHolder ) ) {
 			throw new AnnotationException( "Property '" + getPath( propertyHolder, inferredData ) +
-												   "' belongs to an '@Embeddable' class that is contained in an '@ElementCollection' and may not be a "
-												   + annotationName( oneToMany, manyToMany, elementCollection ) );
+												"' belongs to an '@Embeddable' class that is contained in an '@ElementCollection' and may not be a "
+												+ annotationName( oneToMany, manyToMany, elementCollection ) );
 		}
 
 		if ( oneToMany != null && property.hasDirectAnnotationUsage( SoftDelete.class ) ) {
@@ -420,20 +420,20 @@ && isToManyAssociationWithinEmbeddableCollection( propertyHolder ) ) {
 				&& manyToMany != null
 				&& isNotBlank( manyToMany.mappedBy() ) ) {
 			throw new AnnotationException( "Collection '" + getPath( propertyHolder, inferredData ) +
-												   "' is the unowned side of a bidirectional '@ManyToMany' and may not have an '@OrderColumn'" );
+												"' is the unowned side of a bidirectional '@ManyToMany' and may not have an '@OrderColumn'" );
 		}
 
 		if ( manyToMany != null || elementCollection != null ) {
 			if ( property.hasDirectAnnotationUsage( JoinColumn.class )
 					|| property.hasDirectAnnotationUsage( JoinColumns.class ) ) {
 				throw new AnnotationException( "Property '" + getPath( propertyHolder, inferredData )
-													   + "' is a " + annotationName(
+													+ "' is a " + annotationName(
 						oneToMany,
 						manyToMany,
 						elementCollection
 				)
-													   + " and is directly annotated '@JoinColumn'"
-													   + " (specify '@JoinColumn' inside '@JoinTable' or '@CollectionTable')" );
+													+ " and is directly annotated '@JoinColumn'"
+													+ " (specify '@JoinColumn' inside '@JoinTable' or '@CollectionTable')" );
 			}
 		}
 	}
@@ -476,13 +476,13 @@ private static String handleTargetEntity(
 		//TODO enhance exception with @ManyToAny and @CollectionOfElements
 		if ( oneToManyAnn != null && manyToManyAnn != null ) {
 			throw new AnnotationException( "Property '" + getPath( propertyHolder, inferredData )
-												   + "' is annotated both '@OneToMany' and '@ManyToMany'" );
+												+ "' is annotated both '@OneToMany' and '@ManyToMany'" );
 		}
 		final String mappedBy;
 		if ( oneToManyAnn != null ) {
 			if ( joinColumns.isSecondary() ) {
 				throw new AnnotationException( "Collection '" + getPath( propertyHolder, inferredData )
-													   + "' has foreign key in secondary table" );
+													+ "' has foreign key in secondary table" );
 			}
 			collectionBinder.setFkJoinColumns( joinColumns );
 			mappedBy = nullIfEmpty( oneToManyAnn.mappedBy() );
@@ -497,7 +497,7 @@ private static String handleTargetEntity(
 		else if ( elementCollectionAnn != null ) {
 			if ( joinColumns.isSecondary() ) {
 				throw new AnnotationException( "Collection '" + getPath( propertyHolder, inferredData )
-													   + "' has foreign key in secondary table" );
+													+ "' has foreign key in secondary table" );
 			}
 			collectionBinder.setFkJoinColumns( joinColumns );
 			mappedBy = null;
@@ -657,9 +657,14 @@ private static void bindJoinedTableAssociation(
 				buildingContext
 		);
 
+		// If @CollectionTableOverride is present, use its collectionTable annotation
+		final CollectionTable effectiveCollectionTable = collectionTableOverride != null
+				? collectionTableOverride.collectionTable()
+				: collectionTable;
+
 		final JoinColumn[] annJoins;
 		final JoinColumn[] annInverseJoins;
-		if ( assocTable != null || collectionTable != null ) {
+		if ( assocTable != null || effectiveCollectionTable != null ) {
 			final String catalog;
 			final String schema;
 			final String tableName;
@@ -670,18 +675,15 @@ private static void bindJoinedTableAssociation(
 			final String options;
 
 			//JPA 2 has priority
-			if ( collectionTable != null ) {
-				catalog = collectionTable.catalog();
-				schema = collectionTable.schema();
-				// Use overridden table name if @CollectionTableOverride is present
-				tableName = collectionTableOverride != null
-						? collectionTableOverride.table()
-						: collectionTable.name();
-				uniqueConstraints = collectionTable.uniqueConstraints();
-				joins = collectionTable.joinColumns();
+			if ( effectiveCollectionTable != null ) {
+				catalog = effectiveCollectionTable.catalog();
+				schema = effectiveCollectionTable.schema();
+				tableName = effectiveCollectionTable.name();
+				uniqueConstraints = effectiveCollectionTable.uniqueConstraints();
+				joins = effectiveCollectionTable.joinColumns();
 				inverseJoins = null;
-				jpaIndexes = collectionTable.indexes();
-				options = collectionTable.options();
+				jpaIndexes = effectiveCollectionTable.indexes();
+				options = effectiveCollectionTable.options();
 			}
 			else {
 				catalog = assocTable.catalog();
@@ -928,20 +930,20 @@ private static CollectionClassification determineCollectionClassification(
 
 		if ( property.hasAnnotationUsage( OrderColumn.class, modelsContext ) ) {
 			throw new AnnotationException( "Attribute '"
-												   + qualify(
+												+ qualify(
 					property.getDeclaringType().getName(),
 					property.getName()
 			)
-												   + "' is annotated '@Bag' and may not also be annotated '@OrderColumn'" );
+												+ "' is annotated '@Bag' and may not also be annotated '@OrderColumn'" );
 		}
 
 		if ( property.hasAnnotationUsage( ListIndexBase.class, modelsContext ) ) {
 			throw new AnnotationException( "Attribute '"
-												   + qualify(
+												+ qualify(
 					property.getDeclaringType().getName(),
 					property.getName()
 			)
-												   + "' is annotated '@Bag' and may not also be annotated '@ListIndexBase'" );
+												+ "' is annotated '@Bag' and may not also be annotated '@ListIndexBase'" );
 		}
 
 		final var collectionJavaType = property.getType().determineRawClass().toJavaClass();
@@ -1078,7 +1080,7 @@ private void setElementType(TypeDetails collectionElementType) {
 
 	private void setTargetEntity(Class<?> targetEntity) {
 		setTargetEntity( modelsContext().getClassDetailsRegistry()
-								 .resolveClassDetails( targetEntity.getName() ) );
+								.resolveClassDetails( targetEntity.getName() ) );
 	}
 
 	private void setTargetEntity(ClassDetails targetEntity) {
@@ -1151,7 +1153,7 @@ private boolean isMutable() {
 	private void checkMapKeyColumn() {
 		if ( property.hasDirectAnnotationUsage( MapKeyColumn.class ) && hasMapKeyProperty ) {
 			throw new AnnotationException( "Collection '" + qualify( propertyHolder.getPath(), propertyName )
-												   + "' is annotated both '@MapKey' and '@MapKeyColumn'" );
+												+ "' is annotated both '@MapKey' and '@MapKeyColumn'" );
 		}
 	}
 
@@ -1188,49 +1190,49 @@ private void detectMappedByProblem(boolean isMappedBy) {
 			if ( property.hasDirectAnnotationUsage( JoinColumn.class )
 					|| property.hasDirectAnnotationUsage( JoinColumns.class ) ) {
 				throw new AnnotationException( "Association '"
-													   + qualify( propertyHolder.getPath(), propertyName )
-													   + "' is 'mappedBy' another entity and may not specify the '@JoinColumn'" );
+													+ qualify( propertyHolder.getPath(), propertyName )
+													+ "' is 'mappedBy' another entity and may not specify the '@JoinColumn'" );
 			}
 			if ( propertyHolder.getJoinTable( property ) != null ) {
 				throw new AnnotationException( "Association '"
-													   + qualify( propertyHolder.getPath(), propertyName )
-													   + "' is 'mappedBy' another entity and may not specify the '@JoinTable'" );
+													+ qualify( propertyHolder.getPath(), propertyName )
+													+ "' is 'mappedBy' another entity and may not specify the '@JoinTable'" );
 			}
 			if ( oneToMany ) {
 				if ( property.hasDirectAnnotationUsage( MapKeyColumn.class ) ) {
 					BOOT_LOGGER.warn( "Association '"
-											  + qualify( propertyHolder.getPath(), propertyName )
-											  + "' is 'mappedBy' another entity and should not specify a '@MapKeyColumn'"
-											  + " (use '@MapKey' instead)" );
+											+ qualify( propertyHolder.getPath(), propertyName )
+											+ "' is 'mappedBy' another entity and should not specify a '@MapKeyColumn'"
+											+ " (use '@MapKey' instead)" );
 				}
 				if ( property.hasDirectAnnotationUsage( OrderColumn.class ) ) {
 					BOOT_LOGGER.warn( "Association '"
-											  + qualify( propertyHolder.getPath(), propertyName )
-											  + "' is 'mappedBy' another entity and should not specify an '@OrderColumn'"
-											  + " (use '@OrderBy' instead)" );
+											+ qualify( propertyHolder.getPath(), propertyName )
+											+ "' is 'mappedBy' another entity and should not specify an '@OrderColumn'"
+											+ " (use '@OrderBy' instead)" );
 				}
 			}
 			else {
 				if ( property.hasDirectAnnotationUsage( MapKeyColumn.class ) ) {
 					throw new AnnotationException( "Association '"
-														   + qualify( propertyHolder.getPath(), propertyName )
-														   + "' is 'mappedBy' another entity and may not specify a '@MapKeyColumn'"
-														   + " (use '@MapKey' instead)" );
+														+ qualify( propertyHolder.getPath(), propertyName )
+														+ "' is 'mappedBy' another entity and may not specify a '@MapKeyColumn'"
+														+ " (use '@MapKey' instead)" );
 				}
 				if ( property.hasDirectAnnotationUsage( OrderColumn.class ) ) {
 					throw new AnnotationException( "Association '"
-														   + qualify( propertyHolder.getPath(), propertyName )
-														   + "' is 'mappedBy' another entity and may not specify an '@OrderColumn'"
-														   + " (use '@OrderBy' instead)" );
+														+ qualify( propertyHolder.getPath(), propertyName )
+														+ "' is 'mappedBy' another entity and may not specify an '@OrderColumn'"
+														+ " (use '@OrderBy' instead)" );
 				}
 			}
 		}
 		else if ( oneToMany
 				&& property.hasDirectAnnotationUsage( OnDelete.class )
 				&& !hasExplicitJoinColumn() ) {
 			throw new AnnotationException( "Unidirectional '@OneToMany' association '"
-												   + qualify( propertyHolder.getPath(), propertyName )
-												   + "' is annotated '@OnDelete' and must explicitly specify a '@JoinColumn'" );
+												+ qualify( propertyHolder.getPath(), propertyName )
+												+ "' is annotated '@OnDelete' and must explicitly specify a '@JoinColumn'" );
 		}
 	}
 
@@ -1524,7 +1526,7 @@ TypeDetails getElementType() {
 			}
 			else {
 				throw new AnnotationException( "Collection '" + safeCollectionRole()
-													   + "' is declared with a raw type and has an explicit 'targetEntity'" );
+													+ "' is declared with a raw type and has an explicit 'targetEntity'" );
 			}
 		}
 		else {
@@ -1842,7 +1844,7 @@ private void addFilterJoinTable(boolean hasAssociationTable, FilterJoinTable fil
 		}
 		else {
 			throw new AnnotationException( "Collection '" + qualify( propertyHolder.getPath(), propertyName )
-												   + "' is an association with no join table and may not have a '@FilterJoinTable'" );
+												+ "' is an association with no join table and may not have a '@FilterJoinTable'" );
 		}
 	}
 
@@ -1864,15 +1866,15 @@ private String getDefaultFilterCondition(String name, Annotation annotation) {
 		final var definition = getMetadataCollector().getFilterDefinition( name );
 		if ( definition == null ) {
 			throw new AnnotationException( "Collection '" + qualify( propertyHolder.getPath(), propertyName )
-												   + "' has a '@" + annotation.annotationType().getSimpleName()
-												   + "' for an undefined filter named '" + name + "'" );
+												+ "' has a '@" + annotation.annotationType().getSimpleName()
+												+ "' for an undefined filter named '" + name + "'" );
 		}
 		final String defaultCondition = definition.getDefaultFilterCondition();
 		if ( isBlank( defaultCondition ) ) {
 			throw new AnnotationException( "Collection '" + qualify( propertyHolder.getPath(), propertyName ) +
-												   "' has a '@" + annotation.annotationType().getSimpleName()
-												   + "' with no 'condition' and no default condition was given by the '@FilterDef' named '"
-												   + name + "'" );
+												"' has a '@" + annotation.annotationType().getSimpleName()
+												+ "' with no 'condition' and no default condition was given by the '@FilterDef' named '"
+												+ name + "'" );
 		}
 		return defaultCondition;
 	}
@@ -2483,8 +2485,8 @@ private static void addCheckToCollection(Table collectionTable, Check check) {
 		final String name = check.name();
 		final String constraint = check.constraints();
 		collectionTable.addCheck( name.isBlank()
-										  ? new CheckConstraint( constraint )
-										  : new CheckConstraint( name, constraint ) );
+										? new CheckConstraint( constraint )
+										: new CheckConstraint( name, constraint ) );
 	}
 
 	private void processSoftDeletes() {
@@ -2513,7 +2515,7 @@ private void handleUnownedManyToMany(
 			boolean isCollectionOfEntities) {
 		if ( !isCollectionOfEntities ) {
 			throw new AnnotationException( "Association '" + safeCollectionRole() + "'"
-												   + targetEntityMessage( elementType ) );
+												+ targetEntityMessage( elementType ) );
 		}
 
 		joinColumns.setManyToManyOwnerSideEntityName( collectionEntity.getEntityName() );
@@ -2536,7 +2538,7 @@ private void checkCheckAnnotation() {
 		if ( property.hasDirectAnnotationUsage( Checks.class )
 				|| property.hasDirectAnnotationUsage( Check.class ) ) {
 			throw new AnnotationException( "Association '" + safeCollectionRole()
-												   + " is an unowned collection and may not be annotated '@Check'" );
+												+ " is an unowned collection and may not be annotated '@Check'" );
 		}
 	}
 
@@ -2549,20 +2551,20 @@ private void detectManyToManyProblems(
 			if ( property.hasDirectAnnotationUsage( ManyToMany.class )
 					|| property.hasDirectAnnotationUsage( OneToMany.class ) ) {
 				throw new AnnotationException( "Association '" + safeCollectionRole() + "'"
-													   + targetEntityMessage( elementType ) );
+													+ targetEntityMessage( elementType ) );
 			}
 			else if ( isManyToAny ) {
 				if ( propertyHolder.getJoinTable( property ) == null ) {
 					throw new AnnotationException( "Association '" + safeCollectionRole()
-														   + "' is a '@ManyToAny' and must specify a '@JoinTable'" );
+														+ "' is a '@ManyToAny' and must specify a '@JoinTable'" );
 				}
 			}
 			else {
 				final var joinTableAnn = propertyHolder.getJoinTable( property );
 				if ( joinTableAnn != null && !ArrayHelper.isEmpty( joinTableAnn.inverseJoinColumns() ) ) {
 					throw new AnnotationException( "Association '" + safeCollectionRole()
-														   + " has a '@JoinTable' with 'inverseJoinColumns' and"
-														   + targetEntityMessage( elementType ) );
+														+ " has a '@JoinTable' with 'inverseJoinColumns' and"
+														+ targetEntityMessage( elementType ) );
 				}
 			}
 		}