Package org.apache.hc.client5.http.impl.cache

Class CacheConfig

java.lang.Object
org.apache.hc.client5.http.impl.cache.CacheConfig
All Implemented Interfaces:
Cloneable
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

  • Field Details

    • 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:

    • 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:

    • 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:

    • DEFAULT_303_CACHING_ENABLED

      public static final boolean DEFAULT_303_CACHING_ENABLED
      Default setting for 303 caching
      See Also:

    • 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:

    • DEFAULT_HEURISTIC_CACHING_ENABLED

      public static final boolean DEFAULT_HEURISTIC_CACHING_ENABLED
      Default setting for heuristic caching
      See Also:

    • 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:

    • 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:

    • 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 Details

    • 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 Details

    • 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 the stale-while-revalidate directive. A value of 0 means background revalidations are disabled.

    • 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