Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.http.impl.client.cache
Class CacheConfig

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

    public class CacheConfig

extends Object

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.

Field Summary
`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.

Constructor Summary
`CacheConfig()`

Method Summary
`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` | `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` | `setMaxObjectSize(long maxObjectSize)` Specifies the maximum response body size that will be eligible for caching.
`void` | `setMaxObjectSizeBytes(int maxObjectSizeBytes)` Deprecated. (4.2) use `setMaxObjectSize(long)`
`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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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_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

Constructor Detail

### CacheConfig

    public CacheConfig()

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 `setMaxObjectSize(long)`

  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

    public void setMaxObjectSize(long maxObjectSize)

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

  Parameters:
    `maxObjectSize` - size in bytes
  Since:
    4.2

### 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

    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`.

### getMaxCacheEntries

    public int getMaxCacheEntries()

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

### setMaxCacheEntries

    public void setMaxCacheEntries(int maxCacheEntries)

  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

    public void setMaxUpdateRetries(int maxUpdateRetries)

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

### isHeuristicCachingEnabled

    public boolean isHeuristicCachingEnabled()

  Returns whether heuristic caching is enabled.

  Returns:
    `true` if it is enabled.

### setHeuristicCachingEnabled

    public void setHeuristicCachingEnabled(boolean heuristicCachingEnabled)

  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

    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`.

### getHeuristicDefaultLifetime

    public long getHeuristicDefaultLifetime()

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

### setHeuristicDefaultLifetime

    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.

### 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

    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.

### getAsynchronousWorkersCore

    public int getAsynchronousWorkersCore()

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

### setAsynchronousWorkersCore

    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()`

### 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

    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

### getRevalidationQueueSize

    public int getRevalidationQueueSize()

  Returns the current maximum queue size for background revalidations.

### setRevalidationQueueSize

    public void setRevalidationQueueSize(int size)

  Sets the current maximum queue size for background revalidations.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1999-2013 The Apache Software Foundation. All Rights Reserved.