From dd28b28095c0de24aa6e880cb33c7d0db1bd4541 Mon Sep 17 00:00:00 2001
From: Robin Bygrave <robin.bygrave@gmail.com>
Date: Fri, 13 May 2016 16:30:43 +1200
Subject: [PATCH] #704 - Update javadoc for @Cache and @Query.setUseCache()

---
 src/main/java/com/avaje/ebean/Query.java            | 12 +++++++++---
 src/main/java/com/avaje/ebean/annotation/Cache.java |  5 +++++
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/avaje/ebean/Query.java b/src/main/java/com/avaje/ebean/Query.java
index c0fdf06a4..287df64e6 100644
--- a/src/main/java/com/avaje/ebean/Query.java
+++ b/src/main/java/com/avaje/ebean/Query.java
@@ -1304,10 +1304,16 @@ public interface Query<T> {
   Query<T> setMapKey(String mapKey);
 
   /**
-   * Set this to true to use the bean cache.
+   * Set this to false to not use the bean cache.
    * <p>
-   * If the query result is in cache then by default this same instance is
-   * returned. In this sense it should be treated as a read only object graph.
+   * 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.
    * </p>
    */
   Query<T> setUseCache(boolean useCache);
diff --git a/src/main/java/com/avaje/ebean/annotation/Cache.java b/src/main/java/com/avaje/ebean/annotation/Cache.java
index bce44cc6d..ea1a50f2a 100644
--- a/src/main/java/com/avaje/ebean/annotation/Cache.java
+++ b/src/main/java/com/avaje/ebean/annotation/Cache.java
@@ -28,6 +28,11 @@ public @interface Cache {
    * set this to false on a bean type that we want to use query caching but no
    * bean caching (and this is expected to be a rare case).
    * </p>
+   * <p>
+   * When bean caching is enabled by default "find by id" and "find by unique natural key"
+   * queries will try to use the bean cache. We use {@link com.avaje.ebean.Query#setUseCache(boolean)}
+   * with <code>false</code> for the case when we do NOT want to use the bean cache.
+   * </p>
    */
   boolean enableBeanCache() default true;