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 */
16package java.net;
17
18import java.io.IOException;
19import java.util.List;
20import 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 */
31public abstract class ResponseCache {
32    private static ResponseCache defaultResponseCache = null;
33
34    /**
35     * Returns the system's default response cache, or null.
36     */
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     */
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     */
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     */
84    public abstract CacheRequest put(URI uri, URLConnection connection) throws IOException;
85}
86