even more jdoc about query cache invalidation

This commit is contained in:
Gavin 2022-11-13 15:38:34 +01:00
parent 1d5c0a60d3
commit e72d0aeb41
3 changed files with 49 additions and 21 deletions

View File

@ -17,7 +17,14 @@ import org.hibernate.query.spi.QueryParameterBindings;
/**
* 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

View File

@ -14,14 +14,18 @@ import org.hibernate.cache.CacheException;
import org.hibernate.engine.spi.SharedSessionContractImplementor;
/**
* Defines the responsibility for managing query result data caching
* in a specific {@linkplain QueryResultsRegion query cache region}.
* There may be multiple instances of {@code QueryResultsCache},
* corresponding to second-level cache regions with distinct policies.
* Responsible for managing query result list caching in a specific
* {@linkplain QueryResultsRegion query cache region}. There may be
* multiple instances of {@code QueryResultsCache}, corresponding to
* second-level cache regions with distinct policies.
* <p>
* A {@code QueryResultsCache} must be used in conjunction with a
* {@link TimestampsCache} which tracks invalidation of the query
* spaces (tables) which affect the cached queries.
* A {@code QueryResultsCache} depends on the {@link TimestampsCache}
* to track invalidation of the query spaces (tables) which affect the
* 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 result The results to cache
* @param key The cache key uniquely identifying the query and its
* 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 @@ public interface QueryResultsCache {
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 spaces The query spaces (used in invalidation plus validation checks)
* @param key The cache key uniquely identifying the query and its
* 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 @@ public interface QueryResultsCache {
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 spaces The query spaces (used in invalidation plus validation checks)
* @param key The cache key uniquely identifying the query and its
* 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 @@ public interface QueryResultsCache {
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 @@ public interface QueryResultsCache {
}
default void destroy() {
// nothing to do.. the region itself gets destroyed
// nothing to do, the region itself gets destroyed
}
}

View File

@ -22,7 +22,7 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
* 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