HHH-17002, HHH-18820, HHH-19391, HHH-18514 add comments explaining an important point

Author: gavinking

hibernate-core/src/main/java/org/hibernate/query/sqm/tree/domain/AbstractSqmJoin.java

@@ -156,10 +156,18 @@ public <X> SqmEntityJoin<R, X> join(Class<X> targetEntityClass, SqmJoinType join
 
 	@Override
 	public boolean equals(Object object) {
-		return object instanceof AbstractSqmJoin<?, ?> that
-			&& super.equals( object )
-			&& this.joinType == that.joinType; // unnecessary, but harmless
-//			&& Objects.equals( onClausePredicate, that.onClausePredicate ); // including this causes problems
+		// Note that this implementation of equals() is only used for
+		// and is only correct when comparing use of AbstractSqmJoin
+		// within path expressions. See SqmFromClause.equalsJoins().
+		return object instanceof AbstractSqmJoin
+			&& super.equals( object );
+			// We do not need to include these in the comparison because
+			// this is taken care of in SqmFromClause.equalsJoins(), which
+			// exists because including the onClausePredicate would result
+			// in a circularity when comparing AbstractSqmJoin in path
+			// expressions.
+//			&& this.joinType == that.joinType
+//			&& Objects.equals( this.onClausePredicate, that.onClausePredicate );
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/query/sqm/tree/from/SqmFromClause.java

@@ -192,6 +192,8 @@ public static void appendTreatJoins(SqmFrom<?, ?> sqmFrom, StringBuilder sb, Sqm
 	public boolean equals(Object object) {
 		return object instanceof SqmFromClause that
 			&& this.getNumberOfRoots() == that.getNumberOfRoots()
+			// calling equals() here leads to circularity,
+			// and so we need to flatten out the comparison
 			&& equalRoots( this.getRoots(), that.getRoots() );
 	}