# Package org.apache.http.client.cache

This package consists largely of constants and interfaces that are necessary for building new storage backends for the `CachingHttpClient` or for those clients wanting to get a little more behavioral information out of the cache module (for example, whether a particular response was a cache hit or not).

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  HttpCacheEntrySerializer | Used by some `HttpCacheStorage` implementations to serialize `HttpCacheEntry` instances to a byte representation before storage.
  HttpCacheInvalidator | Given a particular HttpRequest, flush any cache entries that this request would invalidate.
  HttpCacheStorage | New storage backends should implement this `HttpCacheStorage` interface.
  HttpCacheUpdateCallback | Used for atomically updating entries in a `HttpCacheStorage` implementation.
  Resource | Represents a disposable system resource used for handling cached response bodies.
  ResourceFactory | Generates `Resource` instances for handling cached HTTP response bodies.

- Class Summary
  Class | Description
  --- | ---
  HeaderConstants | Records static constants for various HTTP header names.
  HttpCacheContext |
  HttpCacheEntry | Structure used to store an `HttpResponse` in a cache.
  InputLimit | Used to limiting the size of an incoming response body of unknown size that is optimistically being read in anticipation of caching it.

- Enum Summary
  Enum | Description
  --- | ---
  CacheResponseStatus | This enumeration represents the various ways a response can be generated by the `CachingHttpClient`; if a request is executed with an `HttpContext` then a parameter with one of these values will be registered in the context under the key `CachingHttpClient.CACHE_RESPONSE_STATUS`.

- Exception Summary
  Exception | Description
  --- | ---
  HttpCacheEntrySerializationException | Thrown if serialization or deserialization of an `HttpCacheEntry` fails.
  HttpCacheUpdateException | Signals that `HttpCacheStorage` encountered an error performing an update operation.

## Package org.apache.http.client.cache Description

This package consists largely of constants and interfaces that are necessary for building new storage backends for the `CachingHttpClient` or for those clients wanting to get a little more behavioral information out of the cache module (for example, whether a particular response was a cache hit or not). Developers that simply want to instantiate and make use of the caching module will be better off looking at the `CachingHttpClient` documentation itself.

The classes in this package can be divided into two main groups: reference constants and interfaces needed for storage backends. In the former group, `HeaderConstants` contains a list of HTTP header names encoded as static fields, and the `CacheResponseStatus` enumeration values are set in an `HttpContext` by the `CachingHttpClient` to indicate how the request was processed by the caching module itself.

New storage backends will need to implement the `HttpCacheStorage` interface; they can then be passed to one of the `CachingHttpClient` constructors, which will happily make use of the new storage mechanism. The `HttpCacheEntry` class shows the datastructure for a cache entry that must be stored by the `HttpCacheStorage`. There is, in addition, the notion of a `Resource` and an associated `ResourceFactory`, which are used for managing the handling of cached response bodies. The default implementation used by the `CachingHttpClient` stores response bodies in memory; alternative implementations might involve storing these in a filesystem. A new `ResourceFactory` can be provided along with a `HttpCacheStorage` in one of the constructors to the `CachingHttpClient`. Finally, some of the additional storage backends we provide, like the `EhcacheHttpCacheStorage` and `MemcachedHttpCacheStorage`, can be provided with different serializers for the cache entry metadata; developers wanting to experiment with different serialization techniques should implement the `HttpCacheEntrySerializer` interface.

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