public class CacheConfig extends Object implements Cloneable
Java Beans-style configuration for caching HttpClient
.
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 getMaxObjectSize()
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 isSharedCache()
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 isHeuristicCachingEnabled()
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. Asynchronous
validation is enabled by default but it could be disabled by setting the number
of re-validation workers to 0
with getAsynchronousWorkers()
parameter
Modifier and Type | Class and Description |
---|---|
static class |
CacheConfig.Builder |
Modifier and Type | Field and Description |
---|---|
static CacheConfig |
DEFAULT |
static boolean |
DEFAULT_303_CACHING_ENABLED
Default setting for 303 caching
|
static int |
DEFAULT_ASYNCHRONOUS_WORKERS
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 org.apache.hc.core5.util.TimeValue |
DEFAULT_HEURISTIC_LIFETIME
Default lifetime 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 processChallenge
|
static boolean |
DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED
Default setting to allow weak tags on PUT/DELETE methods
|
Modifier and Type | Method and Description |
---|---|
protected CacheConfig |
clone() |
static CacheConfig.Builder |
copy(CacheConfig config) |
static CacheConfig.Builder |
custom() |
int |
getAsynchronousWorkers()
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.
|
org.apache.hc.core5.util.TimeValue |
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 |
getMaxUpdateRetries()
Returns the number of times to retry a cache processChallenge on failure
|
boolean |
is303CachingEnabled()
Returns whether 303 caching is enabled.
|
boolean |
isFreshnessCheckEnabled()
Returns whether the cache will perform an extra cache entry freshness check
upon cache update in case of a cache miss
|
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.
|
String |
toString() |
public static final int DEFAULT_MAX_OBJECT_SIZE_BYTES
public static final int DEFAULT_MAX_CACHE_ENTRIES
public static final int DEFAULT_MAX_UPDATE_RETRIES
public static final boolean DEFAULT_303_CACHING_ENABLED
public static final boolean DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED
public static final boolean DEFAULT_HEURISTIC_CACHING_ENABLED
public static final float DEFAULT_HEURISTIC_COEFFICIENT
public static final org.apache.hc.core5.util.TimeValue DEFAULT_HEURISTIC_LIFETIME
public static final int DEFAULT_ASYNCHRONOUS_WORKERS
public static final CacheConfig DEFAULT
public long getMaxObjectSize()
public boolean isNeverCacheHTTP10ResponsesWithQuery()
true
to not cache query string responses, false
to cache if explicit cache headers are
foundpublic int getMaxCacheEntries()
public int getMaxUpdateRetries()
public boolean is303CachingEnabled()
true
if it is enabled.public boolean isWeakETagOnPutDeleteAllowed()
true
if it is allowed.public boolean isHeuristicCachingEnabled()
true
if it is enabled.public float getHeuristicCoefficient()
public org.apache.hc.core5.util.TimeValue getHeuristicDefaultLifetime()
public boolean isSharedCache()
true
for a shared cache, false
for a non-
shared (private) cachepublic boolean isFreshnessCheckEnabled()
public int getAsynchronousWorkers()
stale-while-revalidate
directive. A
value of 0 means background revalidations are disabled.protected CacheConfig clone() throws CloneNotSupportedException
clone
in class Object
CloneNotSupportedException
public static CacheConfig.Builder custom()
public static CacheConfig.Builder copy(CacheConfig config)
Copyright © 2010–2021 The Apache Software Foundation. All rights reserved.