1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.webkit; 18 19 import android.annotation.Nullable; 20 import android.compat.annotation.UnsupportedAppUsage; 21 22 import java.io.File; 23 import java.io.IOException; 24 import java.io.InputStream; 25 import java.io.OutputStream; 26 import java.util.Map; 27 28 /** 29 * Manages the HTTP cache used by an application's {@link WebView} instances. 30 * @deprecated Access to the HTTP cache will be removed in a future release. 31 * @hide Since {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 32 */ 33 // The class CacheManager provides the persistent cache of content that is 34 // received over the network. The component handles parsing of HTTP headers and 35 // utilizes the relevant cache headers to determine if the content should be 36 // stored and if so, how long it is valid for. Network requests are provided to 37 // this component and if they can not be resolved by the cache, the HTTP headers 38 // are attached, as appropriate, to the request for revalidation of content. The 39 // class also manages the cache size. 40 // 41 // CacheManager may only be used if your activity contains a WebView. 42 @Deprecated 43 public final class CacheManager { 44 /** 45 * Represents a resource stored in the HTTP cache. Instances of this class 46 * can be obtained by calling 47 * {@link CacheManager#getCacheFile CacheManager.getCacheFile(String, Map<String, String>))}. 48 * 49 * @deprecated Access to the HTTP cache will be removed in a future release. 50 */ 51 @Deprecated 52 public static class CacheResult { 53 54 @UnsupportedAppUsage CacheResult()55 public CacheResult() { 56 } 57 58 // these fields are saved to the database 59 @UnsupportedAppUsage 60 int httpStatusCode; 61 @UnsupportedAppUsage 62 long contentLength; 63 @UnsupportedAppUsage 64 long expires; 65 @UnsupportedAppUsage 66 String expiresString; 67 @UnsupportedAppUsage 68 String localPath; 69 @UnsupportedAppUsage 70 String lastModified; 71 @UnsupportedAppUsage 72 String etag; 73 @UnsupportedAppUsage 74 String mimeType; 75 @UnsupportedAppUsage 76 String location; 77 @UnsupportedAppUsage 78 String encoding; 79 @UnsupportedAppUsage 80 String contentdisposition; 81 @UnsupportedAppUsage 82 String crossDomain; 83 84 // these fields are NOT saved to the database 85 @UnsupportedAppUsage 86 InputStream inStream; 87 @UnsupportedAppUsage 88 OutputStream outStream; 89 @UnsupportedAppUsage 90 File outFile; 91 92 /** 93 * Gets the status code of this cache entry. 94 * 95 * @return the status code of this cache entry 96 */ 97 @UnsupportedAppUsage getHttpStatusCode()98 public int getHttpStatusCode() { 99 return httpStatusCode; 100 } 101 102 /** 103 * Gets the content length of this cache entry. 104 * 105 * @return the content length of this cache entry 106 */ 107 @UnsupportedAppUsage getContentLength()108 public long getContentLength() { 109 return contentLength; 110 } 111 112 /** 113 * Gets the path of the file used to store the content of this cache 114 * entry, relative to the base directory of the cache. See 115 * {@link CacheManager#getCacheFileBaseDir CacheManager.getCacheFileBaseDir()}. 116 * 117 * @return the path of the file used to store this cache entry 118 */ 119 @UnsupportedAppUsage getLocalPath()120 public String getLocalPath() { 121 return localPath; 122 } 123 124 /** 125 * Gets the expiry date of this cache entry, expressed in milliseconds 126 * since midnight, January 1, 1970 UTC. 127 * 128 * @return the expiry date of this cache entry 129 */ 130 @UnsupportedAppUsage getExpires()131 public long getExpires() { 132 return expires; 133 } 134 135 /** 136 * Gets the expiry date of this cache entry, expressed as a string. 137 * 138 * @return the expiry date of this cache entry 139 * 140 */ 141 @UnsupportedAppUsage getExpiresString()142 public String getExpiresString() { 143 return expiresString; 144 } 145 146 /** 147 * Gets the date at which this cache entry was last modified, expressed 148 * as a string. 149 * 150 * @return the date at which this cache entry was last modified 151 */ 152 @UnsupportedAppUsage getLastModified()153 public String getLastModified() { 154 return lastModified; 155 } 156 157 /** 158 * Gets the entity tag of this cache entry. 159 * 160 * @return the entity tag of this cache entry 161 */ 162 @UnsupportedAppUsage getETag()163 public String getETag() { 164 return etag; 165 } 166 167 /** 168 * Gets the MIME type of this cache entry. 169 * 170 * @return the MIME type of this cache entry 171 */ 172 @UnsupportedAppUsage getMimeType()173 public String getMimeType() { 174 return mimeType; 175 } 176 177 /** 178 * Gets the value of the HTTP 'Location' header with which this cache 179 * entry was received. 180 * 181 * @return the HTTP 'Location' header for this cache entry 182 */ 183 @UnsupportedAppUsage getLocation()184 public String getLocation() { 185 return location; 186 } 187 188 /** 189 * Gets the encoding of this cache entry. 190 * 191 * @return the encoding of this cache entry 192 */ 193 @UnsupportedAppUsage getEncoding()194 public String getEncoding() { 195 return encoding; 196 } 197 198 /** 199 * Gets the value of the HTTP 'Content-Disposition' header with which 200 * this cache entry was received. 201 * 202 * @return the HTTP 'Content-Disposition' header for this cache entry 203 * 204 */ 205 @UnsupportedAppUsage getContentDisposition()206 public String getContentDisposition() { 207 return contentdisposition; 208 } 209 210 /** 211 * Gets the input stream to the content of this cache entry, to allow 212 * content to be read. See 213 * {@link CacheManager#getCacheFile CacheManager.getCacheFile(String, Map<String, String>)}. 214 * 215 * @return an input stream to the content of this cache entry 216 */ 217 @UnsupportedAppUsage getInputStream()218 public InputStream getInputStream() { 219 return inStream; 220 } 221 222 /** 223 * Gets an output stream to the content of this cache entry, to allow 224 * content to be written. See 225 * {@link CacheManager#saveCacheFile CacheManager.saveCacheFile(String, CacheResult)}. 226 * 227 * @return an output stream to the content of this cache entry 228 */ 229 // Note that this is always null for objects returned by getCacheFile()! 230 @UnsupportedAppUsage getOutputStream()231 public OutputStream getOutputStream() { 232 return outStream; 233 } 234 235 236 /** 237 * Sets an input stream to the content of this cache entry. 238 * 239 * @param stream an input stream to the content of this cache entry 240 */ 241 @UnsupportedAppUsage setInputStream(InputStream stream)242 public void setInputStream(InputStream stream) { 243 this.inStream = stream; 244 } 245 246 /** 247 * Sets the encoding of this cache entry. 248 * 249 * @param encoding the encoding of this cache entry 250 */ 251 @UnsupportedAppUsage setEncoding(String encoding)252 public void setEncoding(String encoding) { 253 this.encoding = encoding; 254 } 255 256 /** 257 * @hide 258 */ setContentLength(long contentLength)259 public void setContentLength(long contentLength) { 260 this.contentLength = contentLength; 261 } 262 } 263 264 /** 265 * Gets the base directory in which the files used to store the contents of 266 * cache entries are placed. See 267 * {@link CacheManager.CacheResult#getLocalPath CacheManager.CacheResult.getLocalPath()}. 268 * 269 * @return the base directory of the cache 270 * @deprecated This method no longer has any effect and always returns {@code null}. 271 */ 272 @Deprecated 273 @Nullable 274 @UnsupportedAppUsage getCacheFileBaseDir()275 public static File getCacheFileBaseDir() { 276 return null; 277 } 278 279 /** 280 * Gets whether the HTTP cache is disabled. 281 * 282 * @return {@code true} if the HTTP cache is disabled 283 * @deprecated This method no longer has any effect and always returns {@code false}. 284 */ 285 @Deprecated 286 @UnsupportedAppUsage cacheDisabled()287 public static boolean cacheDisabled() { 288 return false; 289 } 290 291 /** 292 * Starts a cache transaction. Returns {@code true} if this is the only running 293 * transaction. Otherwise, this transaction is nested inside currently 294 * running transactions and {@code false} is returned. 295 * 296 * @return {@code true} if this is the only running transaction 297 * @deprecated This method no longer has any effect and always returns {@code false}. 298 */ 299 @Deprecated 300 @UnsupportedAppUsage startCacheTransaction()301 public static boolean startCacheTransaction() { 302 return false; 303 } 304 305 /** 306 * Ends the innermost cache transaction and returns whether this was the 307 * only running transaction. 308 * 309 * @return {@code true} if this was the only running transaction 310 * @deprecated This method no longer has any effect and always returns {@code false}. 311 */ 312 @Deprecated 313 @UnsupportedAppUsage endCacheTransaction()314 public static boolean endCacheTransaction() { 315 return false; 316 } 317 318 /** 319 * Gets the cache entry for the specified URL, or {@code null} if none is found. 320 * If a non-null value is provided for the HTTP headers map, and the cache 321 * entry needs validation, appropriate headers will be added to the map. 322 * The input stream of the CacheEntry object should be closed by the caller 323 * when access to the underlying file is no longer required. 324 * 325 * @param url the URL for which a cache entry is requested 326 * @param headers a map from HTTP header name to value, to be populated 327 * for the returned cache entry 328 * @return the cache entry for the specified URL 329 * @deprecated This method no longer has any effect and always returns {@code null}. 330 */ 331 @Deprecated 332 @Nullable 333 @UnsupportedAppUsage getCacheFile(String url, Map<String, String> headers)334 public static CacheResult getCacheFile(String url, 335 Map<String, String> headers) { 336 return null; 337 } 338 339 /** 340 * Adds a cache entry to the HTTP cache for the specicifed URL. Also closes 341 * the cache entry's output stream. 342 * 343 * @param url the URL for which the cache entry should be added 344 * @param cacheResult the cache entry to add 345 * @deprecated Access to the HTTP cache will be removed in a future release. 346 */ 347 @Deprecated 348 @UnsupportedAppUsage saveCacheFile(String url, CacheResult cacheResult)349 public static void saveCacheFile(String url, CacheResult cacheResult) { 350 saveCacheFile(url, 0, cacheResult); 351 } 352 353 @UnsupportedAppUsage saveCacheFile(String url, long postIdentifier, CacheResult cacheRet)354 static void saveCacheFile(String url, long postIdentifier, 355 CacheResult cacheRet) { 356 try { 357 cacheRet.outStream.close(); 358 } catch (IOException e) { 359 return; 360 } 361 362 // This method is exposed in the public API but the API provides no 363 // way to obtain a new CacheResult object with a non-null output 364 // stream ... 365 // - CacheResult objects returned by getCacheFile() have a null 366 // output stream. 367 // - new CacheResult objects have a null output stream and no 368 // setter is provided. 369 // Since this method throws a null pointer exception in this case, 370 // it is effectively useless from the point of view of the public 371 // API. 372 // 373 // With the Chromium HTTP stack we continue to throw the same 374 // exception for 'backwards compatibility' with the Android HTTP 375 // stack. 376 // 377 // This method is not used from within this package, and for public API 378 // use, we should already have thrown an exception above. 379 assert false; 380 } 381 } 382