HttpResponseCache
public
final
class
HttpResponseCache
extends ResponseCache
implements
Closeable
java.lang.Object | ||
↳ | java.net.ResponseCache | |
↳ | android.net.http.HttpResponseCache |
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
. Installation and instances are thread
safe.
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 theapplication-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();
}
}
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 Context.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.
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 theno-cache
directive: connection.addRequestProperty("Cache-Control", "no-cache");
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 theonly-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
}
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<String, List<String>> requestHeaders)
Retrieve the cached response based on the requesting uri, request method and request headers. |
int
|
getHitCount()
Returns the number of HTTP requests whose response was provided by the cache. |
static
HttpResponseCache
|
getInstalled()
Returns the currently-installed |
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)
The protocol handler calls this method after a resource has been retrieved, and the ResponseCache must decide whether or not to store the resource in its cache. |
long
|
size()
Returns the number of bytes currently being used to store the values in this cache. |
Inherited methods | |
---|---|
Public methods
close
public void close ()
Uninstalls the cache and releases any active resources. Stored contents will remain on the filesystem.
Throws | |
---|---|
IOException |
delete
public void delete ()
Uninstalls the cache and deletes all of its stored contents.
Throws | |
---|---|
IOException |
flush
public void flush ()
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.
get
public CacheResponse get (URI uri, String requestMethod, Map<String, List<String>> requestHeaders)
Retrieve the cached response based on the requesting uri, request method and request headers. Typically this method is called by the protocol handler before it sends out the request to get the network resource. If a cached response is returned, that resource is used instead.
Parameters | |
---|---|
uri |
URI : a URI used to reference the requested
network resource |
requestMethod |
String : a String representing the request
method |
requestHeaders |
Map : - a Map from request header
field names to lists of field values representing
the current request headers |
Returns | |
---|---|
CacheResponse |
a CacheResponse instance if available
from cache, or null otherwise |
Throws | |
---|---|
IOException |
getHitCount
public int getHitCount ()
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.
Returns | |
---|---|
int |
getInstalled
public static HttpResponseCache getInstalled ()
Returns the currently-installed HttpResponseCache
, or null if
there is no cache installed or it is not a HttpResponseCache
.
Returns | |
---|---|
HttpResponseCache |
getNetworkCount
public int getNetworkCount ()
Returns the number of HTTP requests that required the network to either supply a response or validate a locally cached response.
Returns | |
---|---|
int |
getRequestCount
public int getRequestCount ()
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.
Returns | |
---|---|
int |
install
public static HttpResponseCache install (File directory, long maxSize)
Creates a new HTTP response cache and sets it as the system default cache.
Parameters | |
---|---|
directory |
File : the directory to hold cache data. |
maxSize |
long : the maximum size of the cache in bytes. |
Returns | |
---|---|
HttpResponseCache |
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. |
maxSize
public long maxSize ()
Returns the maximum number of bytes that this cache should use to store its data.
Returns | |
---|---|
long |
put
public CacheRequest put (URI uri, URLConnection urlConnection)
The protocol handler calls this method after a resource has been retrieved, and the ResponseCache must decide whether or not to store the resource in its cache. If the resource is to be cached, then put() must return a CacheRequest object which contains an OutputStream that the protocol handler will use to write the resource into the cache. If the resource is not to be cached, then put must return null.
Parameters | |
---|---|
uri |
URI : a URI used to reference the requested
network resource |
urlConnection |
URLConnection : - a URLConnection instance that is used to fetch
the response to be cached |
Returns | |
---|---|
CacheRequest |
a CacheRequest for recording the
response to be cached. Null return indicates that
the caller does not intend to cache the response. |
Throws | |
---|---|
IOException |
size
public long size ()
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. -1
is returned if the size cannot be determined.
Returns | |
---|---|
long |