even more jdoc about query cache invalidation
This commit is contained in:
parent
1d5c0a60d3
commit
e72d0aeb41
|
@ -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
|
||||
|
|
|
@ -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
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue