Package okhttp3

Class Cache

java.lang.Object

okhttp3.Cache

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public final class Cache
extends Object
implements Closeable, Flushable

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 7234) 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:

   

   Request request = new Request.Builder()
       .cacheControl(new CacheControl.Builder().noCache().build())
       .url("http://publicobject.com/helloworld.txt")
       .build();
 

If it is only necessary to force a cached response to be validated by the server, use the more efficient max-age=0 directive instead:

   

   Request request = new Request.Builder()
       .cacheControl(new CacheControl.Builder()
           .maxAge(0, TimeUnit.SECONDS)
           .build())
       .url("http://publicobject.com/helloworld.txt")
       .build();
 

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:

   

     Request request = new Request.Builder()
         .cacheControl(new CacheControl.Builder()
             .onlyIfCached()
             .build())
         .url("http://publicobject.com/helloworld.txt")
         .build();
     Response forceCacheResponse = client.newCall(request).execute();
     if (forceCacheResponse.code() != 504) {
       // The resource was cached! Show it.
     } else {
       // 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:

   

   Request request = new Request.Builder()
       .cacheControl(new CacheControl.Builder()
           .maxStale(365, TimeUnit.DAYS)
           .build())
       .url("http://publicobject.com/helloworld.txt")
       .build();
 

The CacheControl class can configure request caching directives and parse response caching directives. It even offers convenient constants CacheControl.FORCE_NETWORK and CacheControl.FORCE_CACHE that address the use cases above.

Constructor Summary

Constructors

Constructor	Description
Cache(File directory, long maxSize)	Create a cache of at most maxSize bytes in directory.

Method Summary

Modifier and Type	Method	Description
void	close()
void	delete()	Closes the cache and deletes all of its stored values.
File	directory()
void	evictAll()	Deletes all values stored in the cache.
void	flush()
int	hitCount()
void	initialize()	Initialize the cache.
boolean	isClosed()
static String	key(HttpUrl url)
long	maxSize()	Max size of the cache (in bytes).
int	networkCount()
int	requestCount()
long	size()
Iterator<String>	urls()	Returns an iterator over the URLs in this cache.
int	writeAbortCount()
int	writeSuccessCount()

Methods inherited from class java.lang.Object

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

Constructor Detail

Cache

public Cache(File directory,
             long maxSize)

Create a cache of at most maxSize bytes in directory.

Method Detail

key

public static String key(HttpUrl url)

initialize

public void initialize()
                throws IOException

Initialize the cache. This will include reading the journal files from the storage and building up the necessary in-memory cache information.

The initialization time may vary depending on the journal file size and the current actual cache size. The application needs to be aware of calling this function during the initialization phase and preferably in a background worker thread.

Note that if the application chooses to not call this method to initialize the cache. By default, the okhttp will perform lazy initialization upon the first usage of the cache.

Throws:

IOException

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

evictAll

public void evictAll()
              throws IOException

Deletes all values stored in the cache. In-flight writes to the cache will complete normally, but the corresponding responses will not be stored.

Throws:

IOException

urls

public Iterator<String> urls()
                      throws IOException

Returns an iterator over the URLs in this cache. This iterator doesn't throw ConcurrentModificationException, but if new responses are added while iterating, their URLs will not be returned. If existing responses are evicted during iteration, they will be absent (unless they were already returned).

The iterator supports Iterator.remove(). Removing a URL from the iterator evicts the corresponding response from the cache. Use this to evict selected responses.

Throws:

IOException

writeAbortCount

public int writeAbortCount()

writeSuccessCount

public int writeSuccessCount()

size

public long size()
          throws IOException

Throws:

IOException

maxSize

public long maxSize()

Max size of the cache (in bytes).

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Throws:

IOException

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

directory

public File directory()

isClosed

public boolean isClosed()

networkCount

public int networkCount()

hitCount

public int hitCount()

requestCount

public int requestCount()