+ * However, this enumeration recognizes only five such combinations. In Hibernate, + * {@link CacheStoreMode#REFRESH} always implies {@link CacheRetrieveMode#BYPASS}, + * so there's no {@code CacheMode} representing the combination + * {@code (REFRESH, USE)}. * * @author Gavin King * @author Strong Liu + * * @see Session#setCacheMode(CacheMode) + * @see org.hibernate.query.SelectionQuery#setCacheMode(CacheMode) + * @see CacheStoreMode + * @see CacheRetrieveMode */ public enum CacheMode { /** - * The session may read items from the cache, and add items to the cache. + * The session may read items from the cache, and add items to the cache + * as it reads them from the database. */ NORMAL( CacheStoreMode.USE, CacheRetrieveMode.USE ), /** * The session will never interact with the cache, except to invalidate - * cache items when updates occur. + * cached items when updates occur. */ IGNORE( CacheStoreMode.BYPASS, CacheRetrieveMode.BYPASS ), /** @@ -34,14 +48,24 @@ public enum CacheMode { GET( CacheStoreMode.BYPASS, CacheRetrieveMode.USE ), /** * The session will never read items from the cache, but will add items - * to the cache as it reads them from the database. + * to the cache as it reads them from the database. In this mode, the + * value of the configuration setting + * {@value org.hibernate.cfg.AvailableSettings#USE_MINIMAL_PUTS} + * determines whether an item is written to the cache when the cache + * already contains an entry with the same key. + * + * @see org.hibernate.boot.SessionFactoryBuilder#applyStructuredCacheEntries(boolean) */ PUT( CacheStoreMode.USE, CacheRetrieveMode.BYPASS ), /** - * The session will never read items from the cache, but will add items - * to the cache as it reads them from the database. In this mode, the - * effect of {@code hibernate.cache.use_minimal_puts} is bypassed, in - * order to force a cache refresh. + * As with to {@link #PUT}, the session will never read items from the + * cache, but will add items to the cache as it reads them from the + * database. But in this mode, the effect of the configuration setting + * {@value org.hibernate.cfg.AvailableSettings#USE_MINIMAL_PUTS} is + * bypassed, in order to force a refresh of a cached item, + * even when an entry with the same key already exists in the cache. + * + * @see org.hibernate.boot.SessionFactoryBuilder#applyStructuredCacheEntries(boolean) */ REFRESH( CacheStoreMode.REFRESH, CacheRetrieveMode.BYPASS ); @@ -53,10 +77,16 @@ public enum CacheMode { this.retrieveMode = retrieveMode; } + /** + * @return the JPA-defined {@link CacheStoreMode} implied by this cache mode + */ public CacheStoreMode getJpaStoreMode() { return storeMode; } + /** + * @return the JPA-defined {@link CacheRetrieveMode} implied by this cache mode + */ public CacheRetrieveMode getJpaRetrieveMode() { return retrieveMode; } @@ -80,10 +110,9 @@ public enum CacheMode { } /** - * Used to interpret externalized forms of this enum. + * Interpret externalized form as an instance of this enumeration. * * @param setting The externalized form. - * * @return The matching enum value. * * @throws MappingException Indicates the external form was not recognized as a valid enum value. @@ -101,6 +130,9 @@ public enum CacheMode { } } + /** + * Interpret the given JPA modes as an instance of this enumeration. + */ public static CacheMode fromJpaModes(CacheRetrieveMode retrieveMode, CacheStoreMode storeMode) { if ( retrieveMode == null && storeMode == null ) { return null; diff --git a/hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java b/hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java index 8301b28cb1..a72c37f9e5 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java @@ -461,7 +461,7 @@ public interface SessionFactoryBuilder { * major adverse performance impact. For these caches, it is best to enable this "minimal puts" * feature. *
- * Cache integrations also report whether "minimal puts" should be enabled by default. So its is + * Cache integrations also report whether "minimal puts" should be enabled by default. So it's * very rare that users need to set this, generally speaking. * * @param enabled {@code true} indicates Hibernate should first check whether data exists and only @@ -480,7 +480,7 @@ public interface SessionFactoryBuilder { * that format is impossible to "read" if browsing the cache. The use of "structured" cache * entries allows the cached data to be read. * - * @param enabled {@code true} indicates that structured cache entries (human readable) should be used; + * @param enabled {@code true} indicates that structured (human-readable) cache entries should be used; * {@code false} indicates that the native entry structure should be used. * * @return {@code this}, for method chaining diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java index 852c16a634..1aa6a18f69 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java @@ -1309,7 +1309,7 @@ public interface AvailableSettings { /** * Optimize interaction with the second-level cache to minimize writes, at the cost - * of more frequent database reads. + * of an additional read before each write. * * @see org.hibernate.boot.SessionFactoryBuilder#applyMinimalPutsForCaching(boolean) */