You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2010/05/08 11:22:32 UTC
svn commit: r942353 - in /httpcomponents/httpclient/trunk/src/docbkx:
caching.xml index.xml
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<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.</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<CacheEntry> 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>
Re: svn commit: r942353 - in
/httpcomponents/httpclient/trunk/src/docbkx: caching.xml index.xml
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2010-05-08 at 11:14 +0100, sebb wrote:
> > --- 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>
>
> Is the above part of the change correct?
>
Eh, no. Committed by mistake. Reverted.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: svn commit: r942353 - in /httpcomponents/httpclient/trunk/src/docbkx:
caching.xml index.xml
Posted by sebb <se...@gmail.com>.
On 08/05/2010, olegk@apache.org <ol...@apache.org> wrote:
> 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
>
> --- 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>
Is the above part of the change correct?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org