HHH-11356 - Adjust the 2nd-Cache SPIs to better reflect supported uses

HHH-12323 - Update Statistics API and SPI based on changes to 2nd level caching changes

documentation/src/test/java/org/hibernate/userguide/caching/SecondLevelCacheTest.java

@@ -26,10 +26,9 @@
 import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.jpa.QueryHints;
 import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
-import org.hibernate.stat.SecondLevelCacheStatistics;
+import org.hibernate.stat.CacheRegionStatistics;
 import org.hibernate.stat.Statistics;
 
-import org.hibernate.testing.FailureExpected;
 import org.junit.Ignore;
 import org.junit.Test;
 
@@ -188,8 +187,8 @@ public void testCache() {
 			Session session = entityManager.unwrap( Session.class );
 			//tag::caching-statistics-example[]
 			Statistics statistics = session.getSessionFactory().getStatistics();
-			SecondLevelCacheStatistics secondLevelCacheStatistics =
-					statistics.getSecondLevelCacheStatistics( "query.cache.person" );
+			CacheRegionStatistics secondLevelCacheStatistics =
+					statistics.getDomainDataRegionStatistics( "query.cache.person" );
 			long hitCount = secondLevelCacheStatistics.getHitCount();
 			long missCount = secondLevelCacheStatistics.getMissCount();
 			double hitRatio = (double) hitCount / ( hitCount + missCount );

documentation/src/test/java/org/hibernate/userguide/persister/CollectionPersister.java

@@ -8,7 +8,6 @@
 
 import org.hibernate.MappingException;
 import org.hibernate.cache.CacheException;
-import org.hibernate.cache.spi.access.CollectionRegionAccessStrategy;
 import org.hibernate.mapping.Collection;
 import org.hibernate.persister.collection.OneToManyPersister;
 import org.hibernate.persister.spi.PersisterCreationContext;

documentation/src/test/java/org/hibernate/userguide/persister/EntityPersister.java

@@ -7,8 +7,6 @@
 package org.hibernate.userguide.persister;
 
 import org.hibernate.HibernateException;
-import org.hibernate.cache.spi.access.EntityRegionAccessStrategy;
-import org.hibernate.cache.spi.access.NaturalIdRegionAccessStrategy;
 import org.hibernate.mapping.PersistentClass;
 import org.hibernate.persister.entity.SingleTableEntityPersister;
 import org.hibernate.persister.spi.PersisterCreationContext;

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

@@ -18,6 +18,7 @@
  *
  * @author Steve Ebersole
  */
+@SuppressWarnings( {"UnusedDeclaration"})
 public interface Cache extends javax.persistence.Cache {
 	/**
 	 * Access to the SessionFactory this Cache is bound to.
@@ -26,6 +27,11 @@ public interface Cache extends javax.persistence.Cache {
 	 */
 	SessionFactory getSessionFactory();
 
+
+
+	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	// Entity data
+
 	/**
 	 * Determine whether the cache contains data for the given entity "instance".
 	 * <p/>
@@ -58,59 +64,83 @@ public interface Cache extends javax.persistence.Cache {
 	 *
 	 * @param entityClass The entity class.
 	 * @param identifier The entity identifier
+	 *
+	 * @since 5.3
 	 */
-	void evictEntity(Class entityClass, Serializable identifier);
+	void evictEntityData(Class entityClass, Serializable identifier);
 
 	/**
 	 * Evicts the entity data for a particular entity "instance".
 	 *
 	 * @param entityName The entity name.
 	 * @param identifier The entity identifier
+	 *
+	 * @since 5.3
 	 */
-	void evictEntity(String entityName, Serializable identifier);
+	void evictEntityData(String entityName, Serializable identifier);
 
 	/**
 	 * Evicts all entity data from the given region (i.e. for all entities of
 	 * type).
 	 *
 	 * @param entityClass The entity class.
+	 *
+	 * @since 5.3
 	 */
-	void evictEntityRegion(Class entityClass);
+	void evictEntityData(Class entityClass);
 
 	/**
 	 * Evicts all entity data from the given region (i.e. for all entities of
 	 * type).
 	 *
 	 * @param entityName The entity name.
+	 *
+	 * @since 5.3
 	 */
-	void evictEntityRegion(String entityName);
+	void evictEntityData(String entityName);
 
 	/**
 	 * Evict data from all entity regions.
+	 *
+	 * @since 5.3
 	 */
-	void evictEntityRegions();
+	void evictEntityData();
+
+
+	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	// Natural-id data
+
 
 	/**
-	 * Evicts all naturalId data from the given region (i.e. for all entities of
-	 * type).
+	 * Evict cached data for the given entity's natural-id
 	 *
-	 * @param naturalIdClass The naturalId class.
+	 * @param entityClass The entity class.
+	 *
+	 * @since 5.3
 	 */
-	@SuppressWarnings( {"UnusedDeclaration"})
-	void evictNaturalIdRegion(Class naturalIdClass);
+	void evictNaturalIdData(Class entityClass);
 
 	/**
-	 * Evicts all naturalId data from the given region (i.e. for all entities of
-	 * type).
+	 * Evict cached data for the given entity's natural-id
+	 *
+	 * @param entityName The entity name.
 	 *
-	 * @param naturalIdName The naturalId name.
+	 * @since 5.3
 	 */
-	void evictNaturalIdRegion(String naturalIdName);
+	void evictNaturalIdData(String entityName);
 
 	/**
-	 * Evict data from all naturalId regions.
+	 * Evict cached data for all natural-ids (for all entities)
+	 *
+	 * @since 5.3
 	 */
-	void evictNaturalIdRegions();
+	void evictNaturalIdData();
+
+
+
+
+	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	// Collection data
 
 	/**
 	 * Determine whether the cache contains data for the given collection.
@@ -128,26 +158,38 @@ public interface Cache extends javax.persistence.Cache {
 	@SuppressWarnings( {"UnusedDeclaration"})
 	boolean containsCollection(String role, Serializable ownerIdentifier);
 
+
 	/**
-	 * Evicts the cache data for the given identified collection instance.
+	 * Evicts the cache data for the given identified collection "instance"
 	 *
 	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
 	 * @param ownerIdentifier The identifier of the owning entity
+	 *
+	 * @since 5.3
 	 */
-	void evictCollection(String role, Serializable ownerIdentifier);
+	void evictCollectionData(String role, Serializable ownerIdentifier);
 
 	/**
-	 * Evicts all entity data from the given region (i.e. evicts cached data
-	 * for all of the specified collection role).
+	 * Evicts cached data for the given collection role
 	 *
 	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
+	 *
+	 * @since 5.3
 	 */
-	void evictCollectionRegion(String role);
+	void evictCollectionData(String role);
 
 	/**
-	 * Evict data from all collection regions.
+	 * Evict cache data for all collections
+	 *
+	 * @since 5.3
 	 */
-	void evictCollectionRegions();
+	void evictCollectionData();
+
+
+
+
+	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	// Query result data
 
 	/**
 	 * Determine whether the cache contains data for the given query.
@@ -159,7 +201,6 @@ public interface Cache extends javax.persistence.Cache {
 	 *
 	 * @return True if the underlying cache contains corresponding data; false otherwise.
 	 */
-	@SuppressWarnings( {"UnusedDeclaration"})
 	boolean containsQuery(String regionName);
 
 	/**
@@ -178,9 +219,181 @@ public interface Cache extends javax.persistence.Cache {
 	 * Evict data from all query regions.
 	 */
 	void evictQueryRegions();
-
+
+
+
+	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	// Misc
+
+	/**
+	 * Evict all data from the named cache region
+	 *
+	 * @since 5.3
+	 */
+	void evictRegion(String regionName);
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @apiNote Hibernate impl - we only evict entity data here in keeping
+	 * with the JPA intent (JPA only defines caching for entity data).  For
+	 * evicting all cache regions (collections, natural-ids and query results),
+	 * use {@link #evictAllRegions} instead.
+	 */
+	@Override
+	default void evictAll() {
+		// Evict only the "JPA cache", which is purely defined as the entity regions.
+		evictEntityData();
+	}
+
+	/**
+	 * Evict data from all cache regions.
+	 */
+	default void evictAllRegions() {
+		evictEntityData();
+		evictNaturalIdData();
+		evictCollectionData();
+		evictDefaultQueryRegion();
+		evictQueryRegions();
+	}
+
+
+
+	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	// Deprecations (5.3)
+
+	/**
+	 * Evicts the entity data for a particular entity "instance".
+	 *
+	 * @param entityClass The entity class.
+	 * @param identifier The entity identifier
+	 *
+	 * @deprecated Use {@link Cache#evictEntityData(Class, Serializable)} instead
+	 */
+	@Deprecated
+	default void evictEntity(Class entityClass, Serializable identifier) {
+		evictEntityData( entityClass, identifier );
+	}
+
+	/**
+	 * Evicts the entity data for a particular entity "instance".
+	 *
+	 * @param entityName The entity name.
+	 * @param identifier The entity identifier
+	 *
+	 * @deprecated Use {@link Cache#evictEntityData(String, Serializable)} instead
+	 */
+	@Deprecated
+	default void evictEntity(String entityName, Serializable identifier) {
+		evictEntityData( entityName, identifier );
+	}
+
+	/**
+	 * Evicts all entity data from the given region (i.e. for all entities of
+	 * type).
+	 *
+	 * @param entityClass The entity class.
+	 *
+	 * @deprecated Use {@link Cache#evictEntityData(Class)} instead
+	 */
+	@Deprecated
+	default void evictEntityRegion(Class entityClass) {
+		evictEntityData( entityClass );
+	}
+
+	/**
+	 * Evicts all entity data from the given region (i.e. for all entities of
+	 * type).
+	 *
+	 * @param entityName The entity name.
+	 *
+	 * @deprecated Use {@link Cache#evictEntityData(String)} instead
+	 */
+	@Deprecated
+	default void evictEntityRegion(String entityName) {
+		evictEntityData( entityName );
+	}
+
 	/**
-	 * Evict all data from the cache.
+	 * Evict data from all entity regions.
+	 *
+	 * @deprecated Use {@link Cache#evictEntityData()} instead
 	 */
-	void evictAllRegions();
+	@Deprecated
+	default void evictEntityRegions() {
+		evictEntityData();
+	}
+
+	/**
+	 * Evicts all naturalId data from the given region (i.e. for all entities of
+	 * type).
+	 *
+	 * @param entityClass The entity class.
+	 *
+	 * @deprecated Use {@link Cache#evictNaturalIdData(Class)} instead
+	 */
+	@Deprecated
+	default void evictNaturalIdRegion(Class entityClass) {
+		evictNaturalIdData( entityClass );
+	}
+
+	/**
+	 * Evicts all naturalId data from the given region (i.e. for all entities of
+	 * type).
+	 *
+	 * @param entityName The entity name.
+	 *
+	 * @deprecated Use {@link Cache#evictNaturalIdData(String)} instead
+	 */
+	@Deprecated
+	default void evictNaturalIdRegion(String entityName) {
+		evictNaturalIdData( entityName );
+	}
+
+	/**
+	 * Evict data from all naturalId regions.
+	 *
+	 * @deprecated Use {@link Cache#evictNaturalIdData()} instead
+	 */
+	@Deprecated
+	default void evictNaturalIdRegions() {
+		evictNaturalIdData();
+	}
+
+	/**
+	 * Evicts the cache data for the given identified collection instance.
+	 *
+	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
+	 * @param ownerIdentifier The identifier of the owning entity
+	 *
+	 * @deprecated Use {@link Cache#evictCollectionData(String, Serializable)} instead
+	 */
+	@Deprecated
+	default void evictCollection(String role, Serializable ownerIdentifier) {
+		evictCollectionData( role, ownerIdentifier );
+	}
+
+	/**
+	 * Evicts all entity data from the given region (i.e. evicts cached data
+	 * for all of the specified collection role).
+	 *
+	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
+	 *
+	 * @deprecated Use {@link Cache#evictCollectionData(String)} instead
+	 */
+	@Deprecated
+	default void evictCollectionRegion(String role) {
+		evictCollectionData( role );
+	}
+
+	/**
+	 * Evict data from all collection regions.
+	 *
+	 * @deprecated Use {@link Cache#evictCollectionData()} instead
+	 */
+	@Deprecated
+	default void evictCollectionRegions() {
+		evictCollectionData();
+	}
+
 }