254 lines
11 KiB
XML
254 lines
11 KiB
XML
<?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--the Java equivalent of a browser cache. The
|
|
implementation follows the Chain of Responsibility design pattern, where the
|
|
caching HttpClient implementation can serve a drop-in replacement for
|
|
the default non-caching HttpClient implementation; requests that can be
|
|
satisfied entirely from the cache will not result in actual origin requests.
|
|
Stale cache entries are automatically validated with the origin where possible,
|
|
using conditional GETs and the If-Modified-Since and/or If-None-Match request
|
|
headers.
|
|
</para>
|
|
|
|
<para>
|
|
HTTP/1.1 caching in general is designed to be <emphasis>semantically
|
|
transparent</emphasis>; that is, a cache should not change the meaning of
|
|
the request-response exchange between client and server. As such, it should
|
|
be safe to drop a caching HttpClient into an existing compliant client-server
|
|
relationship. Although the caching module is part of the client from an
|
|
HTTP protocol point of view, the implementation aims to be compatible with
|
|
the requirements placed on a transparent caching proxy.
|
|
</para>
|
|
|
|
<para>Finally, caching HttpClient includes support the Cache-Control
|
|
extensions specified by RFC 5861 (stale-if-error and stale-while-revalidate).
|
|
</para>
|
|
|
|
<para>When caching HttpClient 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 caching HttpClient receives a response, it goes through the
|
|
following flow:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Examining 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 caching HttpClient is not, itself,
|
|
a different implementation of HttpClient, but that it works by inserting
|
|
itself as an additonal processing component to the request execution
|
|
pipeline.</para>
|
|
</section>
|
|
|
|
<section id="rfc2616compliance">
|
|
<title>RFC-2616 Compliance</title>
|
|
|
|
<para>We believe HttpClient Cache is <emphasis>unconditionally
|
|
compliant</emphasis> with <ulink
|
|
url="http://www.ietf.org/rfc/rfc2616.txt">RFC-2616</ulink>. That is,
|
|
wherever the specification indicates MUST, MUST NOT, SHOULD, or SHOULD NOT
|
|
for HTTP caches, the caching layer attempts to behave in a way that satisfies
|
|
those requirements. This means the caching module won't produce incorrect
|
|
behavior when you drop it in. </para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example Usage</title>
|
|
|
|
<para>This is a simple example of how to set up a basic caching HttpClient.
|
|
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><![CDATA[
|
|
CacheConfig cacheConfig = CacheConfig.custom()
|
|
.setMaxCacheEntries(1000)
|
|
.setMaxObjectSize(8192)
|
|
.build();
|
|
RequestConfig requestConfig = RequestConfig.custom()
|
|
.setConnectTimeout(30000)
|
|
.setSocketTimeout(30000)
|
|
.build();
|
|
CloseableHttpClient cachingClient = CachingHttpClients.custom()
|
|
.setCacheConfig(cacheConfig)
|
|
.setDefaultRequestConfig(requestConfig)
|
|
.build();
|
|
|
|
HttpCacheContext context = HttpCacheContext.create();
|
|
HttpGet httpget = new HttpGet("http://www.mydomain.com/content/");
|
|
CloseableHttpResponse response = cachingClient.execute(httpget, context);
|
|
try {
|
|
CacheResponseStatus responseStatus = context.getCacheResponseStatus();
|
|
switch (responseStatus) {
|
|
case CACHE_HIT:
|
|
System.out.println("A response was generated from the cache with " +
|
|
"no requests sent upstream");
|
|
break;
|
|
case CACHE_MODULE_RESPONSE:
|
|
System.out.println("The response was generated directly by the " +
|
|
"caching module");
|
|
break;
|
|
case CACHE_MISS:
|
|
System.out.println("The response came from an upstream server");
|
|
break;
|
|
case VALIDATED:
|
|
System.out.println("The response was generated from the cache " +
|
|
"after validating the entry with the origin server");
|
|
break;
|
|
}
|
|
} finally {
|
|
response.close();
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="configuration">
|
|
<title>Configuration</title>
|
|
|
|
<para>The caching HttpClient inherits all configuration options and parameters
|
|
of the default non-caching implementation (this includes setting options like
|
|
timeouts and connection pool sizes). For caching-specific configuration, you can
|
|
provide a <classname>CacheConfig</classname> instance to customize behavior
|
|
across the following areas:</para>
|
|
|
|
<para><emphasis>Cache size.</emphasis> If the backend storage supports these limits,
|
|
you can specify the maximum number of cache entries as well as the maximum cacheable
|
|
response body size.</para>
|
|
|
|
|
|
<para><emphasis>Public/private caching.</emphasis> By default, the caching module
|
|
considers itself to be a shared (public) cache, and will not, for example, cache
|
|
responses to requests with Authorization headers or responses marked with
|
|
"Cache-Control: private". If, however, the cache is only going to be used by one
|
|
logical "user" (behaving similarly to a browser cache), then you will want to turn
|
|
off the shared cache setting.</para>
|
|
|
|
<para><emphasis>Heuristic caching.</emphasis>Per RFC2616, a cache MAY cache
|
|
certain cache entries even if no explicit cache control headers are set by the
|
|
origin. This behavior is off by default, but you may want to turn this on if you
|
|
are working with an origin that doesn't set proper headers but where you still
|
|
want to cache the responses. You will want to enable heuristic caching, then
|
|
specify either a default freshness lifetime and/or a fraction of the time since
|
|
the resource was last modified. See Sections 13.2.2 and 13.2.4 of the HTTP/1.1
|
|
RFC for more details on heuristic caching.</para>
|
|
|
|
<para><emphasis>Background validation.</emphasis> The cache module supports the
|
|
stale-while-revalidate directive of RFC5861, which allows certain cache entry
|
|
revalidations to happen in the background. You may want to tweak the settings
|
|
for the minimum and maximum number of background worker threads, as well as the
|
|
maximum time they can be idle before being reclaimed. You can also control the
|
|
size of the queue used for revalidations when there aren't enough workers to
|
|
keep up with demand.</para>
|
|
</section>
|
|
|
|
<section id="storage">
|
|
<title>Storage Backends</title>
|
|
|
|
<para>The default implementation of caching HttpClient stores cache entries and
|
|
cached response bodies in memory in the JVM of your application. While this
|
|
offers high performance, it may not be appropriate for your application due to
|
|
the limitation on size or because the cache entries are ephemeral and don't
|
|
survive an application restart. The current release includes support for storing
|
|
cache entries using EhCache and memcached implementations, which allow for
|
|
spilling cache entries to disk or storing them in an external process.</para>
|
|
|
|
<para>If none of those options are suitable for your application, it is
|
|
possible to provide your own storage backend by implementing the HttpCacheStorage
|
|
interface and then supplying that to caching HttpClient at construction time. In
|
|
this case, the cache entries will be stored using your scheme but you will get to
|
|
reuse all of the logic surrounding HTTP/1.1 compliance and cache handling.
|
|
Generally speaking, it should be possible to create an HttpCacheStorage
|
|
implementation out of anything that supports a key/value store (similar to the
|
|
Java Map interface) with the ability to apply atomic updates.</para>
|
|
|
|
<para>Finally, with some extra efforts it's entirely possible to set up
|
|
a multi-tier caching hierarchy; for example, wrapping an in-memory caching
|
|
HttpClient around one that stores cache entries on disk or remotely in memcached,
|
|
following a pattern similar to virtual memory, L1/L2 processor caches, etc.
|
|
</para>
|
|
</section>
|
|
</chapter>
|