Index: src/docbkx/caching.xml =================================================================== --- src/docbkx/caching.xml (revision ) +++ src/docbkx/caching.xml (revision ) @@ -0,0 +1,145 @@ + + + + + HTTP Caching + +
+ General Concepts + + 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. +
+ +
+ RFC-2616 Compliance + + 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. +
+ +
+ Cache Implementation + + 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. +
+ +
+ Example Usage + + 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); + + +
+
Index: src/docbkx/index.xml =================================================================== --- src/docbkx/index.xml (revision 807956) +++ src/docbkx/index.xml (revision ) @@ -25,7 +25,7 @@ HttpClient Tutorial - &version; + @@ -67,5 +67,6 @@ +