even more jdoc about query cache invalidation

hibernate-core/src/main/java/org/hibernate/cache/spi/QueryKey.java

@@ -17,7 +17,14 @@
 
 /**
  * A key that identifies a particular query with bound parameter values.
- * This is the object Hibernate uses as a key into its query cache.
+ * This object is used as a key into the {@linkplain QueryResultsCache
+ * query results cache}.
+ * <p>
+ * Note that the fields of this object must contain every explicit and
+ * implicit setting and parameter argument that affects the result list
+ * of the query, including things like the {@link #maxRows limit} and
+ * {@link #firstRow offset}, {@link #tenantIdentifier current tenant id},
+ * and {@link #enabledFilterNames enabled filters}.
  *
  * @author Gavin King
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/cache/spi/QueryResultsCache.java

@@ -14,14 +14,18 @@
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * Defines the responsibility for managing query result data caching
+ * Responsible for managing query result list caching in a specific
- * in a specific {@linkplain QueryResultsRegion query cache region}.
+ * {@linkplain QueryResultsRegion query cache region}. There may be
- * There may be multiple instances of {@code QueryResultsCache},
+ * multiple instances of {@code QueryResultsCache}, corresponding to
- * corresponding to second-level cache regions with distinct policies.
+ * second-level cache regions with distinct policies.
  * <p>
- * A {@code QueryResultsCache} must be used in conjunction with a
+ * A {@code QueryResultsCache} depends on the {@link TimestampsCache}
- * {@link TimestampsCache} which tracks invalidation of the query
+ * to track invalidation of the query spaces (tables) which affect the
- * spaces (tables) which affect the cached queries.
+ * cached queries. A cached query result list is considered <em>stale</em>
+ * if any one of the query spaces which affect the query results was
+ * {@linkplain TimestampsCache#invalidate invalidated} since the result
+ * list was read from the database and {@linkplain #put stored} in the
+ * query result cache.
  * 
  * @author Gavin King
  * @author Steve Ebersole
@@ -33,10 +37,12 @@ public interface QueryResultsCache {
 	QueryResultsRegion getRegion();
 
 	/**
-	 * Put a result into the query cache.
+	 * Store a result list of a query with the given {@link QueryKey}
+	 * in the query result cache.
 	 *
-	 * @param key The cache key
+	 * @param key The cache key uniquely identifying the query and its
-	 * @param result The results to cache
+	 *            bound parameter arguments
+	 * @param result The result list to cache
 	 * @param session The originating session
 	 *
 	 * @return Whether the put actually happened.
@@ -49,13 +55,21 @@ boolean put(
 			SharedSessionContractImplementor session) throws HibernateException;
 
 	/**
-	 * Get results from the cache.
+	 * Attempt to retrieve a cached query result list for the given
+	 * {@link QueryKey} from the {@linkplain QueryResultsRegion cache
+	 * region}, and then {@linkplain TimestampsCache#isUpToDate check}
+	 * if the cached results, if any, are stale. If there is no cached
+	 * result list for the given key, or if the cached results are stale,
+	 * return {@code null}.
 	 *
-	 * @param key The cache key
+	 * @param key The cache key uniquely identifying the query and its
-	 * @param spaces The query spaces (used in invalidation plus validation checks)
+	 *            bound parameter arguments
+	 * @param spaces The query spaces which affect the results of the
+	 *               query (used to check if cached results are stale)
 	 * @param session The originating session
 	 *
-	 * @return The cached results; may be null.
+	 * @return The cached results; may be null if there are no cached
+	 *         results for the given key, or if the results are stale.
 	 *
 	 * @throws HibernateException Indicates a problem delegating to the underlying cache.
 	 */
@@ -65,10 +79,17 @@ List<?> get(
 			SharedSessionContractImplementor session) throws HibernateException;
 
 	/**
-	 * Get results from the cache.
+	 * Attempt to retrieve a cached query result list for the given
+	 * {@link QueryKey} from the {@linkplain QueryResultsRegion cache
+	 * region}, and then {@linkplain TimestampsCache#isUpToDate check}
+	 * if the cached results, if any, are stale. If there is no cached
+	 * result list for the given key, or if the cached results are stale,
+	 * return {@code null}.
 	 *
-	 * @param key The cache key
+	 * @param key The cache key uniquely identifying the query and its
-	 * @param spaces The query spaces (used in invalidation plus validation checks)
+	 *            bound parameter arguments
+	 * @param spaces The query spaces which affect the results of the
+	 *               query (used to check if cached results are stale)
 	 * @param session The originating session
 	 *
 	 * @return The cached results; may be null.
@@ -81,7 +102,7 @@ List<?> get(
 			SharedSessionContractImplementor session) throws HibernateException;
 
 	/**
-	 * Clear items from the query cache.
+	 * Clear all items from this query result cache.
 	 *
 	 * @throws CacheException Indicates a problem delegating to the underlying cache.
 	 */
@@ -90,6 +111,6 @@ default void clear() throws CacheException {
 	}
 
 	default void destroy() {
-		// nothing to do.. the region itself gets destroyed
+		// nothing to do, the region itself gets destroyed
 	}
 }

hibernate-core/src/main/java/org/hibernate/cache/spi/TimestampsCache.java

@@ -22,7 +22,7 @@
  *     Hibernate affects the corresponding table.
  * <li>A cached query result set is {@linkplain #isUpToDate checked for
  *     staleness} against the {@code TimestampsCache} when it is read
- *     from the {@link QueryResultsCache}.
+ *     from a {@link QueryResultsRegion} by a {@link QueryResultsCache}.
  * </ul>
  *
  * @author Steve Ebersole