Class CacheConfig
- java.lang.Object
-
- org.apache.hc.client5.http.impl.cache.CacheConfig
-
- All Implemented Interfaces:
java.lang.Cloneable
public class CacheConfig extends java.lang.Object implements java.lang.Cloneable
Java Beans-style configuration for caching
HttpClient
. Any class in the caching module that has configuration options should take aCacheConfig
argument in one of its constructors. ACacheConfig
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 theCachingHttpClient
.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 thegetMaxObjectSize()
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 withCache-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 toisSharedCache()
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 adefault freshness lifetime
and/or afraction 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 to0
withgetAsynchronousWorkers()
parameter
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
CacheConfig.Builder
-
Field Summary
Fields Modifier and Type Field Description private boolean
allow303Caching
private int
asynchronousWorkers
static CacheConfig
DEFAULT
static boolean
DEFAULT_303_CACHING_ENABLED
Default setting for 303 cachingstatic 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 cachingstatic 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 processChallengestatic boolean
DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED
Default setting to allow weak tags on PUT/DELETE methodsprivate boolean
freshnessCheckEnabled
private boolean
heuristicCachingEnabled
private float
heuristicCoefficient
private org.apache.hc.core5.util.TimeValue
heuristicDefaultLifetime
private int
maxCacheEntries
private long
maxObjectSize
private int
maxUpdateRetries
private boolean
neverCacheHTTP10ResponsesWithQuery
private boolean
sharedCache
private boolean
weakETagOnPutDeleteAllowed
-
Constructor Summary
Constructors Constructor Description CacheConfig(long maxObjectSize, int maxCacheEntries, int maxUpdateRetries, boolean allow303Caching, boolean weakETagOnPutDeleteAllowed, boolean heuristicCachingEnabled, float heuristicCoefficient, org.apache.hc.core5.util.TimeValue heuristicDefaultLifetime, boolean sharedCache, boolean freshnessCheckEnabled, int asynchronousWorkers, boolean neverCacheHTTP10ResponsesWithQuery)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 thestale-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 failureboolean
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 missboolean
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.java.lang.String
toString()
-
-
-
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 processChallenge- 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 org.apache.hc.core5.util.TimeValue DEFAULT_HEURISTIC_LIFETIME
Default lifetime to be assumed when we cannot calculate freshness heuristically.
-
DEFAULT_ASYNCHRONOUS_WORKERS
public static final int DEFAULT_ASYNCHRONOUS_WORKERS
Default number of worker threads to allow for background revalidations resulting from the stale-while-revalidate directive.- See Also:
- Constant Field Values
-
DEFAULT
public static final CacheConfig DEFAULT
-
maxObjectSize
private final long maxObjectSize
-
maxCacheEntries
private final int maxCacheEntries
-
maxUpdateRetries
private final int maxUpdateRetries
-
allow303Caching
private final boolean allow303Caching
-
weakETagOnPutDeleteAllowed
private final boolean weakETagOnPutDeleteAllowed
-
heuristicCachingEnabled
private final boolean heuristicCachingEnabled
-
heuristicCoefficient
private final float heuristicCoefficient
-
heuristicDefaultLifetime
private final org.apache.hc.core5.util.TimeValue heuristicDefaultLifetime
-
sharedCache
private final boolean sharedCache
-
freshnessCheckEnabled
private final boolean freshnessCheckEnabled
-
asynchronousWorkers
private final int asynchronousWorkers
-
neverCacheHTTP10ResponsesWithQuery
private final boolean neverCacheHTTP10ResponsesWithQuery
-
-
Constructor Detail
-
CacheConfig
CacheConfig(long maxObjectSize, int maxCacheEntries, int maxUpdateRetries, boolean allow303Caching, boolean weakETagOnPutDeleteAllowed, boolean heuristicCachingEnabled, float heuristicCoefficient, org.apache.hc.core5.util.TimeValue heuristicDefaultLifetime, boolean sharedCache, boolean freshnessCheckEnabled, int asynchronousWorkers, boolean neverCacheHTTP10ResponsesWithQuery)
-
-
Method Detail
-
getMaxObjectSize
public long getMaxObjectSize()
Returns the current maximum response body size that will be cached.- Returns:
- 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.
-
getMaxUpdateRetries
public int getMaxUpdateRetries()
Returns the number of times to retry a cache processChallenge 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.
-
getHeuristicCoefficient
public float getHeuristicCoefficient()
Returns lifetime coefficient used in heuristic freshness caching.
-
getHeuristicDefaultLifetime
public org.apache.hc.core5.util.TimeValue getHeuristicDefaultLifetime()
Get the default lifetime to be used if heuristic freshness calculation is not possible.
-
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
-
isFreshnessCheckEnabled
public boolean isFreshnessCheckEnabled()
Returns whether the cache will perform an extra cache entry freshness check upon cache update in case of a cache miss- Since:
- 5.0
-
getAsynchronousWorkers
public int getAsynchronousWorkers()
Returns the maximum number of threads to allow for background revalidations due to thestale-while-revalidate
directive. A value of 0 means background revalidations are disabled.
-
clone
protected CacheConfig clone() throws java.lang.CloneNotSupportedException
- Overrides:
clone
in classjava.lang.Object
- Throws:
java.lang.CloneNotSupportedException
-
custom
public static CacheConfig.Builder custom()
-
copy
public static CacheConfig.Builder copy(CacheConfig config)
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-