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

Class CacheConfig

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class CacheConfig
extends java.lang.Object
implements java.lang.Cloneable

    Configuration for HTTP caches

    Cache configuration can be grouped into the following categories:

    Protocol options. I some cases the HTTP protocol allows for conditional behaviors or optional protocol extensions. Such conditional protocol behaviors or extensions can be turned on or off here. See isNeverCacheHTTP10ResponsesWithQuery(), isNeverCacheHTTP11ResponsesWithQuery(), isStaleIfErrorEnabled()

    Cache size. If the backend storage supports these limits, one 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 one may want to isSharedCache() turn off the shared cache setting}.

    Heuristic caching. Per HTTP caching specification, 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 one may still want to cache the responses. Use isHeuristicCachingEnabled() to enable heuristic caching}, then specify either a default freshness lifetime and/or a fraction of the time since the resource was last modified.

    Background validation. The cache module supports the stale-while-revalidate directive, 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 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

        @Deprecated
public static final boolean DEFAULT_303_CACHING_ENABLED
        Deprecated.
        No longer applicable. Do not use.
        See Also:
        Constant Field Values

      • DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED

        @Deprecated
public static final boolean DEFAULT_WEAK_ETAG_ON_PUTDELETE_ALLOWED
        Deprecated.
        No longer applicable. Do not use.
        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

      • maxObjectSize

        private final long maxObjectSize

      • maxCacheEntries

        private final int maxCacheEntries

      • maxUpdateRetries

        private final int maxUpdateRetries

      • 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

      • staleIfErrorEnabled

        private final boolean staleIfErrorEnabled

      • neverCacheHTTP11ResponsesWithQuery

        private final boolean neverCacheHTTP11ResponsesWithQuery
        A constant indicating whether HTTP/1.1 responses with a query string should never be cached.

    • Constructor Detail

      • CacheConfig

        CacheConfig​(long maxObjectSize,
            int maxCacheEntries,
            int maxUpdateRetries,
            boolean heuristicCachingEnabled,
            float heuristicCoefficient,
            org.apache.hc.core5.util.TimeValue heuristicDefaultLifetime,
            boolean sharedCache,
            boolean freshnessCheckEnabled,
            int asynchronousWorkers,
            boolean neverCacheHTTP10ResponsesWithQuery,
            boolean neverCacheHTTP11ResponsesWithQuery,
            boolean staleIfErrorEnabled)

    • 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

      • isNeverCacheHTTP11ResponsesWithQuery

        public boolean isNeverCacheHTTP11ResponsesWithQuery()
        Determines whether HTTP/1.1 responses with query strings should never be cached by the client. By default, caching of such responses is allowed. Enabling this option may improve security by preventing responses with sensitive information from being cached.

        Note that this option only applies to HTTP/1.1.

        Returns:
        true if HTTP/1.1 responses with query strings should never be cached; false otherwise.
        Since:
        5.4

      • isStaleIfErrorEnabled

        public boolean isStaleIfErrorEnabled()
        Returns a boolean value indicating whether the stale-if-error cache directive is enabled. If this option is enabled, cached responses that have become stale due to an error (such as a server error or a network failure) will be returned instead of generating a new request. This can help to reduce the load on the origin server and improve performance.
        Returns:
        true if the stale-if-error directive is enabled, or false otherwise.

      • 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

        @Deprecated
public boolean is303CachingEnabled()
        Deprecated.
        No longer applicable. Do not use.

      • isWeakETagOnPutDeleteAllowed

        @Deprecated
public boolean isWeakETagOnPutDeleteAllowed()
        Deprecated.
        Do not use.
        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 java.lang.CloneNotSupportedException
        Overrides:
        clone in class java.lang.Object
        Throws:
        java.lang.CloneNotSupportedException

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object