303 lines
12 KiB
Java
303 lines
12 KiB
Java
/*
|
|
* Copyright (C) 2011 The Android Open Source Project
|
|
*
|
|
* Licensed 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.
|
|
*/
|
|
|
|
package android.net.http;
|
|
|
|
import com.android.okhttp.internalandroidapi.AndroidResponseCacheAdapter;
|
|
import com.android.okhttp.internalandroidapi.HasCacheHolder;
|
|
|
|
import java.io.Closeable;
|
|
import java.io.File;
|
|
import java.io.IOException;
|
|
import java.net.CacheRequest;
|
|
import java.net.CacheResponse;
|
|
import java.net.ResponseCache;
|
|
import java.net.URI;
|
|
import java.net.URLConnection;
|
|
import java.util.List;
|
|
import java.util.Map;
|
|
|
|
/**
|
|
* Caches HTTP and HTTPS responses to the filesystem so they may be reused,
|
|
* saving time and bandwidth. This class supports {@link
|
|
* java.net.HttpURLConnection} and {@link javax.net.ssl.HttpsURLConnection};
|
|
* there is no platform-provided cache for {@code DefaultHttpClient} or
|
|
* {@code AndroidHttpClient}. Installation and instances are thread
|
|
* safe.
|
|
*
|
|
* <h3>Installing an HTTP response cache</h3>
|
|
* 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 {@link android.content.Context#getCacheDir() application-specific
|
|
* cache directory} of the filesystem}: <pre> {@code
|
|
* 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();
|
|
* }
|
|
* }}</pre>
|
|
* 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!
|
|
*
|
|
* <p>For some applications it may be preferable to create the cache in the
|
|
* external storage directory. <strong>There are no access controls on the
|
|
* external storage directory so it should not be used for caches that could
|
|
* contain private data.</strong> 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 {@link
|
|
* android.content.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.
|
|
*
|
|
* <p>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.
|
|
*
|
|
* <h3>Cache Optimization</h3>
|
|
* To measure cache effectiveness, this class tracks three statistics:
|
|
* <ul>
|
|
* <li><strong>{@link #getRequestCount() Request Count:}</strong> the number
|
|
* of HTTP requests issued since this cache was created.
|
|
* <li><strong>{@link #getNetworkCount() Network Count:}</strong> the
|
|
* number of those requests that required network use.
|
|
* <li><strong>{@link #getHitCount() Hit Count:}</strong> the number of
|
|
* those requests whose responses were served by the cache.
|
|
* </ul>
|
|
* 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
|
|
* {@code 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.
|
|
*
|
|
* <p>The best way to improve the cache hit rate is by configuring the web
|
|
* server to return cacheable responses. Although this client honors all <a
|
|
* href="http://www.ietf.org/rfc/rfc2616.txt">HTTP/1.1 (RFC 2068)</a> cache
|
|
* headers, it doesn't cache partial responses.
|
|
*
|
|
* <h3>Force a Network Response</h3>
|
|
* 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 {@code no-cache} directive: <pre> {@code
|
|
* connection.addRequestProperty("Cache-Control", "no-cache");
|
|
* }</pre>
|
|
* If it is only necessary to force a cached response to be validated by the
|
|
* server, use the more efficient {@code max-age=0} instead: <pre> {@code
|
|
* connection.addRequestProperty("Cache-Control", "max-age=0");
|
|
* }</pre>
|
|
*
|
|
* <h3>Force a Cache Response</h3>
|
|
* Sometimes you'll want to show resources if they are available immediately,
|
|
* but not otherwise. This can be used so your application can show
|
|
* <i>something</i> while waiting for the latest data to be downloaded. To
|
|
* restrict a request to locally-cached resources, add the {@code
|
|
* only-if-cached} directive: <pre> {@code
|
|
* 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
|
|
* }
|
|
* }</pre>
|
|
* This technique works even better in situations where a stale response is
|
|
* better than no response. To permit stale cached responses, use the {@code
|
|
* max-stale} directive with the maximum staleness in seconds: <pre> {@code
|
|
* int maxStale = 60 * 60 * 24 * 28; // tolerate 4-weeks stale
|
|
* connection.addRequestProperty("Cache-Control", "max-stale=" + maxStale);
|
|
* }</pre>
|
|
*
|
|
* <h3>Working With Earlier Releases</h3>
|
|
* This class was added in Android 4.0 (Ice Cream Sandwich). Use reflection to
|
|
* enable the response cache without impacting earlier releases: <pre> {@code
|
|
* 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) {
|
|
* }}</pre>
|
|
*/
|
|
public final class HttpResponseCache extends ResponseCache implements HasCacheHolder, Closeable {
|
|
|
|
private final AndroidResponseCacheAdapter mDelegate;
|
|
|
|
private HttpResponseCache(AndroidResponseCacheAdapter delegate) {
|
|
mDelegate = delegate;
|
|
}
|
|
|
|
/**
|
|
* Returns the currently-installed {@code HttpResponseCache}, or null if
|
|
* there is no cache installed or it is not a {@code HttpResponseCache}.
|
|
*/
|
|
public static HttpResponseCache getInstalled() {
|
|
ResponseCache installed = ResponseCache.getDefault();
|
|
if (installed instanceof HttpResponseCache) {
|
|
return (HttpResponseCache) installed;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Creates a new HTTP response cache and sets it as the system default cache.
|
|
*
|
|
* @param directory the directory to hold cache data.
|
|
* @param maxSize the maximum size of the cache in bytes.
|
|
* @return the newly-installed cache
|
|
* @throws IOException if {@code directory} cannot be used for this cache.
|
|
* Most applications should respond to this exception by logging a
|
|
* warning.
|
|
*/
|
|
public static synchronized HttpResponseCache install(File directory, long maxSize)
|
|
throws IOException {
|
|
ResponseCache installed = ResponseCache.getDefault();
|
|
if (installed instanceof HttpResponseCache) {
|
|
HttpResponseCache installedResponseCache = (HttpResponseCache) installed;
|
|
CacheHolder cacheHolder = installedResponseCache.getCacheHolder();
|
|
// don't close and reopen if an equivalent cache is already installed
|
|
if (cacheHolder.isEquivalent(directory, maxSize)) {
|
|
return installedResponseCache;
|
|
} else {
|
|
// The HttpResponseCache that owns this object is about to be replaced.
|
|
installedResponseCache.close();
|
|
}
|
|
}
|
|
|
|
CacheHolder cacheHolder = CacheHolder.create(directory, maxSize);
|
|
AndroidResponseCacheAdapter androidResponseCacheAdapter =
|
|
new AndroidResponseCacheAdapter(cacheHolder);
|
|
HttpResponseCache responseCache = new HttpResponseCache(androidResponseCacheAdapter);
|
|
ResponseCache.setDefault(responseCache);
|
|
return responseCache;
|
|
}
|
|
|
|
@Override
|
|
public CacheResponse get(URI uri, String requestMethod,
|
|
Map<String, List<String>> requestHeaders) throws IOException {
|
|
return mDelegate.get(uri, requestMethod, requestHeaders);
|
|
}
|
|
|
|
@Override
|
|
public CacheRequest put(URI uri, URLConnection urlConnection) throws IOException {
|
|
return mDelegate.put(uri, urlConnection);
|
|
}
|
|
|
|
/**
|
|
* Returns the number of bytes currently being used to store the values in
|
|
* this cache. This may be greater than the {@link #maxSize} if a background
|
|
* deletion is pending. {@code -1} is returned if the size cannot be determined.
|
|
*/
|
|
public long size() {
|
|
try {
|
|
return mDelegate.getSize();
|
|
} catch (IOException e) {
|
|
// This can occur if the cache failed to lazily initialize.
|
|
return -1;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns the maximum number of bytes that this cache should use to store
|
|
* its data.
|
|
*/
|
|
public long maxSize() {
|
|
return mDelegate.getMaxSize();
|
|
}
|
|
|
|
/**
|
|
* 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 void flush() {
|
|
try {
|
|
mDelegate.flush();
|
|
} catch (IOException ignored) {
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns the number of HTTP requests that required the network to either
|
|
* supply a response or validate a locally cached response.
|
|
*/
|
|
public int getNetworkCount() {
|
|
return mDelegate.getNetworkCount();
|
|
}
|
|
|
|
/**
|
|
* Returns the number of HTTP requests whose response was provided by the
|
|
* cache. This may include conditional {@code GET} requests that were
|
|
* validated over the network.
|
|
*/
|
|
public int getHitCount() {
|
|
return mDelegate.getHitCount();
|
|
}
|
|
|
|
/**
|
|
* 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 int getRequestCount() {
|
|
return mDelegate.getRequestCount();
|
|
}
|
|
|
|
/**
|
|
* Uninstalls the cache and releases any active resources. Stored contents
|
|
* will remain on the filesystem.
|
|
*/
|
|
@Override
|
|
public void close() throws IOException {
|
|
if (ResponseCache.getDefault() == this) {
|
|
ResponseCache.setDefault(null);
|
|
}
|
|
mDelegate.close();
|
|
}
|
|
|
|
/**
|
|
* Uninstalls the cache and deletes all of its stored contents.
|
|
*/
|
|
public void delete() throws IOException {
|
|
if (ResponseCache.getDefault() == this) {
|
|
ResponseCache.setDefault(null);
|
|
}
|
|
mDelegate.delete();
|
|
}
|
|
|
|
/** @hide Needed for OkHttp integration. */
|
|
@Override
|
|
public CacheHolder getCacheHolder() {
|
|
return mDelegate.getCacheHolder();
|
|
}
|
|
}
|