HttpClient Cache provides an HTTP 1.1 compliant caching layer to be used with HttpClient. It is implemented as a decorator of HttpClient. It provides basic HTTP 1.1 caching capability. You can specify a limit on the maximum cacheable object size to have some control over the size of your cache. When CachingHttpClient executes a request, it goes through the following flow: Check the request for basic compliance with the HTTP 1.1 protocol and attempt to correct the request. Flush any cache entries which would be invalidated by this request. Determine if the current request would be servable from cache. If not, directly pass through the request to the origin server and return the response, after caching it if appropriate. If it was a a cache-servable request, it will attempt to read it from the cache. If it is not in the cache, call the origin server and cache the response, if appropriate. If the cached response is suitable to be served as a response, construct a BasicHttpResponse containing a ByteArrayEntity and return it. Otherwise, attempt to revalidate the cache entry against the origin server. In the case of a cached response which cannot be revalidated, call the origin server and cache the response, if appropriate. When CachingHttpClient receives a response, it goes through the following flow: Examing the response for protocol compliance Determine whether the response is cacheable If it is cacheable, attempt to read up to the maximum size allowed in the configuration and store it in the cache. If the response is too large for the cache, reconstruct the partially consumed response and return it directly without caching it. It is important to note that CachingHttpClient is not, itself, an implementation of HttpClient, but that it decorates an instance of an HttpClient implementation. If you do not provide an implementation, it will use DefaultHttpClient internally by default.

HttpClient Cache makes an effort to be at least conditionally compliant with RFC-2616. That is, wherever the specification indicates MUST or MUST NOT for HTTP caches, the caching layer attempts to behave in a way that satisfies those requirements.

The provided implementation for an HttpCache<T> is called BasicHttpCache. It uses an in-memory LinkedHashMap to provide basic least-recently-used (LRU) functionality. Because we provide the HttpCache<T> interface, other implementations of caching may be used, e.g. EHCache, memcached, etc.

This is a simple example of how to set up a basic CachingHttpClient. As configured, it will store a maximum of 1000 cached objects, each of which may have a maximum body size of 8192 bytes. The numbers selected here are for example only and not intended to be prescriptive or considered as recommendations. HttpClient client = new DefaultHttpClient(); int maxCacheEntries = 1000; int maxCacheEntrySizeBytes = 8192; HttpCache<CacheEntry> cache = new BasicHttpCache(maxCacheEntries); HttpClient cachingClient = new CachingHttpClient(client, cache, maxCacheEntrySizeBytes);