#1215 - ENH: Add Query setBeanCacheMode(CacheMode) ... with a view to it replacing the existing setUseCache(boolean) and setLoadBeanCache(boolean)

src/main/java/io/ebean/CacheMode.java

@@ -1,41 +1,71 @@
 package io.ebean;
 
 /**
- * Enum to control the different cache modes for queryCache (and maybe later) beanCache.
+ * Enum to control the different cache modes for queryCache and beanCache.
+ * <h3>Bean cache</h3>
  * <p>
- * If cache is enabled, you must be careful, what you do with the returned collection.
+ * The bean cache is automatically used by default on <code>@Cache</code> beans for
+ * the following queries:
+ * </p>
+ * <ul>
+ * <li>findOne() by id</li>
+ * <li>findOne() by natural key(s)</li>
+ * <li>findList() by ids</li>
+ * </ul>
+ * <p>
+ * Bean caching needs to be explicitly turned on for queries that are findList() by natural keys.
+ * </p>
+ * <h3>Query cache</h3>
+ * <p>
+ * For query cache use note that you must be careful, what you do with the returned collection.
  * By default the returned collections are read only and you will get an exception if you try
  * to change them.
  * If you add ".setReadOnly(false)" to your query, you'll get a collection that is a clone from the
- * one in the cache. That means, changing does not affect the cache
+ * one in the cache. That means, changing does not affect the cache.
+ * </p>
  *
  * @author Roland Praml, FOCONIS AG
  */
 public enum CacheMode {
+
   /**
    * Do not use cache.
    */
   OFF(false, false),
 
   /**
-   * Use the cache (query & store the result).
+   * Use the cache and store a result when needed.
    */
   ON(true, true),
 
   /**
-   * Only used for bean caching. We automatically use the cache for findOne() but not findList().
+   * Only used for bean caching.
+   * <p>
+   * The bean cache is automatically used by default on <code>@Cache</code> beans for
+   * the following queries:
+   * </p>
+   * <ul>
+   * <li>findOne() by id</li>
+   * <li>findOne() by natural key(s)</li>
+   * <li>findList() by ids</li>
+   * </ul>
+   * <p>
+   * Bean caching needs to be explicitly turned on for queries that are findList() by natural keys.
+   * </p>
    */
   AUTO(true, true),
 
   /**
-   * Do not read from cache, but write retrieved value to cache.
-   * Use this, if you want to get the fresh value from database and a CacheMode.ON query will follow.
+   * Do not read from cache, but load retrieved beans into the cache.
+   * <p>
+   * Use this, if you want to get the fresh value from database into the cache. Typically a CacheMode.ON query
+   * will follow.
    */
   RECACHE(false, true),
 
   /**
-   * Query the cache for value. If it is there, use it, otherwise hit database but do NOT put the value
-   * into the cache. (this mode is for completeness. There's probably no use case for this)
+   * Query the cache for value. If it is there, use it and otherwise hit database but do NOT put the value
+   * into the cache. Note that there are not many use case for this mode.
    */
   QUERY_ONLY(true, false);
 
@@ -48,14 +78,14 @@ public enum CacheMode {
   }
 
   /**
-   * Retruns <code>true</code> if value is read from cache.
+   * Return true if value is read from cache.
    */
   public boolean isGet() {
     return get;
   }
 
   /**
-   * Returns <code>true</code> if value (from database) is written to cache.
+   * Return true if a newly loaded value (from database) is put into the cache.
    */
   public boolean isPut() {
     return put;

src/main/java/io/ebean/ExpressionList.java

@@ -457,14 +457,24 @@ public interface ExpressionList<T> {
   Query<T> setMapKey(String mapKey);
 
   /**
-   * Set to true to use the query for executing this query.
+   * Set to true when this query should use the bean cache.
+   * <p>
+   * This is now the same as setUseBeanCache(CacheMode.ON) and will be deprecated.
+   * </p>
    *
    * @see Query#setUseCache(boolean)
    */
   Query<T> setUseCache(boolean useCache);
 
   /**
-   * Set the {@link CacheMode} to use the query for executing this query.
+   * Set the mode to use the bean cache when executing this query.
+   *
+   * @see Query#setBeanCacheMode(CacheMode)
+   */
+  Query<T> setBeanCacheMode(CacheMode beanCacheMode);
+
+  /**
+   * Set the {@link CacheMode} to use the query cache for executing this query.
    *
    * @see Query#setUseQueryCache(boolean)
    */

src/main/java/io/ebean/Query.java

@@ -1305,7 +1305,7 @@ public interface Query<T> {
    *
    * // Assuming sku is unique for products...
    *
-   * Map<?,Product> productMap =
+   * Map<String,Product> productMap =
    *     ebeanServer.find(Product.class)
    *     // use sku for keys...
    *     .setMapKey("sku")
@@ -1320,22 +1320,36 @@ public interface Query<T> {
   /**
    * Set this to false to not use the bean cache.
    * <p>
+   * This method is now superseded by {@link #setBeanCacheMode(CacheMode)}
+   * which provides more explicit options controlled bean cache use.
+   * </p>
+   * <p>
+   * This method is likely to be deprecated in the future with migration
+   * over to setUseBeanCache().
+   * </p>
+   */
+  default Query<T> setUseCache(boolean useCache) {
+    return setBeanCacheMode(useCache ? CacheMode.ON : CacheMode.OFF);
+  }
+
+  /**
+   * Set the mode to use the bean cache when executing this query.
+   * <p>
    * By default "find by id" and "find by natural key" will use the bean cache
    * when bean caching is enabled. Setting this to false means that the query
    * will not use the bean cache and instead hit the database.
    * </p>
    * <p>
-   * In the case of other queries (findList(), findEach() etc) then setting this to
-   * false beans that the if lazy loading is invoked that lazy loading will not try
-   * to use the bean cache.
+   * By default findList() with natural keys will not use the bean cache. In that
+   * case we need to explicitly use the bean cache.
    * </p>
    */
-  Query<T> setUseCache(boolean useCache);
+  Query<T> setBeanCacheMode(CacheMode beanCacheMode);
 
   /**
    * Set the {@link CacheMode} to use the query for executing this query.
    */
-  Query<T> setUseQueryCache(CacheMode useQueryCache);
+  Query<T> setUseQueryCache(CacheMode queryCacheMode);
 
   /**
    * Calls {@link #setUseQueryCache(CacheMode)} with <code>ON</code> or <code>OFF</code>.
@@ -1369,8 +1383,9 @@ public interface Query<T> {
   Query<T> setReadOnly(boolean readOnly);
 
   /**
-   * When set to true all the beans from this query are loaded into the bean
-   * cache.
+   * Will be deprecated - migrate to use setBeanCacheMode(CacheMode.RECACHE).
+   * <p>
+   * When set to true all the beans from this query are loaded into the bean cache.
    */
   Query<T> setLoadBeanCache(boolean loadBeanCache);
 

src/main/java/io/ebeaninternal/server/expression/DefaultExpressionList.java

@@ -483,6 +483,11 @@ public class DefaultExpressionList<T> implements SpiExpressionList<T> {
     return query.setUseCache(useCache);
   }
 
+  @Override
+  public Query<T> setBeanCacheMode(CacheMode useCache) {
+    return query.setBeanCacheMode(useCache);
+  }
+
   @Override
   public Query<T> setUseQueryCache(CacheMode useCache) {
     return query.setUseQueryCache(useCache);

src/main/java/io/ebeaninternal/server/expression/JunctionExpression.java

@@ -767,6 +767,11 @@ class JunctionExpression<T> implements SpiJunction<T>, SpiExpression, Expression
     return exprList.setUseCache(useCache);
   }
 
+  @Override
+  public Query<T> setBeanCacheMode(CacheMode useCache) {
+    return exprList.setBeanCacheMode(useCache);
+  }
+
   @Override
   public Query<T> setUseQueryCache(CacheMode useCache) {
     return exprList.setUseQueryCache(useCache);

src/main/java/io/ebeaninternal/server/querydefn/DefaultOrmQuery.java

@@ -1135,8 +1135,8 @@ public class DefaultOrmQuery<T> implements SpiQuery<T> {
   }
 
   @Override
-  public DefaultOrmQuery<T> setUseCache(boolean useCache) {
-    this.useBeanCache = (useCache) ? CacheMode.ON: CacheMode.OFF;
+  public Query<T> setBeanCacheMode(CacheMode beanCacheMode) {
+    this.useBeanCache = beanCacheMode;
     return this;
   }