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&nbsp;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      */
getDefault()83     public synchronized  static 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      */
setDefault(ResponseCache responseCache)106     public synchronized static 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
get(URI uri, String rqstMethod, Map<String, List<String>> rqstHeaders)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      */
put(URI uri, URLConnection conn)162     public abstract CacheRequest put(URI uri, URLConnection conn)  throws IOException;
163 }
164