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
26 package java.net;
27
28 import java.io.IOException;
29 import java.util.Map;
30 import java.util.List;
31 import 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 2616: Hypertext
56 * Transfer Protocol -- HTTP/1.1</i></a>
57 *
58 * @author Yingxian Wang
59 * @since 1.5
60 */
61 public 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 }