deprecate two unused types in the cache SPI + add javadoc

also correct some errors in the names of types - this is
why it's better to use @link!!

Author: gavinking

hibernate-core/src/main/java/org/hibernate/cache/cfg/spi/DomainDataRegionBuildingContext.java

@@ -18,12 +18,12 @@
  */
 public interface DomainDataRegionBuildingContext {
 	/**
-	 * The CacheKeyFactory explicitly specified as part of the
-	 * bootstrap by the user, by some "container", etc.
+	 * The {@link CacheKeysFactory} explicitly specified as part of
+	 * the bootstrap by the user, by some "container", etc.
 	 *
-	 * If this method returns a non-null value, it is expected
-	 * that RegionFactory implementors will use to be its
-	 * CacheKeyFactory and return it when asked later.
+	 * If this method returns a non-null value, it is expected that
+	 * {@link RegionFactory} implementors will use to be its
+	 * {@link CacheKeysFactory} and return it when asked later.
 	 */
 	CacheKeysFactory getEnforcedCacheKeysFactory();
 

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

@@ -12,6 +12,8 @@
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
+ * A factory for keys into the second-level cache.
+ *
  * @author Radim Vansa <[email protected]>
  */
 public interface CacheKeysFactory {

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

@@ -9,7 +9,7 @@
 /**
  * Defines a context object that a {@link RegionFactory} is asked to create
  * ({@link RegionFactory#createTransactionContext}}) when a Hibernate Session
- * is created.  It's lifecycle is that of the Session.  It receives
+ * is created.  Its lifecycle is that of the Session.  It receives
  * "transactional event callbacks" around joining and completing resource
  * transactions.
  *
@@ -26,13 +26,13 @@
  * instead.  Native transactional implementation may provide looser semantics
  * and 2LC implementation has to adapt to these.
  *
- * @implNote Even though a JTA transaction may involve more than one Session
- * the CacheTransactionContext is specific to each Session since the distinction
- * is generally unimportant.  However, a provider is free to attempt to scope
- * these CacheTransactionContext instances in such a way that they may be
- * associated with more than one Session at a time.  This SPI is designed
- * to not require this of the caching impl, but it certainly allows the
- * provider to do it
+ * @implNote Even though a JTA transaction may involve more than one session,
+ * the {@code CacheTransactionSynchronization} is specific to each session since
+ * the distinction is generally unimportant.  However, a provider is free to
+ * attempt to scope these {@code CacheTransactionSynchronization} instances in
+ * such a way that they may be associated with more than one session at a time.
+ * This SPI is designed to not require this of the caching impl, but it certainly
+ * allows the provider to do it.
  *
  * @author Steve Ebersole
  * @author Radim Vansa

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

@@ -9,10 +9,11 @@
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * Specialized Region whose data is accessed directly (not requiring key/item wrapping).
+ * Specialized {@link Region} whose data is accessed directly,
+ * without the need for key/item wrapping.
  *
- * Does not define a "remove" operation because Hibernate's query and timestamps caches
- * only ever "get" and "put"
+ * Does not define a "remove" operation because Hibernate's
+ * query and timestamps caches only ever "get" and "put".
  *
  * @author Steve Ebersole
  */

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

@@ -12,51 +12,58 @@
 import org.hibernate.metamodel.model.domain.NavigableRole;
 
 /**
- * A Region for cacheable domain data - entity, collection, natural-id.
- *
- * Generally speaking, this type of data has:
- *
- * 		* specific key and value wrapping that needs to be applied
- * 		* specific access patterns ({@link EntityDataAccess}, etc),
- * 			including some form of locking
+ * A {@linkplain Region second-level cache region} that holds cacheable
+ * domain data:
+ * <ul>
+ * <li>the destructured state of entity instances and collections, and
+ * <li>mappings from natural id to primary key.
+ *</ul>
+ * This type of data has:
+ * <ul>
+ * <li>key and value wrapping that should to be applied, and
+ * <li>defined policies for managing concurrent data access, possibly
+ *     including some form of locking.
+ * </ul>
+ * These behaviors are defined by an instance of {@link EntityDataAccess},
+ * {@link CollectionDataAccess}, or {@link NaturalIdDataAccess}).
  *
  * @author Steve Ebersole
  */
 public interface DomainDataRegion extends Region {
 	/**
-	 * Build a EntityRegionAccess instance representing access to entity data
-	 * stored in this cache region using the given AccessType.
+	 * Build a {@link EntityDataAccess} instance representing access to
+	 * destructured entity data stored in this cache region.
 	 *
 	 * @apiNote Calling this method is illegal if the given entity is
-	 * not cached
+	 * not cacheable
 	 *
-	 * @param rootEntityRole The root entity name for the hierarchy whose data
-	 * we want to access
+	 * @param rootEntityRole The root entity name for the hierarchy whose
+	 * data we want to access
 	 *
 	 * @throws org.hibernate.cache.CacheException If the provider cannot provide the requested access
 	 */
 	EntityDataAccess getEntityDataAccess(NavigableRole rootEntityRole);
 
 	/**
-	 * Build a NaturalIdRegionAccess instance representing access to natural-id
-	 * data stored in this cache region using the given AccessType.
+	 * Build a {@link NaturalIdDataAccess} instance representing access to
+	 * natural id mappings stored in this cache region.
 	 *
-	 * @apiNote Calling this method is illegal if the given entity is
-	 * not cached
+	 * @apiNote Calling this method is illegal if the given natural id is
+	 * not cacheable
 	 *
 	 * @param rootEntityRole The NavigableRole of the root entity whose
-	 * natural-id data we want to access
+	 * natural id data we want to access
 	 *
 	 * @throws org.hibernate.cache.CacheException If the provider cannot provide the requested access
 	 */
 	NaturalIdDataAccess getNaturalIdDataAccess(NavigableRole rootEntityRole);
 
 	/**
-	 * Build a CollectionRegionAccess instance representing access to collection
-	 * data stored in this cache region using the given AccessType.
+	 * Build a {@link CollectionDataAccess} instance representing access to
+	 * destructured collection data stored in this cache region.
 	 *
-	 * @apiNote Calling this method is illegal if the given entity is
-	 * not cached
+	 * @apiNote Calling this method is illegal if the given collection is
+	 * not cacheable
 	 *
 	 * @param collectionRole The NavigableRole of the collection whose data
 	 * we want to access

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

@@ -7,7 +7,7 @@
 package org.hibernate.cache.spi;
 
 /**
- * Optional Region contract defining support for extra statistic information
+ * Optional contract for a {@link Region} defining support for extra statistic information.
  *
  * @author Steve Ebersole
  */

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

@@ -8,20 +8,20 @@
 
 import java.io.Serializable;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.Map;
-import java.util.Set;
 
-import org.hibernate.Filter;
+import org.hibernate.Remove;
 import org.hibernate.engine.spi.TypedValue;
-import org.hibernate.internal.FilterImpl;
 import org.hibernate.type.Type;
 
 /**
  * Allows cached queries to be keyed by enabled filters.
  * 
  * @author Gavin King
+ *
+ * @deprecated this class is no longer used
  */
+@Deprecated(since = "6.2") @Remove
 public final class FilterKey implements Serializable {
 	private final String filterName;
 	private final Map<String,TypedValue> filterParameters = new HashMap<>();

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

@@ -16,8 +16,8 @@
 import org.hibernate.query.spi.QueryParameterBindings;
 
 /**
- * A key that identifies a particular query with bound parameter values.  This is the object Hibernate uses
- * as its key into its query cache.
+ * A key that identifies a particular query with bound parameter values.
+ * This is the object Hibernate uses as a key into its query cache.
  *
  * @author Gavin King
  * @author Steve Ebersole

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

@@ -15,7 +15,13 @@
 
 /**
  * Defines the responsibility for managing query result data caching
- * in regards to a specific region.
+ * 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.
  * 
  * @author Gavin King
  * @author Steve Ebersole

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

@@ -7,8 +7,7 @@
 package org.hibernate.cache.spi;
 
 /**
- * Defines the contract for a cache region which will specifically be used to
- * store query results.
+ * Defines the contract for a cache region that stores query results.
  *
  * @author Steve Ebersole
  */