Added more Javadocs, including, most significantly so far, detailed

docs for CacheConfig talking about all the available configuration
options for the caching module.


git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1057242 13f79535-47bb-0310-9956-ffa450edef68

httpclient-cache/src/main/java/org/apache/http/client/cache/CacheResponseStatus.java

@@ -31,7 +31,8 @@ package org.apache.http.client.cache;
  * by the {@link org.apache.http.impl.client.cache.CachingHttpClient}; 
  * if a request is executed with an {@link org.apache.http.protocol.HttpContext}
  * then a parameter with one of these values will be registered in the
- * context.
+ * context under the key
+ * {@link org.apache.http.impl.client.cache.CachingHttpClient#CACHE_RESPONSE_STATUS}.
  */
 public enum CacheResponseStatus {
 

httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java

@@ -287,6 +287,10 @@ public class HttpCacheEntry implements Serializable {
         return Collections.unmodifiableMap(variantMap);
     }
 
+    /**
+     * Provides a string representation of this instance suitable for
+     * human consumption.
+     */
     @Override
     public String toString() {
         return "[request date=" + this.requestDate + "; response date=" + this.responseDate

httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java

@@ -37,8 +37,18 @@ import java.io.OutputStream;
  */
 public interface HttpCacheEntrySerializer {
 
-    public void writeTo(HttpCacheEntry entry, OutputStream os) throws IOException;
+    /**
+     * Serializes the given entry to a byte representation on the
+     * given {@link OutputStream}.
+     * @throws IOException
+     */
+    void writeTo(HttpCacheEntry entry, OutputStream os) throws IOException;
 
-    public HttpCacheEntry readFrom(InputStream is) throws IOException;
+    /**
+     * Deserializes a byte representation of a cache entry by reading
+     * from the given {@link InputStream}.
+     * @throws IOException
+     */
+    HttpCacheEntry readFrom(InputStream is) throws IOException;
 
 }

httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java

@@ -65,10 +65,13 @@ public interface HttpCacheStorage {
     void removeEntry(String key) throws IOException;
 
     /**
-     * Atomically applies the given callback to update an
+     * Atomically applies the given callback to update an existing cache
-     * existing cache entry under a given key.
+     * entry under a given key.
      * @param key indicates which entry to modify
-     * @param callback performs the update
+     * @param callback performs the update; see 
+     *   {@link HttpCacheUpdateCallback} for details, but roughly the
+     *   callback expects to be handed the current entry and will return
+     *   the new value for the entry.
      * @throws IOException
      * @throws HttpCacheUpdateException
      */

httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java

@@ -42,8 +42,8 @@ public interface HttpCacheUpdateCallback {
      * @param existing
      *            the cache entry currently in-place in the cache, possibly
      *            <code>null</code> if nonexistent
-     * @return HttpCacheEntry the cache entry that should replace it, again,
+     * @return the cache entry that should replace it, again,
-     *         possibly <code>null</code>
+     *         possibly <code>null</code> if the entry should be deleted
      *
      * @since 4.1
      */

httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java

@@ -40,7 +40,7 @@ public interface Resource extends Serializable {
 
     /**
      * Returns an {@link InputStream} from which the response
-     * body can be returned.
+     * body can be read.
      * @throws IOException
      */
     InputStream getInputStream() throws IOException;

httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java

@@ -59,7 +59,7 @@ public interface ResourceFactory {
      * @param requestId unique identifier provided to associate
      *   with the cloned response body.
      * @param resource the original response body to clone.
-     * @return {@code Resource}
+     * @return the {@code Resource} copy
      * @throws IOException
      */
     Resource copy(String requestId, Resource resource) throws IOException;

httpclient-cache/src/main/java/org/apache/http/impl/client/cache/BasicHttpCacheStorage.java

@@ -35,9 +35,12 @@ import org.apache.http.client.cache.HttpCacheStorage;
 import org.apache.http.client.cache.HttpCacheUpdateCallback;
 
 /**
- * Basic {@link HttpCacheStorage} implementation backed by an instance of {@link LinkedHashMap}.
+ * Basic {@link HttpCacheStorage} implementation backed by an instance of
- * This cache does NOT deallocate resources associated with the cache entries. It is intended
+ * {@link LinkedHashMap}. In other words, cache entries and the cached
- * for use with {@link HeapResource} and similar.
+ * response bodies are held in-memory. This cache does NOT deallocate
+ * resources associated with the cache entries; it is intended for use
+ * with {@link HeapResource} and similar. This is the default cache
+ * storage backend used by {@link CachingHttpClient}.
  *
  * @since 4.1
  */

httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java

@@ -27,8 +27,59 @@
 package org.apache.http.impl.client.cache;
 
 /**
- * Java Beans-style configuration for a
+ * <p>Java Beans-style configuration for a {@link CachingHttpClient}. Any class
- * {@link org.apache.http.impl.client.cache.CachingHttpClient}.
+ * in the caching module that has configuration options should take a
+ * {@link CacheConfig} argument in one of its constructors. A
+ * {@code CacheConfig} instance has sane and conservative defaults, so the
+ * easiest way to specify options is to get an instance and then set just
+ * the options you want to modify from their defaults.</p>
+ * 
+ * <p><b>N.B.</b> This class is only for caching-specific configuration; to
+ * configure the behavior of the rest of the client, configure the 
+ * {@link org.apache.http.client.HttpClient} used as the &quot;backend&quot;
+ * for the {@code CachingHttpClient}.</p>
+ * 
+ * <p>Cache configuration can be grouped into the following categories:</p>
+ * 
+ * <p><b>Cache size.</b> If the backend storage supports these limits, you
+ * can specify the {@link CacheConfig#setMaxCacheEntries maximum number of
+ * cache entries} as well as the {@link CacheConfig#setMaxObjectSizeBytes
+ * maximum cacheable response body size}.</p>
+ * 
+ * <p><b>Public/private caching.</b> By default, the caching module considers
+ * itself to be a shared (public) cache, and will not, for example, cache
+ * responses to requests with {@code Authorization} headers or responses
+ * marked with {@code Cache-Control: private}. If, however, the cache
+ * is only going to be used by one logical "user" (behaving similarly to a
+ * browser cache), then you will want to {@link
+ * CacheConfig#setSharedCache(boolean) turn off the shared cache setting}.</p>
+ * 
+ * <p><b>Heuristic caching</b>. Per RFC2616, a cache may cache certain cache
+ * entries even if no explicit cache control headers are set by the origin.
+ * This behavior is off by default, but you may want to turn this on if you
+ * are working with an origin that doesn't set proper headers but where you
+ * still want to cache the responses. You will want to {@link
+ * CacheConfig#setHeuristicCachingEnabled(boolean) enable heuristic caching},
+ * then specify either a {@link CacheConfig#setHeuristicDefaultLifetime(long)
+ * default freshness lifetime} and/or a {@link
+ * CacheConfig#setHeuristicCoefficient(float) fraction of the time since
+ * the resource was last modified}. See Sections
+ * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.2.2">
+ * 13.2.2</a> and <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.2.4">
+ * 13.2.4</a> of the HTTP/1.1 RFC for more details on heuristic caching.</p>
+ * 
+ * <p><b>Background validation</b>. The cache module supports the
+ * {@code stale-while-revalidate} directive of
+ * <a href="http://tools.ietf.org/html/rfc5861">RFC5861</a>, which allows
+ * certain cache entry revalidations to happen in the background. You may
+ * want to tweak the settings for the {@link
+ * CacheConfig#setAsynchronousWorkersCore(int) minimum} and {@link
+ * CacheConfig#setAsynchronousWorkersMax(int) maximum} number of background
+ * worker threads, as well as the {@link
+ * CacheConfig#setAsynchronousWorkerIdleLifetimeSecs(int) maximum time they
+ * can be idle before being reclaimed}. You can also control the {@link
+ * CacheConfig#setRevalidationQueueSize(int) size of the queue} used for
+ * revalidations when there aren't enough workers to keep up with demand.</b> 
  */
 public class CacheConfig {
 
@@ -64,21 +115,21 @@ public class CacheConfig {
     /** Default number of worker threads to allow for background revalidations
      * resulting from the stale-while-revalidate directive.
      */
-    private static final int DEFAULT_ASYNCHRONOUS_WORKERS_MAX = 1; 
+    public static final int DEFAULT_ASYNCHRONOUS_WORKERS_MAX = 1; 
 
     /** Default minimum number of worker threads to allow for background
      * revalidations resulting from the stale-while-revalidate directive.
      */
-    private static final int DEFAULT_ASYNCHRONOUS_WORKERS_CORE = 1;
+    public static final int DEFAULT_ASYNCHRONOUS_WORKERS_CORE = 1;
     
     /** Default maximum idle lifetime for a background revalidation thread
      * before it gets reclaimed.
      */
-    private static final int DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS = 60;
+    public static final int DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS = 60;
     
     /** Default maximum queue length for background revalidation requests. 
      */
-    private static final int DEFAULT_REVALIDATION_QUEUE_SIZE = 100;
+    public static final int DEFAULT_REVALIDATION_QUEUE_SIZE = 100;
     
     private int maxObjectSizeBytes = DEFAULT_MAX_OBJECT_SIZE_BYTES;
     private int maxCacheEntries = DEFAULT_MAX_CACHE_ENTRIES;
@@ -93,7 +144,7 @@ public class CacheConfig {
     private int revalidationQueueSize = DEFAULT_REVALIDATION_QUEUE_SIZE;
 
     /**
-     * Returns the current maximum object size that will be cached.
+     * Returns the current maximum response body size that will be cached.
      * @return size in bytes
      */
     public int getMaxObjectSizeBytes() {
@@ -101,7 +152,7 @@ public class CacheConfig {
     }
 
     /**
-     * Specifies the maximum object size that will be eligible for caching.
+     * Specifies the maximum response body size that will be eligible for caching.
      * @param maxObjectSizeBytes size in bytes
      */
     public void setMaxObjectSizeBytes(int maxObjectSizeBytes) {
@@ -110,8 +161,8 @@ public class CacheConfig {
 
     /**
      * Returns whether the cache will behave as a shared cache or not.
-     * @return true for a shared cache, false for a non-shared (private)
+     * @return {@code true} for a shared cache, {@code false} for a non-
-     * cache
+     * shared (private) cache
      */
     public boolean isSharedCache() {
         return isSharedCache;
@@ -120,7 +171,8 @@ public class CacheConfig {
     /**
      * Sets whether the cache should behave as a shared cache or not.
      * @param isSharedCache true to behave as a shared cache, false to
-     * behave as a non-shared (private) cache.
+     * behave as a non-shared (private) cache. To have the cache
+     * behave like a browser cache, you want to set this to {@code false}.
      */
     public void setSharedCache(boolean isSharedCache) {
         this.isSharedCache = isSharedCache;
@@ -155,28 +207,36 @@ public class CacheConfig {
     }
 
     /**
-     * Returns if heuristic freshness caching is in enabled
+     * Returns whether heuristic caching is enabled.
+     * @return {@code true} if it is enabled.
      */
     public boolean isHeuristicCachingEnabled() {
         return heuristicCachingEnabled;
     }
 
     /**
-     * Set if heuristic freshness caching is enabled
+     * Enables or disables heuristic caching.
+     * @param heuristicCachingEnabled should be {@code true} to
+     *   permit heuristic caching, {@code false} to enable it.
      */
     public void setHeuristicCachingEnabled(boolean heuristicCachingEnabled) {
         this.heuristicCachingEnabled = heuristicCachingEnabled;
     }
 
     /**
-     * Returns coefficient used in heuristic freshness caching
+     * Returns lifetime coefficient used in heuristic freshness caching.
      */
     public float getHeuristicCoefficient() {
         return heuristicCoefficient;
     }
 
     /**
-     * Set coefficient to be used in heuristic freshness caching
+     * Sets coefficient to be used in heuristic freshness caching. This is
+     * interpreted as the fraction of the time between the {@code Last-Modified}
+     * and {@code Date} headers of a cached response during which the cached
+     * response will be considered heuristically fresh.
+     * @param heuristicCoefficient should be between {@code 0.0} and
+     *   {@code 1.0}. 
      */
     public void setHeuristicCoefficient(float heuristicCoefficient) {
         this.heuristicCoefficient = heuristicCoefficient;
@@ -184,22 +244,30 @@ public class CacheConfig {
 
     /**
      * Get the default lifetime to be used if heuristic freshness calculation is
-     * not possible
+     * not possible.
      */
     public long getHeuristicDefaultLifetime() {
         return heuristicDefaultLifetime;
     }
 
     /**
-     * Set default lifetime to be used if heuristic freshness calculation is not possible
+     * Sets default lifetime in seconds to be used if heuristic freshness
+     * calculation is not possible. Explicit cache control directives on
+     * either the request or origin response will override this, as will
+     * the heuristic {@code Last-Modified} freshness calculation if it is
+     * available. 
+     * @param heuristicDefaultLifetimeSecs is the number of seconds to
+     *   consider a cache-eligible response fresh in the absence of other
+     *   information. Set this to {@code 0} to disable this style of
+     *   heuristic caching.
      */
-    public void setHeuristicDefaultLifetime(long heuristicDefaultLifetime) {
+    public void setHeuristicDefaultLifetime(long heuristicDefaultLifetimeSecs) {
-        this.heuristicDefaultLifetime = heuristicDefaultLifetime;
+        this.heuristicDefaultLifetime = heuristicDefaultLifetimeSecs;
     }
 
     /**
      * Returns the maximum number of threads to allow for background
-     * revalidations due to the stale-while-revalidate directive. A
+     * revalidations due to the {@code stale-while-revalidate} directive. A
      * value of 0 means background revalidations are disabled.
      */
     public int getAsynchronousWorkersMax() {
@@ -208,7 +276,7 @@ public class CacheConfig {
 
     /**
      * Sets the maximum number of threads to allow for background
-     * revalidations due to the stale-while-revalidate directive. 
+     * revalidations due to the {@code stale-while-revalidate} directive. 
      * @param max number of threads; a value of 0 disables background
      * revalidations. 
      */
@@ -218,7 +286,7 @@ public class CacheConfig {
 
     /**
      * Returns the minimum number of threads to keep alive for background
-     * revalidations due to the stale-while-revalidate directive. 
+     * revalidations due to the {@code stale-while-revalidate} directive. 
      */
     public int getAsynchronousWorkersCore() {
         return asynchronousWorkersCore;
@@ -226,7 +294,7 @@ public class CacheConfig {
 
     /**
      * Sets the minimum number of threads to keep alive for background
-     * revalidations due to the stale-while-revalidate directive.
+     * revalidations due to the {@code stale-while-revalidate} directive.
      * @param min should be greater than zero and less than or equal
      *   to <code>getAsynchronousWorkersMax()</code> 
      */