<?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>