001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package java.net;
017:
018: import java.io.IOException;
019: import java.util.List;
020: import java.util.Map;
021:
022: /**
023: * ResponseCache implements URLConnection caches. System default cache can be
024: * registered by invoking ResponseCache.<code>setDefault</code>(ResponseCache),
025: * and can be retrieved by invoking ResponseCache.<code>getDefault</code>.
026: * If URLConnection#useCaches is set, <code>URLConnection</code> class will
027: * use <code>ResponseCache</code> to store and get resources. Whether the
028: * resource is cached depends on <code>ResponseCache</code> implementation. If
029: * a request resource is cached, protocol handler will fecth it from the cache.
030: * If the protocol handler fails to get resource from the cache, it turns to get
031: * the resource from its original location.
032: */
033: public abstract class ResponseCache {
034:
035: /*
036: * _defaultResponseCache is used to store default response cache.
037: */
038: private static ResponseCache _defaultResponseCache = null;
039:
040: /*
041: * "getResponseCache" permission. getDefault method requires this
042: * permission.
043: */
044: private static NetPermission getResponseCachepermission = new NetPermission(
045: "getResponseCache"); //$NON-NLS-1$
046:
047: /*
048: * "setResponseCache" permission. setDefault method requires this
049: * permission.
050: */
051: private static NetPermission setResponseCachepermission = new NetPermission(
052: "setResponseCache"); //$NON-NLS-1$
053:
054: /*
055: * check getResponseCache permission. getDefault method requires
056: * "getResponseCache" permission if a security manager is installed.
057: */
058: private static void checkGetResponseCachePermission() {
059: SecurityManager sm = System.getSecurityManager();
060: if (null != sm) {
061: sm.checkPermission(getResponseCachepermission);
062: }
063: }
064:
065: /*
066: * check setResponseCache permission. setDefault method requires
067: * "setResponseCache" permission if a security manager is installed.
068: */
069: private static void checkSetResponseCachePermission() {
070: SecurityManager sm = System.getSecurityManager();
071: if (null != sm) {
072: sm.checkPermission(setResponseCachepermission);
073: }
074: }
075:
076: /**
077: * Constructor method.
078: */
079: public ResponseCache() {
080: super ();
081: }
082:
083: /**
084: * Gets system default response cache.
085: *
086: * @return default <code>ResponseCache</code>.
087: * @throws SecurityException
088: * If a security manager is installed and it doesn't have
089: * <code>NetPermission</code>("getResponseCache").
090: */
091: public static ResponseCache getDefault() {
092: checkGetResponseCachePermission();
093: return _defaultResponseCache;
094: }
095:
096: /**
097: * Sets the system default response cache when responseCache is not null.
098: * Otherwise, the method unsets the system default response cache. This
099: * setting may be ignored by some non-standard protocols.
100: *
101: * @param responseCache
102: * Set default <code>ResponseCache</code>. If responseCache is
103: * null, it unsets the cache.
104: * @throws SecurityException
105: * If a security manager is installed and it doesn't have
106: * <code>NetPermission</code>("setResponseCache").
107: */
108: public static void setDefault(ResponseCache responseCache) {
109: checkSetResponseCachePermission();
110: _defaultResponseCache = responseCache;
111: }
112:
113: /**
114: * Gets the cached response according to requesting uri,method and headers.
115: *
116: * @param uri
117: * A <code>URL</code> represents requesting uri.
118: * @param rqstMethod
119: * A <code>String</code> represents requesting method.
120: * @param rqstHeaders
121: * A <code>Map</code> from request header field names to lists
122: * of field values represents requesting headers.
123: * @return A <code>CacheResponse</code> object if the request is available
124: * in the cache. Otherwise, this method returns null.
125: * @throws IOException
126: * If an I/O error is encountered.
127: * @throws IllegalArgumentException
128: * If any one of the parameters is null
129: */
130: public abstract CacheResponse get(URI uri, String rqstMethod,
131: Map<String, List<String>> rqstHeaders) throws IOException;
132:
133: /**
134: * Protocol handler calls this method after retrieving resources. The
135: * <code>ResponseCache</code> decides whether the resource should be
136: * cached. If the resource needs to be cached, this method will return a
137: * <code>CacheRequest</code> with a <code>WriteableByteChannel</code>,
138: * and then, protocol handler will use this channel to write the resource
139: * data into the cache. Otherwise, if the resource doesn't need to be
140: * cached, it returns null.
141: *
142: * @param uri
143: * @param conn
144: * @return a <code>CacheRequest</code> which contains
145: * <code>WriteableByteChannel</code> if the resource is cached.
146: * Otherwise, it returns null.
147: * @throws IOException
148: * If an I/O error is encountered.
149: * @throws IllegalArgumentException
150: * If any one of the parameters is null.
151: */
152: public abstract CacheRequest put(URI uri, URLConnection conn)
153: throws IOException;
154: }
|