From 96331238ed66f79307b9f974db3112711c20a9fa Mon Sep 17 00:00:00 2001
From: Gail Badner <gbadner@redhat.com>
Date: Mon, 6 Aug 2018 22:25:21 -0700
Subject: [PATCH] HHH-12875 : Add comments to clarify how Collection#setWhere
 and #setManyToManyWhere are used

(cherry picked from commit 3ea9fa999cabbd1725cbce620c8af50507c8cec5)
---
 .../model/source/internal/hbm/ModelBinder.java   | 16 ++++++++++++++++
 .../cfg/annotations/CollectionBinder.java        | 14 ++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java
index 13123c494f..2b414c96b6 100644
--- a/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java
+++ b/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java
@@ -3465,6 +3465,12 @@ public class ModelBinder {
 
 				final PersistentClass referencedEntityBinding = mappingDocument.getMetadataCollector()
 						.getEntityBinding( elementSource.getReferencedEntityName() );
+				// For a one-to-many association, there are 2 possible sources of "where" clauses that apply
+				// to the associated entity table:
+				// 1) from the associated entity mapping; i.e., <class name="..." ... where="..." .../>
+				// 2) from the collection mapping; e.g., <set name="..." ... where="..." .../>
+				// Collection#setWhere is used to set the "where" clause that applies to the collection table
+				// (which is the associated entity table for a one-to-many association).
 				collectionBinding.setWhere(
 					StringHelper.getNonEmptyOrConjunctionIfBothNonEmpty(
 							referencedEntityBinding.getWhere(),
@@ -3599,7 +3605,17 @@ public class ModelBinder {
 				final PersistentClass referencedEntityBinding = mappingDocument.getMetadataCollector().getEntityBinding(
 						elementSource.getReferencedEntityName()
 				);
+
+				// Collection#setWhere is used to set the "where" clause that applies to the collection table
+				// (which is the join table for a many-to-many association).
+				// This "where" clause comes from the collection mapping; e.g., <set name="..." ... where="..." .../>
 				getCollectionBinding().setWhere( getPluralAttributeSource().getWhere() );
+				// For a many-to-many association, there are 2 possible sources of "where" clauses that apply
+				// to the associated entity table (not the join table):
+				// 1) from the associated entity mapping; i.e., <class name="..." ... where="..." .../>
+				// 2) from the many-to-many mapping; i.e <many-to-many ... where="...".../>
+				// Collection#setManytoManyWhere is used to set the "where" clause that applies to
+				// to the many-to-many associated entity table (not the join table).
 				getCollectionBinding().setManyToManyWhere(
 						StringHelper.getNonEmptyOrConjunctionIfBothNonEmpty(
 								referencedEntityBinding.getWhere(),
diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/annotations/CollectionBinder.java b/hibernate-core/src/main/java/org/hibernate/cfg/annotations/CollectionBinder.java
index be9414177d..cbd177f4df 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/annotations/CollectionBinder.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/annotations/CollectionBinder.java
@@ -945,6 +945,11 @@ public abstract class CollectionBinder {
 			}
 		}
 
+		// There are 2 possible sources of "where" clauses that apply to the associated entity table:
+		// 1) from the associated entity mapping; i.e., @Entity @Where(clause="...")
+		// 2) from the collection mapping;
+		//    for one-to-many, e.g., @OneToMany @JoinColumn @Where(clause="...") public Set<Rating> getRatings();
+		//    for many-to-many e.g., @ManyToMany @Where(clause="...") public Set<Rating> getRatings();
 		String whereOnClassClause = null;
 		if ( property.getElementClass() != null ) {
 			Where whereOnClass = property.getElementClass().getAnnotation( Where.class );
@@ -962,9 +967,15 @@ public abstract class CollectionBinder {
 				whereOnCollectionClause
 		);
 		if ( hasAssociationTable ) {
+			// A many-to-many association has an association (join) table
+			// Collection#setManytoManyWhere is used to set the "where" clause that applies to
+			// to the many-to-many associated entity table (not the join table).
 			collection.setManyToManyWhere( whereClause );
 		}
 		else {
+			// A one-to-many association does not have an association (join) table.
+			// Collection#setWhere is used to set the "where" clause that applies to the collection table
+			// (which is the associated entity table for a one-to-many association).
 			collection.setWhere( whereClause );
 		}
 
@@ -972,6 +983,9 @@ public abstract class CollectionBinder {
 		String whereJoinTableClause = whereJoinTable == null ? null : whereJoinTable.clause();
 		if ( StringHelper.isNotEmpty( whereJoinTableClause ) ) {
 			if ( hasAssociationTable ) {
+				// This is a many-to-many association.
+				// Collection#setWhere is used to set the "where" clause that applies to the collection table
+				// (which is the join table for a many-to-many association).
 				collection.setWhere( whereJoinTableClause );
 			}
 			else {