null if nonexistent
- * @return HttpCacheEntry the cache entry that should replace it, again,
- * possibly null
+ * @return the cache entry that should replace it, again,
+ * possibly null if the entry should be deleted
*
* @since 4.1
*/
diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java
index 8a3ccad1e..56e14db43 100644
--- a/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java
+++ b/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;
diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java
index 5d857426d..09664799c 100644
--- a/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java
+++ b/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;
diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/BasicHttpCacheStorage.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/BasicHttpCacheStorage.java
index 6c0904249..f8c6dad64 100644
--- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/BasicHttpCacheStorage.java
+++ b/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}.
- * This cache does NOT deallocate resources associated with the cache entries. It is intended
- * for use with {@link HeapResource} and similar.
+ * Basic {@link HttpCacheStorage} implementation backed by an instance of
+ * {@link LinkedHashMap}. In other words, cache entries and the cached
+ * 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
*/
diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java
index 79276e820..821a51a3b 100644
--- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java
+++ b/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
- * {@link org.apache.http.impl.client.cache.CachingHttpClient}.
+ * Java Beans-style configuration for a {@link CachingHttpClient}. Any class + * 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.
+ * + *N.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 "backend" + * for the {@code CachingHttpClient}.
+ * + *Cache configuration can be grouped into the following categories:
+ * + *Cache size. 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}.
+ * + *Public/private caching. 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}.
+ * + *Heuristic caching. 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 + * + * 13.2.2 and + * 13.2.4 of the HTTP/1.1 RFC for more details on heuristic caching.
+ * + *Background validation. The cache module supports the
+ * {@code stale-while-revalidate} directive of
+ * RFC5861, 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.
*/
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)
- * cache
+ * @return {@code true} for a shared cache, {@code false} for a non-
+ * 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) {
- this.heuristicDefaultLifetime = heuristicDefaultLifetime;
+ public void setHeuristicDefaultLifetime(long heuristicDefaultLifetimeSecs) {
+ 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 getAsynchronousWorkersMax()
*/