From 81d8be6e393b00b7509ffb77ab48988aa79a26b6 Mon Sep 17 00:00:00 2001
From: Gian Merlino <gianmerlino@gmail.com>
Date: Fri, 28 Feb 2020 11:30:58 -0800
Subject: [PATCH] CacheStrategy: Improve Javadocs. (#9280)

* CacheStrategy: Improve Javadocs.

* Update processing/src/main/java/org/apache/druid/query/CacheStrategy.java

Co-Authored-By: Suneet Saldanha <44787917+suneet-s@users.noreply.github.com>

Co-authored-by: Suneet Saldanha <44787917+suneet-s@users.noreply.github.com>
---
 .../org/apache/druid/query/CacheStrategy.java | 22 +++++++++++++------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/processing/src/main/java/org/apache/druid/query/CacheStrategy.java b/processing/src/main/java/org/apache/druid/query/CacheStrategy.java
index 5d7d94fd2c4..b9c0e25a952 100644
--- a/processing/src/main/java/org/apache/druid/query/CacheStrategy.java
+++ b/processing/src/main/java/org/apache/druid/query/CacheStrategy.java
@@ -30,13 +30,15 @@ import java.util.List;
 import java.util.concurrent.ExecutorService;
 
 /**
+ * Handles caching-related tasks for a particular query type.
  *
+ * Generally returned by the toolchest method {@link QueryToolChest#getCacheStrategy}.
  */
 @ExtensionPoint
 public interface CacheStrategy<T, CacheType, QueryType extends Query<T>>
 {
   /**
-   * Returns the given query is cacheable or not.
+   * Returns whether the given query is cacheable or not.
    * The {@code willMergeRunners} parameter can be used for distinguishing the caller is a broker or a data node.
    *
    * @param query            the query to be cached
@@ -48,21 +50,27 @@ public interface CacheStrategy<T, CacheType, QueryType extends Query<T>>
   boolean isCacheable(QueryType query, boolean willMergeRunners);
 
   /**
-   * Computes the cache key for the given query
+   * Computes the per-segment cache key for the given query. Because this is a per-segment cache key, it should only
+   * include parts of the query that affect the results for a specific segment (i.e., the results returned from
+   * {@link QueryRunnerFactory#createRunner}).
    *
-   * @param query the query to compute a cache key for
+   * @param query the query to be cached
    *
-   * @return the cache key
+   * @return the per-segment cache key
    */
   byte[] computeCacheKey(QueryType query);
 
   /**
-   * Computes the result level cache key for the given query.
-   * Some implementations may include query parameters that might not be used in {@code computeCacheKey} for same query
+   * Computes the result-level cache key for the given query. The result-level cache will tack on datasource and
+   * interval details, so this key does not need to include datasource and interval. But it should include anything
+   * else that might affect the results of the query.
+   *
+   * Some implementations will need to include query parameters that are not used in {@link #computeCacheKey} for the
+   * same query.
    *
    * @param query the query to be cached
    *
-   * @return the result level cache key
+   * @return the result-level cache key
    */
   byte[] computeResultLevelCacheKey(QueryType query);