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

  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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CacheConfig.Builder`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static CacheConfig` | `DEFAULT`
    `static boolean` | `DEFAULT_303_CACHING_ENABLED` Deprecated. No longer applicable. Do not use.
    `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` Deprecated. No longer applicable. Do not use.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated 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()` Deprecated. No longer applicable. Do not use.
    `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` | `isNeverCacheHTTP11ResponsesWithQuery()` Determines whether HTTP/1.1 responses with query strings should never be cached by the client.
    `boolean` | `isSharedCache()` Returns whether the cache will behave as a shared cache or not.
    `boolean` | `isStaleIfErrorEnabled()` Returns a boolean value indicating whether the stale-if-error cache directive is enabled.
    `boolean` | `isWeakETagOnPutDeleteAllowed()` Deprecated. Do not use.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, 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 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

    - #### DEFAULT

          public static final CacheConfig DEFAULT

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

Copyright © 1999–2021 The Apache Software Foundation. All rights reserved.