com.squareup.okhttp

Class HttpResponseCache

java.lang.Object

java.net.ResponseCache

com.squareup.okhttp.HttpResponseCache

All Implemented Interfaces:

OkResponseCache

public final class HttpResponseCache
extends ResponseCache
implements OkResponseCache

Caches HTTP and HTTPS responses to the filesystem so they may be reused, saving time and bandwidth.

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);
 

Constructor Summary

Constructors

Constructor and Description
HttpResponseCache(File directory, long maxSize)

Method Summary

Methods

Modifier and Type	Method and Description
void	close()
void	delete() Closes the cache and deletes all of its stored values.
void	flush()
com.squareup.okhttp.internal.http.Response	get(com.squareup.okhttp.internal.http.Request request)
CacheResponse	get(URI uri, String s, Map<String,List<String>> stringListMap)
File	getDirectory()
int	getHitCount()
long	getMaxSize()
int	getNetworkCount()
int	getRequestCount()
long	getSize()
int	getWriteAbortCount()
int	getWriteSuccessCount()
boolean	isClosed()
boolean	maybeRemove(com.squareup.okhttp.internal.http.Request request) Remove any cache entries for the supplied uri.
CacheRequest	put(com.squareup.okhttp.internal.http.Response response)
CacheRequest	put(URI uri, URLConnection urlConnection)
void	trackConditionalCacheHit() Track an conditional GET that was satisfied by this cache.
void	trackResponse(ResponseSource source) Track an HTTP response being satisfied by source.
void	update(com.squareup.okhttp.internal.http.Response cached, com.squareup.okhttp.internal.http.Response network) Handles a conditional request hit by updating the stored cache response with the headers from network.

Methods inherited from class java.net.ResponseCache

getDefault, setDefault

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HttpResponseCache

public HttpResponseCache(File directory,
                 long maxSize)
                  throws IOException

Throws:

IOException

Method Detail

get

public CacheResponse get(URI uri,
                String s,
                Map<String,List<String>> stringListMap)
                  throws IOException

Specified by:

get in class ResponseCache

Throws:

IOException

put

public CacheRequest put(URI uri,
               URLConnection urlConnection)
                 throws IOException

Specified by:

put in class ResponseCache

Throws:

IOException

get

public com.squareup.okhttp.internal.http.Response get(com.squareup.okhttp.internal.http.Request request)

Specified by:

get in interface OkResponseCache

put

public CacheRequest put(com.squareup.okhttp.internal.http.Response response)
                 throws IOException

Specified by:

put in interface OkResponseCache

Throws:

IOException

maybeRemove

public boolean maybeRemove(com.squareup.okhttp.internal.http.Request request)

Description copied from interface: OkResponseCache

Remove any cache entries for the supplied uri. Returns true if the supplied requestMethod potentially invalidates an entry in the cache.

Specified by:

maybeRemove in interface OkResponseCache

update

public void update(com.squareup.okhttp.internal.http.Response cached,
          com.squareup.okhttp.internal.http.Response network)

Description copied from interface: OkResponseCache

Handles a conditional request hit by updating the stored cache response with the headers from network. The cached response body is not updated. If the stored response has changed since cached was returned, this does nothing.

Specified by:

update in interface OkResponseCache

delete

public void delete()
            throws IOException

Closes the cache and deletes all of its stored values. This will delete all files in the cache directory including files that weren't created by the cache.

Throws:

IOException

getWriteAbortCount

public int getWriteAbortCount()

getWriteSuccessCount

public int getWriteSuccessCount()

getSize

public long getSize()

getMaxSize

public long getMaxSize()

flush

public void flush()
           throws IOException

Throws:

IOException

close

public void close()
           throws IOException

Throws:

IOException

getDirectory

public File getDirectory()

isClosed

public boolean isClosed()

trackResponse

public void trackResponse(ResponseSource source)

Description copied from interface: OkResponseCache

Track an HTTP response being satisfied by source.

Specified by:

trackResponse in interface OkResponseCache

trackConditionalCacheHit

public void trackConditionalCacheHit()

Description copied from interface: OkResponseCache

Track an conditional GET that was satisfied by this cache.

Specified by:

trackConditionalCacheHit in interface OkResponseCache

getNetworkCount

public int getNetworkCount()

getHitCount

public int getHitCount()

getRequestCount

public int getRequestCount()