1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* Licensed to the Apache Software Foundation (ASF) under one or more 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contributor license agreements. See the NOTICE file distributed with 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this work for additional information regarding copyright ownership. 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The ASF licenses this file to You under the Apache License, Version 2.0 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (the "License"); you may not use this file except in compliance with 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the License. You may obtain a copy of the License at 7f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 9f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Unless required by applicable law or agreed to in writing, software 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See the License for the specific language governing permissions and 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitations under the License. 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.net; 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.IOException; 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.List; 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Map; 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 236247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * Caches {@code URLConnection} responses. 246247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * <p>The system's default cache can be set using {@link #setDefault}. 256247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * If {@link URLConnection#getUseCaches} returns true, {@code URLConnection} will use the 266247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * default response cache, if one has been set. 276247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * <p>Although {@code URLConnection} will always call {@link #put}, the specific 286247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * {@code ResponseCache} implementation gets to decide what will actually be cached, 296247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * and for how long. 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic abstract class ResponseCache { 326247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes private static ResponseCache defaultResponseCache = null; 33adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 34adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 356247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * Returns the system's default response cache, or null. 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public static ResponseCache getDefault() { 386247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes return defaultResponseCache; 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 426247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * Sets the system's default response cache. Use null to remove the response cache. 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public static void setDefault(ResponseCache responseCache) { 456247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes defaultResponseCache = responseCache; 46adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 47adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 48adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 496247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * Returns the cached response corresponding to the given request. 50f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 51adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param uri 526247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * the request URI. 536247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * @param requestMethod 546247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * the request method. 556247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * @param requestHeaders 566247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * a map of request headers. 57adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return the {@code CacheResponse} object if the request is available in the cache 58adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or {@code null} otherwise. 59adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IOException 60adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an I/O error occurs while getting the cached data. 61adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IllegalArgumentException 62adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if any one of the parameters is set to {@code null}. 63adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 646247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes public abstract CacheResponse get(URI uri, String requestMethod, 656247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes Map<String, List<String>> requestHeaders) throws IOException; 66adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 67adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 68adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Allows the protocol handler to cache data after retrieving resources. The 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code ResponseCache} decides whether the resource data should be cached 706247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * or not. If so, this method returns a {@code CacheRequest} to write the 716247987eb505a482a67f5f19678260d9e7240a5fElliott Hughes * resource data to. Otherwise, this method returns {@code null}. 72f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 73adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param uri 74adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the reference to the requested resource. 7537dcf5581f177229ca6c8e7d0d640361640bfb00Jesse Wilson * @param connection 76adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the connection to fetch the response. 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a CacheRequest object with a WriteableByteChannel if the resource 78adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * has to be cached, {@code null} otherwise. 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IOException 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an I/O error occurs while adding the resource. 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IllegalArgumentException 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if any one of the parameters is set to {@code null}. 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 8437dcf5581f177229ca6c8e7d0d640361640bfb00Jesse Wilson public abstract CacheRequest put(URI uri, URLConnection connection) throws IOException; 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 86