CacheConfig (HttpComponents Client 4.3 API)

java.lang.Object
- org.apache.http.impl.client.cache.CacheConfig

All Implemented Interfaces:

Cloneable
```
public class CacheConfig
extends Object
implements Cloneable
```
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.

303 caching. RFC2616 explicitly disallows caching 303 responses; however, the HTTPbis working group says they can be cached if explicitly indicated in the response headers and permitted by the request method. (They also indicate that disallowing 303 caching is actually an unintended spec error in RFC2616). This behavior is off by default, to err on the side of a conservative adherence to the existing standard, but you may want to enable it.
Weak ETags on PUT/DELETE If-Match requests. RFC2616 explicitly prohibits the use of weak validators in non-GET requests, however, the HTTPbis working group says while the limitation for weak validators on ranged requests makes sense, weak ETag validation is useful on full non-GET requests; e.g., PUT with If-Match. This behavior is off by default, to err on the side of a conservative adherence to the existing standard, but you may want to enable it.
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.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CacheConfig.Builder

Nested Classes
Modifier and Type	Class and Description
`static class`	`CacheConfig.Builder`

Field Summary

Fields
Modifier and Type	Field and Description
`static CacheConfig`	`DEFAULT`
`static boolean`	`DEFAULT_303_CACHING_ENABLED` Default setting for 303 caching
`static int`	`DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS` Default maximum idle lifetime for a background revalidation thread before it gets reclaimed.
`static int`	`DEFAULT_ASYNCHRONOUS_WORKERS_CORE` Default minimum number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.
`static int`	`DEFAULT_ASYNCHRONOUS_WORKERS_MAX` Default number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.
`static boolean`	`DEFAULT_HEURISTIC_CACHING_ENABLED` Default setting for heuristic caching
`static float`	`DEFAULT_HEURISTIC_COEFFICIENT` Default coefficient used to heuristically determine freshness lifetime from the Last-Modified time of a cache entry.
`static long`	`DEFAULT_HEURISTIC_LIFETIME` Default lifetime in seconds to be assumed when we cannot calculate freshness heuristically.
`static int`	`DEFAULT_MAX_CACHE_ENTRIES` Default setting for the maximum number of cache entries that will be retained.
`static int`	`DEFAULT_MAX_OBJECT_SIZE_BYTES` Default setting for the maximum object size that will be cached, in bytes.
`static int`	`DEFAULT_MAX_UPDATE_RETRIES` Default setting for the number of retries on a failed cache update
`static int`	`DEFAULT_REVALIDATION_QUEUE_SIZE` Default maximum queue length for background revalidation requests.
`static boolean`	`DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED` Default setting to allow weak tags on PUT/DELETE methods

Constructor Summary

Constructors
Constructor and Description

CacheConfig()
Deprecated.
(4.3) use CacheConfig.Builder.

Constructors
Constructor and Description
`CacheConfig()` Deprecated. (4.3) use `CacheConfig.Builder`.

Method Summary

Methods
Modifier and Type	Method and Description
`protected CacheConfig`	`clone()`
`static CacheConfig.Builder`	`copy(CacheConfig config)`
`static CacheConfig.Builder`	`custom()`
`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.
`long`	`getMaxObjectSize()` Returns the current maximum response body size that will be cached.
`int`	`getMaxObjectSizeBytes()` Deprecated. (4.2) use `getMaxObjectSize()`
`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`	`is303CachingEnabled()` Returns whether 303 caching is enabled.
`boolean`	`isHeuristicCachingEnabled()` Returns whether heuristic caching is enabled.
`boolean`	`isNeverCacheHTTP10ResponsesWithQuery()` Returns whether the cache will never cache HTTP 1.0 responses with a query string or not.
`boolean`	`isSharedCache()` Returns whether the cache will behave as a shared cache or not.
`boolean`	`isWeakETagOnPutDeleteAllowed()` Returns whether weak etags is allowed with PUT/DELETE methods.
`void`	`setAsynchronousWorkerIdleLifetimeSecs(int secs)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setAsynchronousWorkersCore(int min)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setAsynchronousWorkersMax(int max)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setHeuristicCachingEnabled(boolean heuristicCachingEnabled)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setHeuristicCoefficient(float heuristicCoefficient)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setHeuristicDefaultLifetime(long heuristicDefaultLifetimeSecs)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setMaxCacheEntries(int maxCacheEntries)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setMaxObjectSize(long maxObjectSize)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setMaxObjectSizeBytes(int maxObjectSizeBytes)` Deprecated. (4.2) use `CacheConfig.Builder`.
`void`	`setMaxUpdateRetries(int maxUpdateRetries)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setRevalidationQueueSize(int size)` Deprecated. (4.3) use `CacheConfig.Builder`.
`void`	`setSharedCache(boolean isSharedCache)` Deprecated. (4.3) use `CacheConfig.Builder`.
`String`	`toString()`

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_MAX_OBJECT_SIZE_BYTES
```
public static final int DEFAULT_MAX_OBJECT_SIZE_BYTES
```
    Default setting for the maximum object size that will be cached, in bytes.
    
    See Also:
    Constant Field Values
  - DEFAULT_MAX_CACHE_ENTRIES
```
public static final int DEFAULT_MAX_CACHE_ENTRIES
```
    Default setting for the maximum number of cache entries that will be retained.
    
    See Also:
    Constant Field Values
  - DEFAULT_MAX_UPDATE_RETRIES
```
public static final int DEFAULT_MAX_UPDATE_RETRIES
```
    Default setting for the number of retries on a failed cache update
    
    See Also:
    Constant Field Values
  - DEFAULT_303_CACHING_ENABLED
```
public static final boolean DEFAULT_303_CACHING_ENABLED
```
    Default setting for 303 caching
    
    See Also:
    Constant Field Values
  - DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED
```
public static final boolean DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED
```
    Default setting to allow weak tags on PUT/DELETE methods
    
    See Also:
    Constant Field Values
  - DEFAULT_HEURISTIC_CACHING_ENABLED
```
public static final boolean DEFAULT_HEURISTIC_CACHING_ENABLED
```
    Default setting for heuristic caching
    
    See Also:
    Constant Field Values
  - DEFAULT_HEURISTIC_COEFFICIENT
```
public static final float DEFAULT_HEURISTIC_COEFFICIENT
```
    Default coefficient used to heuristically determine freshness lifetime from the Last-Modified time of a cache entry.
    
    See Also:
    Constant Field Values
  - DEFAULT_HEURISTIC_LIFETIME
```
public static final long DEFAULT_HEURISTIC_LIFETIME
```
    Default lifetime in seconds to be assumed when we cannot calculate freshness heuristically.
    
    See Also:
    Constant Field Values
  - DEFAULT_ASYNCHRONOUS_WORKERS_MAX
```
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.
    
    See Also:
    Constant Field Values
  - DEFAULT_ASYNCHRONOUS_WORKERS_CORE
```
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.
    
    See Also:
    Constant Field Values
  - DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS
```
public static final int DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS
```
    Default maximum idle lifetime for a background revalidation thread before it gets reclaimed.
    
    See Also:
    Constant Field Values
  - DEFAULT_REVALIDATION_QUEUE_SIZE
```
public static final int DEFAULT_REVALIDATION_QUEUE_SIZE
```
    Default maximum queue length for background revalidation requests.
    
    See Also:
    Constant Field Values
  - DEFAULT
```
public static final CacheConfig DEFAULT
```
- Constructor Detail
  - CacheConfig
```
@Deprecated
public CacheConfig()
```
    Deprecated. (4.3) use CacheConfig.Builder.
- Method Detail
  - getMaxObjectSizeBytes
```
@Deprecated
public int getMaxObjectSizeBytes()
```
    Deprecated. (4.2) use getMaxObjectSize()
    
    Returns the current maximum response body size that will be cached.
    
    Returns:
    size in bytes
  - setMaxObjectSizeBytes
```
@Deprecated
public void setMaxObjectSizeBytes(int maxObjectSizeBytes)
```
    Deprecated. (4.2) use CacheConfig.Builder.
    
    Specifies the maximum response body size that will be eligible for caching.
    
    Parameters:
    maxObjectSizeBytes - size in bytes
  - getMaxObjectSize
```
public long getMaxObjectSize()
```
    Returns the current maximum response body size that will be cached.
    
    Returns:
    size in bytes
    Since:
    
    4.2
  - setMaxObjectSize
```
@Deprecated
public void setMaxObjectSize(long maxObjectSize)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    Specifies the maximum response body size that will be eligible for caching.
    
    Parameters:
    maxObjectSize - size in bytes
    Since:
    
    4.2
  - isNeverCacheHTTP10ResponsesWithQuery
```
public boolean isNeverCacheHTTP10ResponsesWithQuery()
```
    Returns whether the cache will never cache HTTP 1.0 responses with a query string or not.
    
    Returns:
    true to not cache query string responses, false to cache if explicit cache headers are found
  - getMaxCacheEntries
```
public int getMaxCacheEntries()
```
    Returns the maximum number of cache entries the cache will retain.
  - setMaxCacheEntries
```
@Deprecated
public void setMaxCacheEntries(int maxCacheEntries)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    Sets the maximum number of cache entries the cache will retain.
  - getMaxUpdateRetries
```
public int getMaxUpdateRetries()
```
    Returns the number of times to retry a cache update on failure
  - setMaxUpdateRetries
```
@Deprecated
public void setMaxUpdateRetries(int maxUpdateRetries)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    Sets the number of times to retry a cache update on failure
  - is303CachingEnabled
```
public boolean is303CachingEnabled()
```
    Returns whether 303 caching is enabled.
    
    Returns:
    true if it is enabled.
  - isWeakETagOnPutDeleteAllowed
```
public boolean isWeakETagOnPutDeleteAllowed()
```
    Returns whether weak etags is allowed with PUT/DELETE methods.
    
    Returns:
    true if it is allowed.
  - isHeuristicCachingEnabled
```
public boolean isHeuristicCachingEnabled()
```
    Returns whether heuristic caching is enabled.
    
    Returns:
    true if it is enabled.
  - setHeuristicCachingEnabled
```
@Deprecated
public void setHeuristicCachingEnabled(boolean heuristicCachingEnabled)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    Enables or disables heuristic caching.
    
    Parameters:
    heuristicCachingEnabled - should be true to permit heuristic caching, false to enable it.
  - getHeuristicCoefficient
```
public float getHeuristicCoefficient()
```
    Returns lifetime coefficient used in heuristic freshness caching.
  - setHeuristicCoefficient
```
@Deprecated
public void setHeuristicCoefficient(float heuristicCoefficient)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    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.
  - getHeuristicDefaultLifetime
```
public long getHeuristicDefaultLifetime()
```
    Get the default lifetime to be used if heuristic freshness calculation is not possible.
  - setHeuristicDefaultLifetime
```
@Deprecated
public void setHeuristicDefaultLifetime(long heuristicDefaultLifetimeSecs)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    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.
  - isSharedCache
```
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
  - setSharedCache
```
@Deprecated
public void setSharedCache(boolean isSharedCache)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    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.
  - getAsynchronousWorkersMax
```
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.
  - setAsynchronousWorkersMax
```
@Deprecated
public void setAsynchronousWorkersMax(int max)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    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.
  - getAsynchronousWorkersCore
```
public int getAsynchronousWorkersCore()
```
    Returns the minimum number of threads to keep alive for background revalidations due to the stale-while-revalidate directive.
  - setAsynchronousWorkersCore
```
@Deprecated
public void setAsynchronousWorkersCore(int min)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    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()
  - getAsynchronousWorkerIdleLifetimeSecs
```
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.
  - setAsynchronousWorkerIdleLifetimeSecs
```
@Deprecated
public void setAsynchronousWorkerIdleLifetimeSecs(int secs)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    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
  - getRevalidationQueueSize
```
public int getRevalidationQueueSize()
```
    Returns the current maximum queue size for background revalidations.
  - setRevalidationQueueSize
```
@Deprecated
public void setRevalidationQueueSize(int size)
```
    Deprecated. (4.3) use CacheConfig.Builder.
    
    Sets the current maximum queue size for background revalidations.
  - clone
```
protected CacheConfig clone()
                     throws CloneNotSupportedException
```
    Overrides:
    
    clone in class Object
    
    Throws:
    
    CloneNotSupportedException
  - custom
```
public static CacheConfig.Builder custom()
```
  - copy
```
public static CacheConfig.Builder copy(CacheConfig config)
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class CacheConfig

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MAX_OBJECT_SIZE_BYTES

DEFAULT_MAX_CACHE_ENTRIES

DEFAULT_MAX_UPDATE_RETRIES

DEFAULT_303_CACHING_ENABLED

DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED

DEFAULT_HEURISTIC_CACHING_ENABLED

DEFAULT_HEURISTIC_COEFFICIENT

DEFAULT_HEURISTIC_LIFETIME

DEFAULT_ASYNCHRONOUS_WORKERS_MAX

DEFAULT_ASYNCHRONOUS_WORKERS_CORE

DEFAULT_ASYNCHRONOUS_WORKER_IDLE_LIFETIME_SECS

DEFAULT_REVALIDATION_QUEUE_SIZE

DEFAULT

Constructor Detail

CacheConfig

Method Detail

getMaxObjectSizeBytes

setMaxObjectSizeBytes

getMaxObjectSize

setMaxObjectSize

isNeverCacheHTTP10ResponsesWithQuery

getMaxCacheEntries

setMaxCacheEntries

getMaxUpdateRetries

setMaxUpdateRetries

is303CachingEnabled

isWeakETagOnPutDeleteAllowed

isHeuristicCachingEnabled

setHeuristicCachingEnabled

getHeuristicCoefficient

setHeuristicCoefficient

getHeuristicDefaultLifetime

setHeuristicDefaultLifetime

isSharedCache

setSharedCache

getAsynchronousWorkersMax

setAsynchronousWorkersMax

getAsynchronousWorkersCore

setAsynchronousWorkersCore

getAsynchronousWorkerIdleLifetimeSecs

setAsynchronousWorkerIdleLifetimeSecs

getRevalidationQueueSize

setRevalidationQueueSize

clone

custom

copy

toString