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 @@
+