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