Java tutorial
/* * 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(); } }