Android APIs
public final class

HttpResponseCache

extends ResponseCache
implements Closeable
java.lang.Object
   ↳ java.net.ResponseCache
     ↳ android.net.http.HttpResponseCache

Class Overview

Caches HTTP and HTTPS responses to the filesystem so they may be reused, saving time and bandwidth. This class supports HttpURLConnection and HttpsURLConnection; there is no platform-provided cache for DefaultHttpClient or AndroidHttpClient.

Installing an HTTP response cache

Enable caching of all of your application's HTTP requests by installing the cache at application startup. For example, this code installs a 10 MiB cache in the application-specific cache directory of the filesystem}:
   protected void onCreate(Bundle savedInstanceState) {
       ...

       try {
           File httpCacheDir = new File(context.getCacheDir(), "http");
           long httpCacheSize = 10 * 1024 * 1024; // 10 MiB
           HttpResponseCache.install(httpCacheDir, httpCacheSize);
        catch (IOException e) {
           Log.i(TAG, "HTTP response cache installation failed:" + e);
       }
   }

   protected void onStop() {
       ...

       HttpResponseCache cache = HttpResponseCache.getInstalled();
       if (cache != null) {
           cache.flush();
       }
   }}
This cache will evict entries as necessary to keep its size from exceeding 10 MiB. The best cache size is application specific and depends on the size and frequency of the files being downloaded. Increasing the limit may improve the hit rate, but it may also just waste filesystem space!

For some applications it may be preferable to create the cache in the external storage directory. There are no access controls on the external storage directory so it should not be used for caches that could contain private data. Although it often has more free space, external storage is optional and—even if available—can disappear during use. Retrieve the external cache directory using getExternalCacheDir(). If this method returns null, your application should fall back to either not caching or caching on non-external storage. If the external storage is removed during use, the cache hit rate will drop to zero and ongoing cache reads will fail.

Flushing the cache forces its data to the filesystem. This ensures that all responses written to the cache will be readable the next time the activity starts.

Cache Optimization

To measure cache effectiveness, this class tracks three statistics:
  • Request Count: the number of HTTP requests issued since this cache was created.
  • Network Count: the number of those requests that required network use.
  • Hit Count: the number of those requests whose responses were served by the cache.
Sometimes a request will result in a conditional cache hit. If the cache contains a stale copy of the response, the client will issue a conditional GET. The server will then send either the updated response if it has changed, or a short 'not modified' response if the client's copy is still valid. Such responses increment both the network count and hit count.

The best way to improve the cache hit rate is by configuring the web server to return cacheable responses. Although this client honors all HTTP/1.1 (RFC 2068) cache headers, it doesn't cache partial responses.

Force a Network Response

In some situations, such as after a user clicks a 'refresh' button, it may be necessary to skip the cache, and fetch data directly from the server. To force a full refresh, add the no-cache directive:
   connection.addRequestProperty("Cache-Control", "no-cache");
 
If it is only necessary to force a cached response to be validated by the server, use the more efficient max-age=0 instead:
   connection.addRequestProperty("Cache-Control", "max-age=0");
 

Force a Cache Response

Sometimes you'll want to show resources if they are available immediately, but not otherwise. This can be used so your application can show something while waiting for the latest data to be downloaded. To restrict a request to locally-cached resources, add the only-if-cached directive:
   try {
         connection.addRequestProperty("Cache-Control", "only-if-cached");
         InputStream cached = connection.getInputStream();
         // the resource was cached! show it
      catch (FileNotFoundException e) {
         // the resource was not cached
     }
 }
This technique works even better in situations where a stale response is better than no response. To permit stale cached responses, use the max-stale directive with the maximum staleness in seconds:
   int maxStale = 60 * 60 * 24 * 28; // tolerate 4-weeks stale
         connection.addRequestProperty("Cache-Control", "max-stale=" + maxStale);
 

Working With Earlier Releases

This class was added in Android 4.0 (Ice Cream Sandwich). Use reflection to enable the response cache without impacting earlier releases:
   try {
           File httpCacheDir = new File(context.getCacheDir(), "http");
           long httpCacheSize = 10 * 1024 * 1024; // 10 MiB
           Class.forName("android.net.http.HttpResponseCache")
                   .getMethod("install", File.class, long.class)
                   .invoke(null, httpCacheDir, httpCacheSize);
        catch (Exception httpResponseCacheNotAvailable) {
       }}

Summary

Public Methods
void close()
Uninstalls the cache and releases any active resources.
void delete()
Uninstalls the cache and deletes all of its stored contents.
void flush()
Force buffered operations to the filesystem.
CacheResponse get(URI uri, String requestMethod, Map<StringList<String>> requestHeaders)
Returns the cached response corresponding to the given request.
int getHitCount()
Returns the number of HTTP requests whose response was provided by the cache.
static HttpResponseCache getInstalled()
Returns the currently-installed HttpResponseCache, or null if there is no cache installed or it is not a HttpResponseCache.
int getNetworkCount()
Returns the number of HTTP requests that required the network to either supply a response or validate a locally cached response.
int getRequestCount()
Returns the total number of HTTP requests that were made.
static HttpResponseCache install(File directory, long maxSize)
Creates a new HTTP response cache and sets it as the system default cache.
long maxSize()
Returns the maximum number of bytes that this cache should use to store its data.
CacheRequest put(URI uri, URLConnection urlConnection)
Allows the protocol handler to cache data after retrieving resources.
long size()
Returns the number of bytes currently being used to store the values in this cache.
[Expand]
Inherited Methods
From class java.net.ResponseCache
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Public Methods

public void close ()

Added in API level 13

Uninstalls the cache and releases any active resources. Stored contents will remain on the filesystem.

Throws
IOException

public void delete ()

Added in API level 13

Uninstalls the cache and deletes all of its stored contents.

Throws
IOException

public void flush ()

Added in API level 13

Force buffered operations to the filesystem. This ensures that responses written to the cache will be available the next time the cache is opened, even if this process is killed.

public CacheResponse get (URI uri, String requestMethod, Map<StringList<String>> requestHeaders)

Added in API level 13

Returns the cached response corresponding to the given request.

Parameters
uri the request URI.
requestMethod the request method.
requestHeaders a map of request headers.
Returns
  • the CacheResponse object if the request is available in the cache or null otherwise.
Throws
IOException

public int getHitCount ()

Added in API level 13

Returns the number of HTTP requests whose response was provided by the cache. This may include conditional GET requests that were validated over the network.

public static HttpResponseCache getInstalled ()

Added in API level 13

Returns the currently-installed HttpResponseCache, or null if there is no cache installed or it is not a HttpResponseCache.

public int getNetworkCount ()

Added in API level 13

Returns the number of HTTP requests that required the network to either supply a response or validate a locally cached response.

public int getRequestCount ()

Added in API level 13

Returns the total number of HTTP requests that were made. This includes both client requests and requests that were made on the client's behalf to handle a redirects and retries.

public static HttpResponseCache install (File directory, long maxSize)

Added in API level 13

Creates a new HTTP response cache and sets it as the system default cache.

Parameters
directory the directory to hold cache data.
maxSize the maximum size of the cache in bytes.
Returns
  • the newly-installed cache
Throws
IOException if directory cannot be used for this cache. Most applications should respond to this exception by logging a warning.

public long maxSize ()

Added in API level 13

Returns the maximum number of bytes that this cache should use to store its data.

public CacheRequest put (URI uri, URLConnection urlConnection)

Added in API level 13

Allows the protocol handler to cache data after retrieving resources. The ResponseCache decides whether the resource data should be cached or not. If so, this method returns a CacheRequest to write the resource data to. Otherwise, this method returns null.

Parameters
uri the reference to the requested resource.
urlConnection the connection to fetch the response.
Returns
  • a CacheRequest object with a WriteableByteChannel if the resource has to be cached, null otherwise.
Throws
IOException

public long size ()

Added in API level 13

Returns the number of bytes currently being used to store the values in this cache. This may be greater than the maxSize() if a background deletion is pending.