public class

CacheConfig

extends Object
java.lang.Object
   ↳ org.apache.http.impl.client.cache.CacheConfig

Class Overview

Java Beans-style configuration for a CachingHttpClient. Any class in the caching module that has configuration options should take a CacheConfig argument in one of its constructors. A 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 HttpClient used as the "backend" for the CachingHttpClient.

Cache configuration can be grouped into the following categories:

Cache size. If the backend storage supports these limits, you can specify the maximum number of cache entries as well as the 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 Authorization headers or responses marked with 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 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 enable heuristic caching, then specify either a default freshness lifetime and/or a 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 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 minimum and maximum number of background worker threads, as well as the maximum time they can be idle before being reclaimed. You can also control the size of the queue used for revalidations when there aren't enough workers to keep up with demand.

Summary

Constants
int DEFAULT_ASYNCHRONOUS_WORKERS_CORE Default minimum number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.
int DEFAULT_ASYNCHRONOUS_WORKERS_MAX Default number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.
int DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS Default maximum idle lifetime for a background revalidation thread before it gets reclaimed.
boolean DEFAULT_HEURISTIC_CACHING_ENABLED Default setting for heuristic caching
float DEFAULT_HEURISTIC_COEFFICIENT Default coefficient used to heuristically determine freshness lifetime from the Last-Modified time of a cache entry.
long DEFAULT_HEURISTIC_LIFETIME Default lifetime in seconds to be assumed when we cannot calculate freshness heuristically.
int DEFAULT_MAX_CACHE_ENTRIES Default setting for the maximum number of cache entries that will be retained.
int DEFAULT_MAX_OBJECT_SIZE_BYTES Default setting for the maximum object size that will be cached, in bytes.
int DEFAULT_MAX_UPDATE_RETRIES Default setting for the number of retries on a failed cache update
int DEFAULT_REVALIDATION_QUEUE_SIZE Default maximum queue length for background revalidation requests.
Public Constructors
CacheConfig()
Public Methods
int getAsynchronousWorkerIdleLifetimeSecs()
Returns the current maximum idle lifetime in seconds for a background revalidation worker thread.
int getAsynchronousWorkersCore()
Returns the minimum number of threads to keep alive for background revalidations due to the stale-while-revalidate directive.
int getAsynchronousWorkersMax()
Returns the maximum number of threads to allow for background revalidations due to the stale-while-revalidate directive.
float getHeuristicCoefficient()
Returns lifetime coefficient used in heuristic freshness caching.
long getHeuristicDefaultLifetime()
Get the default lifetime to be used if heuristic freshness calculation is not possible.
int getMaxCacheEntries()
Returns the maximum number of cache entries the cache will retain.
int getMaxObjectSizeBytes()
Returns the current maximum response body size that will be cached.
int getMaxUpdateRetries()
Returns the number of times to retry a cache update on failure
int getRevalidationQueueSize()
Returns the current maximum queue size for background revalidations.
boolean isHeuristicCachingEnabled()
Returns whether heuristic caching is enabled.
boolean isSharedCache()
Returns whether the cache will behave as a shared cache or not.
void setAsynchronousWorkerIdleLifetimeSecs(int secs)
Sets the current maximum idle lifetime in seconds for a background revalidation worker thread.
void setAsynchronousWorkersCore(int min)
Sets the minimum number of threads to keep alive for background revalidations due to the stale-while-revalidate directive.
void setAsynchronousWorkersMax(int max)
Sets the maximum number of threads to allow for background revalidations due to the stale-while-revalidate directive.
void setHeuristicCachingEnabled(boolean heuristicCachingEnabled)
Enables or disables heuristic caching.
void setHeuristicCoefficient(float heuristicCoefficient)
Sets coefficient to be used in heuristic freshness caching.
void setHeuristicDefaultLifetime(long heuristicDefaultLifetimeSecs)
Sets default lifetime in seconds to be used if heuristic freshness calculation is not possible.
void setMaxCacheEntries(int maxCacheEntries)
Sets the maximum number of cache entries the cache will retain.
void setMaxObjectSizeBytes(int maxObjectSizeBytes)
Specifies the maximum response body size that will be eligible for caching.
void setMaxUpdateRetries(int maxUpdateRetries)
Sets the number of times to retry a cache update on failure
void setRevalidationQueueSize(int size)
Sets the current maximum queue size for background revalidations.
void setSharedCache(boolean isSharedCache)
Sets whether the cache should behave as a shared cache or not.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int DEFAULT_ASYNCHRONOUS_WORKERS_CORE

Default minimum number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.

Constant Value: 1 (0x00000001)

public static final int DEFAULT_ASYNCHRONOUS_WORKERS_MAX

Default number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.

Constant Value: 1 (0x00000001)

public static final int DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS

Default maximum idle lifetime for a background revalidation thread before it gets reclaimed.

Constant Value: 60 (0x0000003c)

public static final boolean DEFAULT_HEURISTIC_CACHING_ENABLED

Default setting for heuristic caching

Constant Value: false

public static final float DEFAULT_HEURISTIC_COEFFICIENT

Default coefficient used to heuristically determine freshness lifetime from the Last-Modified time of a cache entry.

Constant Value: 0.1

public static final long DEFAULT_HEURISTIC_LIFETIME

Default lifetime in seconds to be assumed when we cannot calculate freshness heuristically.

Constant Value: 0 (0x0000000000000000)

public static final int DEFAULT_MAX_CACHE_ENTRIES

Default setting for the maximum number of cache entries that will be retained.

Constant Value: 1000 (0x000003e8)

public static final int DEFAULT_MAX_OBJECT_SIZE_BYTES

Default setting for the maximum object size that will be cached, in bytes.

Constant Value: 8192 (0x00002000)

public static final int DEFAULT_MAX_UPDATE_RETRIES

Default setting for the number of retries on a failed cache update

Constant Value: 1 (0x00000001)

public static final int DEFAULT_REVALIDATION_QUEUE_SIZE

Default maximum queue length for background revalidation requests.

Constant Value: 100 (0x00000064)

Public Constructors

public CacheConfig ()

Public Methods

public int getAsynchronousWorkerIdleLifetimeSecs ()

Returns the current maximum idle lifetime in seconds for a background revalidation worker thread. If a worker thread is idle for this long, and there are more than the core number of worker threads alive, the worker will be reclaimed.

public int getAsynchronousWorkersCore ()

Returns the minimum number of threads to keep alive for background revalidations due to the stale-while-revalidate directive.

public int getAsynchronousWorkersMax ()

Returns the maximum number of threads to allow for background revalidations due to the stale-while-revalidate directive. A value of 0 means background revalidations are disabled.

public float getHeuristicCoefficient ()

Returns lifetime coefficient used in heuristic freshness caching.

public long getHeuristicDefaultLifetime ()

Get the default lifetime to be used if heuristic freshness calculation is not possible.

public int getMaxCacheEntries ()

Returns the maximum number of cache entries the cache will retain.

public int getMaxObjectSizeBytes ()

Returns the current maximum response body size that will be cached.

Returns
  • size in bytes

public int getMaxUpdateRetries ()

Returns the number of times to retry a cache update on failure

public int getRevalidationQueueSize ()

Returns the current maximum queue size for background revalidations.

public boolean isHeuristicCachingEnabled ()

Returns whether heuristic caching is enabled.

Returns
  • true if it is enabled.

public boolean isSharedCache ()

Returns whether the cache will behave as a shared cache or not.

Returns
  • true for a shared cache, false for a non- shared (private) cache

public void setAsynchronousWorkerIdleLifetimeSecs (int secs)

Sets the current maximum idle lifetime in seconds for a background revalidation worker thread. If a worker thread is idle for this long, and there are more than the core number of worker threads alive, the worker will be reclaimed.

Parameters
secs idle lifetime in seconds

public void setAsynchronousWorkersCore (int min)

Sets the minimum number of threads to keep alive for background revalidations due to the stale-while-revalidate directive.

Parameters
min should be greater than zero and less than or equal to getAsynchronousWorkersMax()

public void setAsynchronousWorkersMax (int max)

Sets the maximum number of threads to allow for background revalidations due to the stale-while-revalidate directive.

Parameters
max number of threads; a value of 0 disables background revalidations.

public void setHeuristicCachingEnabled (boolean heuristicCachingEnabled)

Enables or disables heuristic caching.

Parameters
heuristicCachingEnabled should be true to permit heuristic caching, false to enable it.

public void setHeuristicCoefficient (float heuristicCoefficient)

Sets coefficient to be used in heuristic freshness caching. This is interpreted as the fraction of the time between the Last-Modified and Date headers of a cached response during which the cached response will be considered heuristically fresh.

Parameters
heuristicCoefficient should be between 0.0 and 1.0.

public void setHeuristicDefaultLifetime (long heuristicDefaultLifetimeSecs)

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 Last-Modified freshness calculation if it is available.

Parameters
heuristicDefaultLifetimeSecs is the number of seconds to consider a cache-eligible response fresh in the absence of other information. Set this to 0 to disable this style of heuristic caching.

public void setMaxCacheEntries (int maxCacheEntries)

Sets the maximum number of cache entries the cache will retain.

public void setMaxObjectSizeBytes (int maxObjectSizeBytes)

Specifies the maximum response body size that will be eligible for caching.

Parameters
maxObjectSizeBytes size in bytes

public void setMaxUpdateRetries (int maxUpdateRetries)

Sets the number of times to retry a cache update on failure

public void setRevalidationQueueSize (int size)

Sets the current maximum queue size for background revalidations.

public void setSharedCache (boolean isSharedCache)

Sets whether the cache should behave as a shared cache or not.

Parameters
isSharedCache true to behave as a shared cache, false to behave as a non-shared (private) cache. To have the cache behave like a browser cache, you want to set this to false.