KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > net > ResponseCache


1 /*
2  * @(#)ResponseCache.java 1.1 03/09/22
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.net;
9
10 import java.io.IOException JavaDoc;
11 import java.util.Map JavaDoc;
12 import java.util.List JavaDoc;
13 import sun.security.util.SecurityConstants;
14
15 /**
16  * Represents implementations of URLConnection caches. An instance of
17  * such a class can be registered with the system by doing
18  * ResponseCache.setDefault(ResponseCache), and the system will call
19  * this object in order to:
20  *
21  * <ul><li>store resource data which has been retrieved from an
22  * external source into the cache</li>
23  * <li>try to fetch a requested resource that may have been
24  * stored in the cache</li>
25  * </ul>
26  *
27  * The ResponseCache implementation decides which resources
28  * should be cached, and for how long they should be cached. If a
29  * request resource cannot be retrieved from the cache, then the
30  * protocol handlers will fetch the resource from its original
31  * location.
32  *
33  * The settings for URLConnection#useCaches controls whether the
34  * protocol is allowed to use a cached response.
35  *
36  * For more information on HTTP caching, see <a
37  * HREF="http://www.ietf.org/rfc/rfc2616.txt""><i>RFC&nbsp;2616: Hypertext
38  * Transfer Protocol -- HTTP/1.1</i></a>
39  *
40  * @version 1.1, 03/09/22
41  * @author Yingxian Wang
42  * @since 1.5
43  */
44 public abstract class ResponseCache {
45
46     /**
47      * The system wide cache that provides access to a url
48      * caching mechanism.
49      *
50      * @see #setDefault(ResponseCache)
51      * @see #getDefault()
52      */
53     private static ResponseCache JavaDoc theResponseCache;
54
55     /**
56      * Gets the system-wide response cache.
57      *
58      * @throws SecurityException
59      * If a security manager has been installed and it denies
60      * {@link NetPermission}<tt>("getResponseCache")</tt>
61      *
62      * @see #setDefault(ResponseCache)
63      * @return the system-wide <code>ResponseCache</code>
64      * @since 1.5
65      */
66     public synchronized static ResponseCache JavaDoc getDefault() {
67     SecurityManager JavaDoc sm = System.getSecurityManager();
68     if (sm != null) {
69         sm.checkPermission(SecurityConstants.GET_RESPONSECACHE_PERMISSION);
70     }
71     return theResponseCache;
72     }
73
74     /**
75      * Sets (or unsets) the system-wide cache.
76      *
77      * Note: non-standard procotol handlers may ignore this setting.
78      *
79      * @param responseCache The response cache, or
80      * <code>null</code> to unset the cache.
81      *
82      * @throws SecurityException
83      * If a security manager has been installed and it denies
84      * {@link NetPermission}<tt>("setResponseCache")</tt>
85      *
86      * @see #getDefault()
87      * @since 1.5
88      */
89     public synchronized static void setDefault(ResponseCache JavaDoc responseCache) {
90     SecurityManager JavaDoc sm = System.getSecurityManager();
91     if (sm != null) {
92         sm.checkPermission(SecurityConstants.SET_RESPONSECACHE_PERMISSION);
93     }
94     theResponseCache = responseCache;
95     }
96
97     /**
98      * Retrieve the cached response based on the requesting uri,
99      * request method and request headers. Typically this method is
100      * called by the protocol handler before it sends out the request
101      * to get the network resource. If a cached response is returned,
102      * that resource is used instead.
103      *
104      * @param uri a <code>URI</code> used to reference the requested
105      * network resource
106      * @param rqstMethod a <code>String</code> representing the request
107      * method
108      * @param rqstHeaders - a Map from request header
109      * field names to lists of field values representing
110      * the current request headers
111      * @return a <code>CacheResponse</code> instance if available
112      * from cache, or null otherwise
113      * @throws IOException if an I/O error occurs
114      * @throws IllegalArgumentException if any one of the arguments is null
115      *
116      * @see java.net.URLConnection#setUseCaches(boolean)
117      * @see java.net.URLConnection#getUseCaches()
118      * @see java.net.URLConnection#setDefaultUseCaches(boolean)
119      * @see java.net.URLConnection#getDefaultUseCaches()
120      */
121     public abstract CacheResponse JavaDoc
122     get(URI JavaDoc uri, String JavaDoc rqstMethod, Map JavaDoc<String JavaDoc, List JavaDoc<String JavaDoc>> rqstHeaders)
123     throws IOException JavaDoc;
124
125     /**
126      * The protocol handler calls this method after a resource has
127      * been retrieved, and the ResponseCache must decide whether or
128      * not to store the resource in its cache. If the resource is to
129      * be cached, then put() must return a CacheRequest object which
130      * contains a WriteableByteChannel that the protocol handler will
131      * use to write the resource into the cache. If the resource is
132      * not to be cached, then put must return null.
133      *
134      * @param uri a <code>URI</code> used to reference the requested
135      * network resource
136      * @param conn - a URLConnection instance that is used to fetch
137      * the response to be cached
138      * @return a <code>CacheRequest</code> for recording the
139      * response to be cached. Null return indicates that
140      * the caller does not intend to cache the response.
141      * @throws IOException if an I/O error occurs
142      * @throws IllegalArgumentException if any one of the arguments is
143      * null
144      */
145     public abstract CacheRequest JavaDoc put(URI JavaDoc uri, URLConnection JavaDoc conn) throws IOException JavaDoc;
146 }
147
Popular Tags