HHH-12623 - Improve Javadoc comments for QueryHints.html#NATIVE_SPACES

hibernate-core/src/main/java/org/hibernate/SynchronizeableQuery.java

@@ -18,7 +18,10 @@ import java.util.Collection;
  * In a similar manner, these query spaces also affect how query result caching can recognize
  * invalidated results.
  *
- * @author Steve Ebersole
+ * @implSpec Note that any String can be used and need not actually occur in the query or
+ * even be a mapped table.  This fact can be used to completely circumvent auto-flush checking
+ * and possible large-scale cache invalidation.  Note that this approach also circumvents
+ * "correctness" of the results if there are any pending changes to the tables being queried.
  */
 @SuppressWarnings( { "unused", "UnusedReturnValue", "RedundantSuppression" } )
 public interface SynchronizeableQuery<T> {

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

@@ -6,6 +6,8 @@
  */
 package org.hibernate.annotations;
 
+import org.hibernate.FlushMode;
+
 /**
  * Consolidation of hints available to Hibernate JPA queries.  Mainly used to define features available on
  * Hibernate queries that have no corollary in JPA queries.
@@ -130,10 +132,17 @@ public class QueryHints {
 	 * Passed value can be any of:<ul>
 	 *     <li>List of the spaces</li>
 	 *     <li>array of the spaces</li>
-	 *     <li>String "whitespace"-separated list of the spaces</li>
+	 *     <li>String as "whitespace"-separated list of the spaces</li>
 	 * </ul>
 	 *
+	 * Note that the passed space need not match to any real spaces/tables in
+	 * the underlying query.  This can be used to completely circumvent
+	 * the auto-flush checks as well as any cache invalidation that might
+	 * occur as part of a flush.  See the documentation on SynchronizeableQuery
+	 * for details.  See also {@link FlushMode#MANUAL}
+	 *
 	 * @see org.hibernate.SynchronizeableQuery
+	 * @see #FLUSH_MODE
 	 */
 	public static final String NATIVE_SPACES = "org.hibernate.query.native.spaces";
 

hibernate-core/src/main/java/org/hibernate/jpa/QueryHints.java

@@ -138,6 +138,9 @@ public class QueryHints {
 
 	public static final String HINT_PASS_DISTINCT_THROUGH = PASS_DISTINCT_THROUGH;
 
+	/**
+	 * See {@link org.hibernate.annotations.QueryHints#NATIVE_SPACES}
+	 */
 	public static final String HINT_NATIVE_SPACES = NATIVE_SPACES;