001: /*
002: * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.net;
027:
028: import java.io.IOException;
029: import java.util.Map;
030: import java.util.List;
031: import sun.security.util.SecurityConstants;
032:
033: /**
034: * Represents implementations of URLConnection caches. An instance of
035: * such a class can be registered with the system by doing
036: * ResponseCache.setDefault(ResponseCache), and the system will call
037: * this object in order to:
038: *
039: * <ul><li>store resource data which has been retrieved from an
040: * external source into the cache</li>
041: * <li>try to fetch a requested resource that may have been
042: * stored in the cache</li>
043: * </ul>
044: *
045: * The ResponseCache implementation decides which resources
046: * should be cached, and for how long they should be cached. If a
047: * request resource cannot be retrieved from the cache, then the
048: * protocol handlers will fetch the resource from its original
049: * location.
050: *
051: * The settings for URLConnection#useCaches controls whether the
052: * protocol is allowed to use a cached response.
053: *
054: * For more information on HTTP caching, see <a
055: * href="http://www.ietf.org/rfc/rfc2616.txt""><i>RFC 2616: Hypertext
056: * Transfer Protocol -- HTTP/1.1</i></a>
057: *
058: * @version 1.1, 03/09/22
059: * @author Yingxian Wang
060: * @since 1.5
061: */
062: public abstract class ResponseCache {
063:
064: /**
065: * The system wide cache that provides access to a url
066: * caching mechanism.
067: *
068: * @see #setDefault(ResponseCache)
069: * @see #getDefault()
070: */
071: private static ResponseCache theResponseCache;
072:
073: /**
074: * Gets the system-wide response cache.
075: *
076: * @throws SecurityException
077: * If a security manager has been installed and it denies
078: * {@link NetPermission}<tt>("getResponseCache")</tt>
079: *
080: * @see #setDefault(ResponseCache)
081: * @return the system-wide <code>ResponseCache</code>
082: * @since 1.5
083: */
084: public synchronized static ResponseCache getDefault() {
085: SecurityManager sm = System.getSecurityManager();
086: if (sm != null) {
087: sm
088: .checkPermission(SecurityConstants.GET_RESPONSECACHE_PERMISSION);
089: }
090: return theResponseCache;
091: }
092:
093: /**
094: * Sets (or unsets) the system-wide cache.
095: *
096: * Note: non-standard procotol handlers may ignore this setting.
097: *
098: * @param responseCache The response cache, or
099: * <code>null</code> to unset the cache.
100: *
101: * @throws SecurityException
102: * If a security manager has been installed and it denies
103: * {@link NetPermission}<tt>("setResponseCache")</tt>
104: *
105: * @see #getDefault()
106: * @since 1.5
107: */
108: public synchronized static void setDefault(
109: ResponseCache responseCache) {
110: SecurityManager sm = System.getSecurityManager();
111: if (sm != null) {
112: sm
113: .checkPermission(SecurityConstants.SET_RESPONSECACHE_PERMISSION);
114: }
115: theResponseCache = responseCache;
116: }
117:
118: /**
119: * Retrieve the cached response based on the requesting uri,
120: * request method and request headers. Typically this method is
121: * called by the protocol handler before it sends out the request
122: * to get the network resource. If a cached response is returned,
123: * that resource is used instead.
124: *
125: * @param uri a <code>URI</code> used to reference the requested
126: * network resource
127: * @param rqstMethod a <code>String</code> representing the request
128: * method
129: * @param rqstHeaders - a Map from request header
130: * field names to lists of field values representing
131: * the current request headers
132: * @return a <code>CacheResponse</code> instance if available
133: * from cache, or null otherwise
134: * @throws IOException if an I/O error occurs
135: * @throws IllegalArgumentException if any one of the arguments is null
136: *
137: * @see java.net.URLConnection#setUseCaches(boolean)
138: * @see java.net.URLConnection#getUseCaches()
139: * @see java.net.URLConnection#setDefaultUseCaches(boolean)
140: * @see java.net.URLConnection#getDefaultUseCaches()
141: */
142: public abstract CacheResponse get(URI uri, String rqstMethod,
143: Map<String, List<String>> rqstHeaders) throws IOException;
144:
145: /**
146: * The protocol handler calls this method after a resource has
147: * been retrieved, and the ResponseCache must decide whether or
148: * not to store the resource in its cache. If the resource is to
149: * be cached, then put() must return a CacheRequest object which
150: * contains an OutputStream that the protocol handler will
151: * use to write the resource into the cache. If the resource is
152: * not to be cached, then put must return null.
153: *
154: * @param uri a <code>URI</code> used to reference the requested
155: * network resource
156: * @param conn - a URLConnection instance that is used to fetch
157: * the response to be cached
158: * @return a <code>CacheRequest</code> for recording the
159: * response to be cached. Null return indicates that
160: * the caller does not intend to cache the response.
161: * @throws IOException if an I/O error occurs
162: * @throws IllegalArgumentException if any one of the arguments is
163: * null
164: */
165: public abstract CacheRequest put(URI uri, URLConnection conn)
166: throws IOException;
167: }
| 