hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r942353 - in /httpcomponents/httpclient/trunk/src/docbkx: caching.xml index.xml
Date Sat, 08 May 2010 09:22:32 GMT
Author: olegk
Date: Sat May  8 09:22:29 2010
New Revision: 942353

URL: http://svn.apache.org/viewvc?rev=942353&view=rev
Log:
HTTPCLIENT-427: Added a section on HTTP caching to the HttpClient tutorial
Contributed by David Mays <david_mays at comcast.com>

Added:
    httpcomponents/httpclient/trunk/src/docbkx/caching.xml
Modified:
    httpcomponents/httpclient/trunk/src/docbkx/index.xml

Added: httpcomponents/httpclient/trunk/src/docbkx/caching.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/caching.xml?rev=942353&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/caching.xml (added)
+++ httpcomponents/httpclient/trunk/src/docbkx/caching.xml Sat May  8 09:22:29 2010
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+    ====================================================================
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+    ====================================================================
+-->
+<chapter id="caching">
+  <title>HTTP Caching</title>
+
+  <section id="generalconcepts">
+    <title>General Concepts</title>
+
+    <para>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.</para>
+
+    <para>When CachingHttpClient executes a request, it goes through the
+    following flow:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Check the request for basic compliance with the HTTP 1.1
+        protocol and attempt to correct the request.</para>
+      </listitem>
+
+      <listitem>
+        <para>Flush any cache entries which would be invalidated by this
+        request.</para>
+      </listitem>
+
+      <listitem>
+        <para>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.</para>
+      </listitem>
+
+      <listitem>
+        <para>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.</para>
+      </listitem>
+
+      <listitem>
+        <para>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.</para>
+      </listitem>
+
+      <listitem>
+        <para>In the case of a cached response which cannot be revalidated,
+        call the origin server and cache the response, if appropriate.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>When CachingHttpClient receives a response, it goes through the
+    following flow:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Examing the response for protocol compliance</para>
+      </listitem>
+
+      <listitem>
+        <para>Determine whether the response is cacheable</para>
+      </listitem>
+
+      <listitem>
+        <para>If it is cacheable, attempt to read up to the maximum size
+        allowed in the configuration and store it in the cache.</para>
+      </listitem>
+
+      <listitem>
+        <para>If the response is too large for the cache, reconstruct the
+        partially consumed response and return it directly without caching
+        it.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>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.</para>
+  </section>
+
+  <section id="rfc2616compliance">
+    <title>RFC-2616 Compliance</title>
+
+    <para>HttpClient Cache makes an effort to be at least conditionally
+    compliant with <ulink
+    url="http://www.ietf.org/rfc/rfc2616.txt">RFC-2616</ulink>. 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.</para>
+  </section>
+
+  <section>
+    <title>Cache Implementation</title>
+
+    <para>The provided implementation for an HttpCache&lt;T&gt; is called
+    BasicHttpCache. It uses an in-memory LinkedHashMap to provide basic
+    least-recently-used (LRU) functionality. Because we provide the
+    HttpCache&lt;T&gt; interface, other implementations of caching may be
+    used, e.g. EHCache, memcached, etc.</para>
+  </section>
+
+  <section>
+    <title>Example Usage</title>
+
+    <para>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.</para>
+
+    <programlisting>
+HttpClient client = new DefaultHttpClient();
+int maxCacheEntries = 1000;
+int maxCacheEntrySizeBytes = 8192;
+HttpCache&lt;CacheEntry&gt; cache = new
+BasicHttpCache(maxCacheEntries);
+HttpClient cachingClient = new CachingHttpClient(client, cache, maxCacheEntrySizeBytes);
+</programlisting>
+  </section>
+</chapter>

Modified: httpcomponents/httpclient/trunk/src/docbkx/index.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/index.xml?rev=942353&r1=942352&r2=942353&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/index.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/index.xml Sat May  8 09:22:29 2010
@@ -25,7 +25,7 @@
     
     <bookinfo>
         <title>HttpClient Tutorial</title>
-        <releaseinfo>&version;</releaseinfo>
+        <releaseinfo></releaseinfo>
 
         <authorgroup>
             <author>
@@ -66,6 +66,7 @@
     <xi:include href="statemgmt.xml"/>
     <xi:include href="authentication.xml"/>
     <xi:include href="httpagent.xml"/>
+    <xi:include href="caching.xml"/>
     <xi:include href="advanced.xml"/>
     
 </book>



Mime
View raw message