## 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
HttpCacheEntrySerializer: Used by some `HttpCacheStorage` implementations to serialize `HttpCacheEntry` instances to a byte representation before storage.
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
HeaderConstants: Records static constants for various HTTP header names.
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
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
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-2012 The Apache Software Foundation. All Rights Reserved.