1/*
2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.net;
27
28import java.io.IOException;
29import java.util.Map;
30import java.util.List;
31import sun.security.util.SecurityConstants;
32
33/**
34 * Represents implementations of URLConnection caches. An instance of
35 * such a class can be registered with the system by doing
36 * ResponseCache.setDefault(ResponseCache), and the system will call
37 * this object in order to:
38 *
39 *    <ul><li>store resource data which has been retrieved from an
40 *            external source into the cache</li>
41 *         <li>try to fetch a requested resource that may have been
42 *            stored in the cache</li>
43 *    </ul>
44 *
45 * The ResponseCache implementation decides which resources
46 * should be cached, and for how long they should be cached. If a
47 * request resource cannot be retrieved from the cache, then the
48 * protocol handlers will fetch the resource from its original
49 * location.
50 *
51 * The settings for URLConnection#useCaches controls whether the
52 * protocol is allowed to use a cached response.
53 *
54 * For more information on HTTP caching, see <a
55 * href="http://www.ietf.org/rfc/rfc2616.txt"><i>RFC&nbsp;2616: Hypertext
56 * Transfer Protocol -- HTTP/1.1</i></a>
57 *
58 * @author Yingxian Wang
59 * @since 1.5
60 */
61public abstract class ResponseCache {
62
63    /**
64     * The system wide cache that provides access to a url
65     * caching mechanism.
66     *
67     * @see #setDefault(ResponseCache)
68     * @see #getDefault()
69     */
70    private static ResponseCache theResponseCache;
71
72    /**
73     * Gets the system-wide response cache.
74     *
75     * @throws  SecurityException
76     *          If a security manager has been installed and it denies
77     * {@link NetPermission}{@code ("getResponseCache")}
78     *
79     * @see #setDefault(ResponseCache)
80     * @return the system-wide {@code ResponseCache}
81     * @since 1.5
82     */
83    public static synchronized ResponseCache getDefault() {
84        SecurityManager sm = System.getSecurityManager();
85        if (sm != null) {
86            sm.checkPermission(SecurityConstants.GET_RESPONSECACHE_PERMISSION);
87        }
88        return theResponseCache;
89    }
90
91    /**
92     * Sets (or unsets) the system-wide cache.
93     *
94     * Note: non-standard procotol handlers may ignore this setting.
95     *
96     * @param responseCache The response cache, or
97     *          {@code null} to unset the cache.
98     *
99     * @throws  SecurityException
100     *          If a security manager has been installed and it denies
101     * {@link NetPermission}{@code ("setResponseCache")}
102     *
103     * @see #getDefault()
104     * @since 1.5
105     */
106    public static synchronized void setDefault(ResponseCache responseCache) {
107        SecurityManager sm = System.getSecurityManager();
108        if (sm != null) {
109            sm.checkPermission(SecurityConstants.SET_RESPONSECACHE_PERMISSION);
110        }
111        theResponseCache = responseCache;
112    }
113
114    /**
115     * Retrieve the cached response based on the requesting uri,
116     * request method and request headers. Typically this method is
117     * called by the protocol handler before it sends out the request
118     * to get the network resource. If a cached response is returned,
119     * that resource is used instead.
120     *
121     * @param uri a {@code URI} used to reference the requested
122     *            network resource
123     * @param rqstMethod a {@code String} representing the request
124     *            method
125     * @param rqstHeaders - a Map from request header
126     *            field names to lists of field values representing
127     *            the current request headers
128     * @return a {@code CacheResponse} instance if available
129     *          from cache, or null otherwise
130     * @throws  IOException if an I/O error occurs
131     * @throws  IllegalArgumentException if any one of the arguments is null
132     *
133     * @see     java.net.URLConnection#setUseCaches(boolean)
134     * @see     java.net.URLConnection#getUseCaches()
135     * @see     java.net.URLConnection#setDefaultUseCaches(boolean)
136     * @see     java.net.URLConnection#getDefaultUseCaches()
137     */
138    public abstract CacheResponse
139        get(URI uri, String rqstMethod, Map<String, List<String>> rqstHeaders)
140        throws IOException;
141
142    /**
143     * The protocol handler calls this method after a resource has
144     * been retrieved, and the ResponseCache must decide whether or
145     * not to store the resource in its cache. If the resource is to
146     * be cached, then put() must return a CacheRequest object which
147     * contains an OutputStream that the protocol handler will
148     * use to write the resource into the cache. If the resource is
149     * not to be cached, then put must return null.
150     *
151     * @param uri a {@code URI} used to reference the requested
152     *            network resource
153     * @param conn - a URLConnection instance that is used to fetch
154     *            the response to be cached
155     * @return a {@code CacheRequest} for recording the
156     *            response to be cached. Null return indicates that
157     *            the caller does not intend to cache the response.
158     * @throws IOException if an I/O error occurs
159     * @throws IllegalArgumentException if any one of the arguments is
160     *            null
161     */
162    public abstract CacheRequest put(URI uri, URLConnection conn)  throws IOException;
163}
164